refactor(ios): remove clang VFS overlay, resolve headers via new ReactNativeHeaders framework

[chrfalch]

Summary

The prebuilt React.xcframework previously relied on a Clang VFS overlay (React-VFS.yaml) to make headers importable, because the headers were laid out in CocoaPods-style namespaced folders rather than standard framework conventions. The overlay had to be generated at build time, re-resolved at pod-install time per slice, and injected as -ivfsoverlay flags into every Obj-C, C++, and Swift compile (including aggregate and third-party pod targets).

This is fragile, hard to reason about, and incompatible with SwiftPM consumption.

This PR removes the VFS overlay entirely and resolves headers through standard framework/header-search-path mechanics instead.

Headers are now emitted into the artifact according to an explicit, executable spec:

• React.xcframework — each slice's React.framework carries every <React/...> header plus a framework module map, so #import <React/...> and @import React resolve through FRAMEWORK_SEARCH_PATHS automatically.
• ReactNativeHeaders.xcframework (new, headers-only) — carries every other namespace (<react/...>, <yoga/...>, folly, glog, …), shipped alongside in the prebuilt tarball and exposed via a single header search path.
• This makes ReactNativeDependencies binary-only.

No clang VFS overlay, no per-target -ivfsoverlay flags. The layout is driven by a single source of truth (headers-spec.js, rules R1–R11) that both the prebuild compose step and downstream SwiftPM tooling derive from, so the shipped header set cannot drift from the spec.

Source headers are byte-identical to the repo — the only consumer-facing change needed is bare-form angle includes (#import <RCTAppDelegate.h> → #import <React/RCTAppDelegate.h>).

Consumer surfaces the flattened layout initially dropped are restored (validated against Expo and community Fabric modules):

• Private headers (RCTBridge+Private.h + the Fabric RCTComponentView* family) are exposed in the React module map — modular where safe, textual where they reach C++ — so frameworks like Expo compile unchanged, incl. Swift access to RCTBridge.moduleRegistry.
• React_RCTAppDelegate-umbrella.h is re-emitted (derived from the live header set) for consumers probing it via __has_include.
• Sources shipping under multiple include spellings (React/X.h + legacy CoreModules/…, RCTImage/…, bare aliases — 116 today) keep content at ONE module-owned spelling; other spellings become generated redirect shims, so -fmodules consumers cannot hit duplicate declarations.
• The React-RCTFabric facade re-vends RCTFabricComponentsPlugins.h at header_dir "React", keeping community Fabric modules' quoted #import "RCTFabricComponentsPlugins.h" working as with source pods.

The layout is verified at generator time (headers-verify.js, runs in the prebuild compose CI job): unresolvable includes ratchet against a committed baseline, composed module maps/umbrellas must byte-match the spec render, and consumer-shaped compile smokes must pass (the React module, every namespace module, an Expo-shaped ObjC++ fixture, and a Swift moduleRegistry fixture). Fail-closed guards cover header collisions, allowlist drift, and missing OR undeclared third-party deps namespaces (the latter surfaced SocketRocket, which is deliberately NOT relocated — the real pod vends it, and textual copies collide under use_frameworks; the gate asserts its absence).

Key changes

• New: headers-spec.js (the executable layout contract, R1–R11), headers-compose.js (emitter for both xcframeworks), headers-inventory.js (podspec-driven header classifier feeding the spec + a diagnostic manifest), headers-verify.js (generator-time gate + CI step), __docs__/headers-rules.md (rules + rationale).
• Removed: vfs.js, VFS types in types.js, and the VFS processing/flag-injection paths in rncore.rb and xcframework.js.
• Updated: React-Core-prebuilt.podspec (vends both xcframeworks, flattens ReactNativeHeaders headers into Headers/ via prepare_command, fails closed on incomplete tarballs), rncore.rb / react_native_pods.rb (header search path instead of overlay flags), prebuild-ios-core.yml (core tarball ships both xcframeworks; compose job verifies the composed headers), README (VFS docs replaced with the new model).
• Added facades to the Podspecs that shouldn't be in use when running using precompiled frameworks to satisfy dependencies as empty pod-specs (with the single RCTFabricComponentsPlugins.h re-vend exception noted above).

Changelog:

[IOS] [CHANGED] - Remove the Clang VFS overlay from prebuilt React Native Core; resolve headers via React.xcframework + a new headers-only ReactNativeHeaders.xcframework

Test Plan

• rn-tester builds against the prebuilt React-Core-prebuilt pod (Debug + Release) with no -ivfsoverlay flags present in the generated xcconfigs.
• rn-tester builds against React native source code (without any prebuilt artifacts)
• #import <React/...>, @import React;, and the relocated namespaces (<react/...>, <yoga/...>, folly/glog) all resolve.
• Prebuilt tarball contains both React.xcframework and ReactNativeHeaders.xcframework; pod install flattens headers into React-Core-prebuilt/Headers.
• Switch RN-tester between Debug/Release and verify that both React.xcframework and ReactNativeHeaders.xcframework are changed between debug and release correctly.
• headers-verify.js gate green on Debug and Release composes (-Werror=non-modular-include-in-framework-module never trips in consumer builds).
• private/helloworld builds against the prebuilt core (CocoaPods path).
• Expo SDK compiles against the prebuilt artifacts (private headers, React_RCTAppDelegate umbrella probe, Fabric quoted imports).

[cortinico]

CI is really red @chrfalch

[chrfalch]

CI is really red @chrfalch

I know - working on it! Forgot to put it in draft, @cortinico :)

