feat(spm): fold Hermes public headers into ReactNativeHeaders

Libraries that use the Hermes C++ API (worklets' WorkletHermesRuntime →
`#include <hermes/hermes.h>`) failed to build under SPM: the Hermes public
headers were never vended. They ARE shipped — the hermes-ios Maven tarball
carries them in `destroot/include/hermes` (46 headers incl. hermes.h) alongside
the framework — but `extractXCFramework` keeps only the `.xcframework` and
discards the rest. So the headers were downloaded and thrown away.

Fix: stop discarding them, and fold the `hermes/` namespace into
ReactNativeHeaders (the headers-only artifact already auto-served as a search
path on every RN-linking target — same place jsi/folly/glog live). This makes
`<hermes/...>` resolve everywhere with zero per-library wiring. Only `hermes/`
is vended — `jsi/` is already provided, so it isn't re-copied (no double-vend).

- download-spm-artifacts.js: on hermes extraction, stage `destroot/include/
  hermes` → `<slot>/hermes-headers/hermes`. Self-heal for already-extracted
  slots (the fast path skips extraction): backfill from the cached tarball,
  downloading only as a last resort. validateArtifactsCache now requires the
  staged headers, so an older slot re-runs the (network-free) backfill.
- zero-i-compose.js: buildReactNativeHeadersXcframework takes an optional
  hermesHeaders source and folds the `hermes/` namespace in (textual, like
  folly — no clang module); ensureZeroILayout locates the staged headers in the
  slot and includes their presence in the freshness marker so a slot that gains
  them recomposes.
- xcframework.js: note where the prebuild publish path should pass the hermes
  include dir when that (gated) pipeline is productionized.

Serves both forms through the single buildReactNativeHeadersXcframework path:
the consumer self-compose (active today) and the eventually-published artifact.

