fix(iOS): exclude C++-guarded foreign-namespace headers from React umbrella (#57575)

Summary:
The first nightly containing the prebuilt/SwiftPM stack (`0.88.0-nightly-20260716`) broke the `react-native-unistyles` job in [react-native-community/nightly-tests](https://github.com/react-native-community/nightly-tests/actions/runs/29476835418/job/87551592185) with:

```
Pods/Headers/Public/React-Core-prebuilt/react/timing/primitives.h:28:7: error: redefinition of 'HighResDuration'
note: additional include site in header from module 'ReactNativeHeaders_react'
note: additional include site in header from module 'React.RCTFrameTimingsObserver'
→ could not build module 'React'
```

**Root cause:** `RCTFrameTimingsObserver.h` includes `<jsinspector-modern/tracing/FrameTimingSequence.h>` under `#ifdef __cplusplus`, transitively reaching `react/timing/primitives.h`, which is owned by the `ReactNativeHeaders_react` module. The headers inventory's reachability fixpoint only follows *unguarded* include edges (modeling a pure-ObjC consumer), so it couldn't see this edge and classified the header as umbrella-safe. Swift pods with C++ interop (unistyles, Nitro-based libs) build the `React` clang module as ObjC++, opening the guard — one header owned by two modules in a single compilation → C++ redefinition errors. Pure-ObjC consumers never open the guard, which is why only C++-interop libraries failed.

**Fix:** a curated `UMBRELLA_CXX_GUARDED_EXCLUSIONS` set checked in `isUmbrellaSafe`, mirroring the existing `PRIVATE_REACT_HEADERS` pattern, with fail-closed validation (`validateUmbrellaExclusions`, wired into `planFromInventory`) so a renamed/deleted entry surfaces immediately.

The header still ships in `React.framework/Headers` and stays importable via `#import <React/RCTFrameTimingsObserver.h>` (its only consumer today is `RCTHost.mm`); it is only removed from the modular umbrella surface. If a modular consumer ever needs it, it can be promoted to a `PRIVATE_REACT_HEADERS.textual`-style entry instead.

## Changelog:

[IOS] [FIXED] - Fix "redefinition of 'HighResDuration'" / "could not build module 'React'" when building Swift pods with C++ interop against the prebuilt React-Core artifact

Pull Request resolved: #57575

Test Plan:
- New unit tests in `scripts/ios-prebuild/__tests__/headers-spec-test.js`: the excluded header is kept out of the umbrella (fails against the previous code with `Received array: ["React/RCTFrameTimingsObserver.h"]`), and exclusion drift fails closed.
- Full ios-prebuild suite: 5 suites, 58/58 tests passing; prettier/eslint clean.
- E2E: to be confirmed via a nightly/prebuilt cut building react-native-unistyles in prebuilt mode (`RCT_USE_RN_DEP=1 RCT_USE_PREBUILT_RNCORE=1`).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed By: sammy-SC

Differential Revision: D112320697

Pulled By: cipolleschi

fbshipit-source-id: 9c7d1d2cb035ac821992914d8df4db7245905834

Author: chrfalch

packages/react-native/scripts/ios-prebuild/__tests__/headers-spec-test.js

@@ -72,6 +72,11 @@ const validManifest = () => ({
       'objc-modular-candidate',
     ),
     entry('React_RCTAppDelegate/RCTAppDelegate.h', 'objc-modular-candidate'),
+    // Bucketed objc-modular-candidate because its only C++ include
+    // (<jsinspector-modern/tracing/...> → react/timing/primitives.h) is behind
+    // a `#ifdef __cplusplus` guard; the inventory's umbrella-safety fixpoint
+    // follows unguarded edges only. It must still be kept OUT of the umbrella.
+    entry('React/RCTFrameTimingsObserver.h', 'objc-modular-candidate'),
   ],
 });
 
@@ -166,6 +171,28 @@ describe('R10 per-namespace umbrella (React_RCTAppDelegate)', () => {
   });
 });
 