[cipolleschi]

I see that the modulemap template has been deleted. Why are we setting this? From where the modulemap comes from?

[cipolleschi]

Major: Inventory natural-path collisions are computed here but never enforced. computeInventory() (~line 581) doesn't return collisions, and the compose gate in headers-compose.js (~line 40) only checks destination collisions from headers-spec.js. Because addIdentity merges two same-naturalPath sources into one entry and planFromInventory only uses identities[0].source, the second source is silently dropped and nothing fails — a gap versus the R8 'can't silently regress' guarantee in the docs. Consider surfacing these collisions and treating a non-empty set as fatal.

[cipolleschi]

Minor: The default-member-initializer heuristic requires a named aggregate, so an anonymous typedef struct { CGFloat x = NAN; } Foo; is misbucketed as objc/c and could wrongly enter the umbrella. The generator compile gate is the backstop, but widening this regex (or a comment) would help.

[cipolleschi]

Minor: Line scanners strip only // comments, not /* ... */ block comments, so a block-comment line starting with namespace/template </constexpr can trip the C++ detector and push a header to textual/objc-blocked. Direction is safe (only loses modularity), but it can silently shrink the umbrella.

[cipolleschi]

Minor: .replace('-', '_') replaces only the first hyphen, so a future pod like React-Foo-Bar would namespace as React_Foo-Bar. Intentional parity with the old code and no current pod has two hyphens, but /-/g would be safer.

[cipolleschi]

Major: The recompose freshness marker keys only on the React.xcframework Info.plist mtime. Editing a source header or headers-spec.js/headers-compose.js without changing the cached xcframework will serve stale composed output. Fine for downloaded-artifact consumers, but a footgun for local iteration — consider folding a hash of the plan (or of the script mtimes) into the marker.

[cipolleschi]

Minor: compose uses execSync with template-interpolated double-quoted paths, while headers-verify.js uses execFileSync with arg arrays. A path containing " or $ could break or shell-expand. Low risk (CI/dev-Mac controlled paths), just an inconsistency worth noting.

[cipolleschi]

Minor: Missing hermes namespace warns and continues, whereas missing deps namespaces fail closed. Documented as intentional, but a consumer-side compose can silently produce a ReactNativeHeaders without <hermes/...> resolution and only discover it at a downstream build.

[cipolleschi]

Major: This hard-fails install when a tarball lacks ReactNativeHeaders.xcframework (mirrored by a throw in replace-rncore-version.js). Deliberate, but any artifact published before this layout becomes uninstallable with no version-gated fallback — notable on a stable branch. Please confirm the prebuild-ios-core.yml cache key was bumped, otherwise a warm pre-PR cache can skip the new download/extract steps and ship a ReactNativeHeaders-less tarball.

[cipolleschi]

Nit: The 'contract' docblock lists R1–R8 then jumps to R11; R9/R10 exist only as inline comments, and other files say R1–R10 / R1–R11. Align the numbering.

[chrfalch]

Thanks for the detailed review! Addressed in 24a65c98ded:

Majors

• headers-inventory.js collisions — computeInventory() now returns collisions, and computeSpecPlan() fails closed on a non-empty set (R8). Two sources projecting to the same natural path can no longer be silently merged.
• headers-compose.js freshness marker — now folds a sha256 of the compose tooling (headers-{inventory,spec,compose}.js) into the marker, so a local script edit forces a recompose (the source xcframework's Info.plist mtime alone couldn't catch that).
• React-Core-prebuilt.podspec hard-fail — kept intentional. Cache-key confirmed: prebuild-ios-core.yml's key hashes packages/react-native/scripts/ios-prebuild/*.js (all changed in this PR), so any warm pre-PR cache misses and re-runs the ReactNativeHeaders download/extract — a headers-less tarball can't ship.

Question — rncore.rb:567 (where does the modulemap come from now?): it's no longer templated. The module map is composed at prebuild time by headers-compose.js, shipped inside the ReactNativeHeaders artifact, and the pod flattens it to React-Core-prebuilt/Headers/module.modulemap — which is exactly what the -fmodule-map-file flag points at. The template was deleted because the map is now generated, not templated at pod-install.

Minors / nits — all done: .replace(/-/g,'_') for multi-hyphen pods; anonymous-aggregate heuristic widened; /* … */ block-comment stripping in the line scanner; execSync→execFileSync for the cp/tar shell-outs (also clears the two CodeQL "command from env values" alerts); clearer hermes-missing warning; R9/R10 added to the contract docblock. New headers-inventory-test.js covers scanHeader (cxx guards, #else/#elif, anonymous aggregate, block/line comments).