Verified end-to-end: `spm update` on a real app stages the headers from the
cached tarball (no network) and recomposes ReactNativeHeaders with the `hermes`
namespace (Headers/hermes/hermes.h present); the reanimated/worklets build now
compiles past `<hermes/hermes.h>`. 332 spm tests still pass. (The build next
hits a separate prefix-header gap — worklets ObjC files using NSThread/UIKit
without importing Foundation — tracked separately.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: chrfalch

packages/react-native/scripts/ios-prebuild/xcframework.js

@@ -215,6 +215,12 @@ function buildXCFrameworks(
     );
     const plan = computeSpecPlan(rootFolder);
     emitReactFrameworkHeaders(outputPath, plan, rootFolder);
+    // NOTE: the Hermes public headers (`<hermes/...>`) are folded into
+    // ReactNativeHeaders on the consumer side by zero-i-compose's
+    // ensureZeroILayout (it stages them from the hermes-ios tarball via
+    // download-spm-artifacts). When this prebuild publish path is
+    // productionized, pass the prebuild's hermes `destroot/include` dir as the
+    // 6th arg so the PUBLISHED ReactNativeHeaders carries hermes too.
     zeroIHeadersXcfw = buildReactNativeHeadersXcframework(
       path.dirname(outputPath),
       plan,

packages/react-native/scripts/ios-prebuild/zero-i-compose.js

@@ -141,6 +141,13 @@ function buildReactNativeHeadersXcframework(
   depsHeaders /*: string */,
   rnRoot /*: string */,
   includeCatalyst /*: boolean */ = false,
+  // Optional dir containing a `hermes/` namespace (the Hermes public C++ API
+  // headers, `destroot/include` from the hermes-ios tarball). Folded in as a
+  // textual namespace — like folly/glog, no clang module — so `<hermes/...>`
+  // resolves for any RN-linking target without per-library wiring. null when
+  // the Hermes headers aren't staged (then `<hermes/...>` stays unavailable,
+  // i.e. the pre-fold behavior).
+  hermesHeaders /*: ?string */ = null,
 ) /*: string */ {
   // ---- stage headers ----
   const stage = fs.mkdtempSync(path.join(outDir, '.rnh-stage-'));
@@ -157,6 +164,20 @@ function buildReactNativeHeadersXcframework(
       console.warn(`zero-i-compose: deps namespace missing: ${ns}`);
     }
   }
+  // Hermes public headers (separate source from the deps namespaces — they
+  // come from the hermes-ios tarball, not ReactNativeDependencies). Vend only
+  // the `hermes/` namespace; `jsi/` is already provided elsewhere, so copying
+  // it here would double-vend.
+  let hermesFolded = false;
+  if (hermesHeaders != null) {
+    const src = path.join(hermesHeaders, 'hermes');
+    if (fs.existsSync(src)) {
+      execSync(`/bin/cp -Rc "${src}" "${path.join(stage, 'hermes')}"`);
+      hermesFolded = true;
+    } else {
+      console.warn(`zero-i-compose: hermes headers missing at ${src}`);
+    }
+  }
   fs.writeFileSync(
     path.join(stage, 'module.modulemap'),
     renderNamespaceModuleMap(plan.namespaceModules),
@@ -208,7 +229,8 @@ function buildReactNativeHeadersXcframework(
   fs.rmSync(work, {recursive: true, force: true});
   console.log(
     `zero-i-compose: ReactNativeHeaders.xcframework (${slices.map(s => s.name).join(', ')}) -> ${outXcfw} ` +
-      `(${plan.reactNativeHeaders.length} RN headers + deps ${plan.depsNamespaces.join(', ')}; ` +
+      `(${plan.reactNativeHeaders.length} RN headers + deps ${plan.depsNamespaces.join(', ')}` +
+      `${hermesFolded ? ', hermes' : ''}; ` +
       `${Object.keys(plan.namespaceModules).length} namespace modules)`,
   );
   return outXcfw;
@@ -240,12 +262,23 @@ function ensureZeroILayout(
     'ReactNativeDependencies.xcframework',
     'Headers',
   );
+  // Hermes public headers staged into the slot by download-spm-artifacts
+  // (the hermes-ios tarball ships them in destroot/include, which the
+  // xcframework extraction otherwise discards). null when absent — then
+  // ReactNativeHeaders composes without the hermes namespace.
+  const hermesHeadersDir = path.join(artifactsDir, 'hermes-headers');
+  const hermesHeaders = fs.existsSync(path.join(hermesHeadersDir, 'hermes'))
+    ? hermesHeadersDir
+    : null;
   const reactXcfw = path.join(outDir, 'React.xcframework');
   const headersXcfw = path.join(outDir, 'ReactNativeHeaders.xcframework');
   const markerPath = path.join(outDir, '.composed-from');
 
   const sourceStat = fs.statSync(path.join(sourceXcfw, 'Info.plist'));
-  const marker = `${sourceXcfw}\n${sourceStat.mtimeMs}\n`;
+  // Fold the hermes-headers presence into the marker so a slot that gains
+  // staged hermes headers (e.g. after a tooling upgrade re-downloads them)
+  // recomposes instead of reusing a hermes-less ReactNativeHeaders.
+  const marker = `${sourceXcfw}\n${sourceStat.mtimeMs}\n${hermesHeaders ?? 'no-hermes'}\n`;
   if (
     !force &&
     fs.existsSync(reactXcfw) &&
@@ -270,7 +303,14 @@ function ensureZeroILayout(
 
   const plan = computeSpecPlan(rnRoot);
   emitReactFrameworkHeaders(reactXcfw, plan, rnRoot);
-  buildReactNativeHeadersXcframework(outDir, plan, depsHeaders, rnRoot);
+  buildReactNativeHeadersXcframework(
+    outDir,
+    plan,
+    depsHeaders,
+    rnRoot,
+    false,
+    hermesHeaders,
+  );
   fs.writeFileSync(markerPath, marker);
   return {reactXcfw, headersXcfw};
 }

packages/react-native/scripts/spm/download-spm-artifacts.js

@@ -621,6 +621,86 @@ function findFirst(
   return null;
 }
 
+/**
+ * The hermes-ios tarball ships its public C++ API headers in
+ * `destroot/include/hermes` alongside the framework — which extractXCFramework
+ * discards (it keeps only the .xcframework). Stage the `hermes/` namespace into
+ * `<outputDir>/hermes-headers/hermes` so zero-i-compose can fold it into
+ * ReactNativeHeaders (making `<hermes/hermes.h>` resolve for any RN-linking
+ * target). Only `hermes/` is staged — `jsi/` is already vended elsewhere.
+ * Best-effort: a tarball without these headers just leaves hermes unavailable.
+ */
+function stageHermesHeaders(
+  extractDir /*: string */,
+  outputDir /*: string */,
+) /*: void */ {
+  let includeDir = path.join(extractDir, 'destroot', 'include');
+  if (!fs.existsSync(path.join(includeDir, 'hermes', 'hermes.h'))) {
+    // Fall back to locating the include dir wherever it landed in the tarball.
+    const hit = findFirst(extractDir, name => name === 'include', 8);
+    if (hit != null) {
+      includeDir = hit;
+    }
+  }
+  const src = path.join(includeDir, 'hermes');
+  if (!fs.existsSync(path.join(src, 'hermes.h'))) {
+    log('  Hermes public headers not found in tarball — skipping header stage');
+    return;
+  }
+  const destRoot = path.join(outputDir, 'hermes-headers');
+  const dest = path.join(destRoot, 'hermes');
+  fs.rmSync(dest, {recursive: true, force: true});
+  fs.mkdirSync(destRoot, {recursive: true});
+  execSync(`/bin/cp -R "${src}" "${dest}"`, {stdio: 'pipe'});
+  log('  Staged Hermes public headers → hermes-headers/hermes');
+}
+
+/**
+ * Self-heal: stage Hermes headers into an already-extracted slot (the fast
+ * path skips extraction, so the headers were never staged). Prefers a CACHED
+ * hermes tarball (no network); downloads only as a last resort so the slot
+ * can't get stuck "incomplete" forever. No-op only when the headers can't be
+ * obtained at all (e.g. a missing local-tarball override).
+ */
+async function ensureHermesHeadersStaged(
+  url /*: string */,
+  downloadDir /*: string */,
+  sharedTarballName /*: ?string */,
+  outputDir /*: string */,
+) /*: Promise<void> */ {
+  const candidates = [
+    !/^https?:\/\//.test(url) ? url : null, // local-tarball override
+    path.join(downloadDir, url.split('/').pop() ?? ''),
+    sharedTarballName != null
+      ? path.join(sharedCacheDir(), sharedTarballName)
+      : null,
+  ].filter(Boolean);
+  let tarPath /*: ?string */ = candidates.find(
+    p => p != null && fs.existsSync(p),
+  );
+  if (tarPath == null) {
+    if (!/^https?:\/\//.test(url)) {
+      return; // local override missing — nothing to recover from
+    }
+    const localPath = path.join(
+      downloadDir,
+      url.split('/').pop() ?? 'hermes.tar.gz',
+    );
+    fs.mkdirSync(downloadDir, {recursive: true});
+    await download(url, localPath);
+    tarPath = localPath;
+  }
+  const tmp = path.join(outputDir, '.hermes-hdr-tmp');
+  fs.rmSync(tmp, {recursive: true, force: true});
+  fs.mkdirSync(tmp, {recursive: true});
+  try {
+    execSync(`tar -xzf "${tarPath}" -C "${tmp}"`, {stdio: 'pipe'});
+    stageHermesHeaders(tmp, outputDir);
+  } finally {
+    fs.rmSync(tmp, {recursive: true, force: true});
+  }
+}
+
 /**
  * Downloads a tarball, extracts the xcframework, and places it directly in
  * the output directory as <xcframeworkName>.xcframework/.
@@ -661,6 +741,23 @@ async function processArtifact(
     } else {
       log(`  Already extracted: ${xcframeworkName}.xcframework`);
     }
+    // The xcframework is cached, but a slot from older tooling won't have the
+    // Hermes headers staged. Backfill them from a cached tarball (no network).
+    if (
+      label === 'hermes' &&
+      !fs.existsSync(path.join(outputDir, 'hermes-headers', 'hermes'))
+    ) {
+      try {
+        await ensureHermesHeadersStaged(
+          url,
+          downloadDir,
+          sharedTarballName,
+          outputDir,
+        );
+      } catch (e) {
+        log(`  Hermes header backfill failed (${e.message}) — continuing`);
+      }
+    }
     return {label, version, xcframeworkPath: destXcfwPath, url};
   }
 
@@ -750,6 +847,17 @@ async function processArtifact(
     fs.renameSync(xcfwPath, destXcfwPath);
   }
 
+  // Hermes ships its public headers in the same tarball; stage them next to
+  // the xcframeworks so zero-i-compose can fold `hermes/` into
+  // ReactNativeHeaders. (Other artifacts have no such headers — no-op.)
+  if (label === 'hermes') {
+    try {
+      stageHermesHeaders(tmpExtractDir, outputDir);
+    } catch (e) {
+      log(`  Hermes header staging failed (${e.message}) — continuing`);
+    }
+  }
+
   fs.rmSync(tmpExtractDir, {recursive: true, force: true});
 
   return {label, version, xcframeworkPath: destXcfwPath, url};
@@ -1023,6 +1131,14 @@ function validateArtifactsCache(
       return `xcframework for "${name}" not found at ${entry.xcframeworkPath}`;
     }
   }
+  // The Hermes public headers must be staged for zero-i-compose to fold
+  // `<hermes/...>` into ReactNativeHeaders. A slot from older tooling won't
+  // have them — report incomplete so ensureArtifacts re-runs the download
+  // (which, with the xcframeworks already present, only backfills the headers
+  // from the cached tarball — no network re-download).
+  if (!fs.existsSync(path.join(artifactsDir, 'hermes-headers', 'hermes'))) {
+    return 'Hermes public headers not staged (hermes-headers/hermes)';
+  }
   return null;
 }