+describe('R4 umbrella excludes C++-guarded foreign-namespace headers', () => {
+  test('a guarded-C++ objc-modular-candidate header is kept out of the umbrella', () => {
+    const plan = planFromInventoryForTest(validManifest());
+    // RCTFrameTimingsObserver.h is objc-modular-candidate for a pure-ObjC
+    // consumer, but reaches react/timing/primitives.h once the __cplusplus
+    // guard opens (Swift/C++-interop compiles the React module as ObjC++).
+    // primitives.h is owned by ReactNativeHeaders_react, so an umbrella entry
+    // would make one header live in two modules → C++ redefinition.
+    expect(plan.umbrella).not.toContain('React/RCTFrameTimingsObserver.h');
+  });
+
+  test('fails closed when an excluded header is absent from the inventory', () => {
+    const m = validManifest();
+    m.headers = m.headers.filter(
+      x => x.naturalPath !== 'React/RCTFrameTimingsObserver.h',
+    );
+    expect(() => planFromInventoryForTest(m)).toThrow(
+      /RCTFrameTimingsObserver\.h is absent/,
+    );
+  });
+});
+
 describe('R5 invalid-identifier exemption assert (H5)', () => {
   test('throws when an invalid-identifier namespace gains a modular candidate', () => {
     const m = validManifest();

packages/react-native/scripts/ios-prebuild/headers-spec.js

@@ -143,6 +143,24 @@ const EXTERN_INLINE_RE /*: RegExp */ =
 
 const MODULE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+// R4 umbrella exclusion: ObjC headers whose ONLY C++ include is behind a
+// `#ifdef __cplusplus` guard, so the inventory buckets them
+// objc-modular-candidate — the reachability fixpoint (headers-inventory.js)
+// follows UNGUARDED edges only, modelling a pure-ObjC consumer. But the React
+// framework module is compiled as Objective-C++ by Swift/C++-interop consumers:
+// the guard opens, the umbrella transitively includes the foreign C++ header,
+// and that header is ALSO owned by the ReactNativeHeaders_<ns> module. One
+// physical header, two modules → C++ redefinition ("could not build module
+// 'React'"). Keeping the header OUT of the umbrella leaves it shipped and
+// textually importable (`#import <React/...>`); its guarded C++ includes then
+// resolve at the consumer's use site, exactly as PRIVATE_REACT_HEADERS.textual
+// (R9) already handles the unguarded objc-blocked case.
+// Found empirically: RCTFrameTimingsObserver.h (#56015) reaches
+// react/timing/primitives.h via <jsinspector-modern/tracing/FrameTimingSequence.h>.
+const UMBRELLA_CXX_GUARDED_EXCLUSIONS /*: Set<string> */ = new Set([
+  'React/RCTFrameTimingsObserver.h',
+]);
+
 // R9: Private React headers — a curated allowlist of `<React/...>` headers that
 // privileged framework consumers (e.g. Expo) import, but which the public
 // umbrella (R4) excludes (they are `+`-suffixed and/or objc-blocked). They are
@@ -202,8 +220,29 @@ function validatePrivateReactHeaders(manifest /*: any */) /*: void */ {
   }
 }
 
+// Fail closed if an umbrella exclusion drifts: the header must still exist in
+// the inventory. If it was removed/renamed the stale exclusion would silently
+// stop matching and the header would re-enter the umbrella — reintroducing the
+// dual-module redefinition. Force the list to be updated instead.
+function validateUmbrellaExclusions(manifest /*: any */) /*: void */ {
+  const naturals = new Set(manifest.headers.map(h => h.naturalPath));
+  for (const np of UMBRELLA_CXX_GUARDED_EXCLUSIONS) {
+    if (!naturals.has(np)) {
+      throw new Error(
+        `Umbrella exclusion ${np} is absent from the inventory ` +
+          `(removed/renamed in source?). Update ` +
+          `UMBRELLA_CXX_GUARDED_EXCLUSIONS.`,
+      );
+    }
+  }
+}
+
 function isUmbrellaSafe(h /*: any */, rnRoot /*: string */) /*: boolean */ {
-  if (h.bucket !== 'objc-modular-candidate' || h.naturalPath.includes('+')) {
+  if (
+    h.bucket !== 'objc-modular-candidate' ||
+    h.naturalPath.includes('+') ||
+    UMBRELLA_CXX_GUARDED_EXCLUSIONS.has(h.naturalPath)
+  ) {
     return false;
   }
   try {
@@ -254,6 +293,7 @@ function planFromInventory(
 ) /*: HeadersSpecPlan */ {
   const root = rnRoot ?? manifest.root ?? RN_ROOT;
   validatePrivateReactHeaders(manifest); // R9: fail closed on allowlist drift
+  validateUmbrellaExclusions(manifest); // R4: fail closed on exclusion drift
   const react /*: Array<SpecEntry> */ = [];
   const reactNativeHeaders /*: Array<SpecEntry> */ = [];
   const umbrella /*: Array<string> */ = [];