feat(iOS) swiftpm support in iOS (#57332)

Summary:
⚠️  This is a stacked PR — review/merge the base PRs first

Builds on, and should land after (bottom-up):

1. #57285 — Remove the Clang VFS overlay / modularize React headers (base of the stack). <React/…> via the framework module map; lowercase namespaces (react/, yoga/, jsi/, …) via the ReactNativeHeaders module map.
2. #57305 — Prebuilt artifact resources + ReactNativeHeaders.xcframework. Ships the prebuilt core artifacts (incl. ReactNativeHeaders in the tarball + embedded React.framework resources) and the CocoaPods React-Core-prebuilt facades.
3. #57440 — Self-serving prebuilt ReactNativeDependencies + dependency-only facades. The deps pod becomes the single header authority for the third-party namespaces (RCT-Folly/glog/boost/…); community `s.dependency "RCT-Folly"` resolves to local facades instead of trunk source pods.
4. #57442 — ReactNativeDependenciesHeaders sidecar + pure-RN ReactNativeHeaders (immediate base). The deps prebuild emits a headers-only LIBRARY-type sidecar (the binary deps xcframework is framework-type — invisible to SwiftPM binaryTargets), ReactNativeHeaders drops the third-party namespaces, and both headers artifacts publish standalone to Maven.

The whole stack is rebased onto current main (2026-07-06).

This PR consumes the final **five-artifact set**: React, ReactNativeHeaders (pure-RN), ReactNativeDependencies, ReactNativeDependenciesHeaders, hermes-engine.

Adds npx react-native spm and the package-generation tooling that turns an app into a SwiftPM-integrated RN app using the base stack's prebuilt XCFrameworks. CocoaPods stays supported — additive, opt-in, no Ruby toolchain. Integration is injected into the existing .xcodeproj in place (nothing generated/renamed/replaced), recorded in .spm-injected.json so it reverses exactly.

### What this PR adds

- The spm CLI (add/update/deinit/scaffold + hidden sync/codegen/download), zero-arg auto-resolution, --deintegrate for CocoaPods→SwiftPM.
- SwiftPM package generation (scripts/spm/): autolinking→Package.swift, Codegen→React-GeneratedCode, core XCFramework binary targets, artifact download/cache, surgical pbxproj inject/remove.
- ReactNativeDependenciesHeaders wired as the 5th binaryTarget: the headers-only companions (ReactNativeHeaders from the core tarball, the deps sidecar from the deps tarball) are staged automatically out of their parent tarballs — no --headers-tarball priming; REQUIRED_ARTIFACTS covers all five.
- Community-library scaffolding from podspecs (incl. root-level-source podspecs via generated include/<SwiftName>/ shims, sibling wiring for transitive spm.dependencies, self-ingestion guards).
- In-place Xcode integration (XCLocalSwiftPackageReference + Sync build phase + scheme pre-action + auto-sync; ${PODS_ROOT}-anchored REACT_NATIVE_PATH replaced on --deintegrate with exact deinit rollback).
- rn-tester + helloworld SwiftPM consumption + test library; npm-packaging hygiene; a small RNCoreFacades.podspec_dir fix.

## Documentation

- **Tool docs** (usage, quick start, architecture): [`scripts/spm/__doc__/spm-scripts.md`](https://github.com/react/react-native/blob/chrfalch/swift-package-manager/packages/react-native/scripts/spm/__doc__/spm-scripts.md)
- **Header-paths contract** (how the five artifacts serve headers): [`scripts/spm/__doc__/spm-header-paths-contract.md`](https://github.com/react/react-native/blob/chrfalch/swift-package-manager/packages/react-native/scripts/spm/__doc__/spm-header-paths-contract.md)
- **RFC** (updated): [react-native-community/discussions-and-proposals#994](react-native-community/discussions-and-proposals#994)

## Changelog:

[IOS] [ADDED] - `npx react-native spm` command + SwiftPM package-generation tooling (opt-in; CocoaPods stays supported)

Pull Request resolved: #57332

Test Plan:
350 scripts/spm unit tests (incl. byte-identical add→deinit round-trip); manual E2E against the five-artifact set: fresh app via `cli init`→`spm add --deintegrate`→build (artifact resources verified in the app), rn-tester in-place migration (RNTesterPods.xcodeproj, test libraries + spmModules), helloworld in-place migration — all BUILD SUCCEEDED. Verified `npx react-native spm <cmd>` from the command line in each journey.

## Scope & limitations

iOS, prebuilt-only (no build-from-source yet); full spm.xcframework/spm.source library metadata not yet (app-local spm.modules + scaffolding are); Expo not yet.

## Follow-ups

Remote-mode ReactNative Package.swift must vend the ReactNativeDependenciesHeaders product (spm-distribution repo); library self-containment for repo-portable manifests; build-from-source.

Reviewed By: mdvacca

Differential Revision: D111449548

Pulled By: cipolleschi

fbshipit-source-id: 87a873bf5c8be2d60f7893611e16924bfa730a46

Author: chrfalch

package.json

@@ -43,6 +43,7 @@
   },
   "workspaces": [
     "packages/*",
+    "packages/react-native-test-library/*",
     "private/*",
     "!private/helloworld"
   ],

packages/react-native-test-library/.gitignore

@@ -0,0 +1,11 @@
+# Generated SPM artifacts (written by setup-ios-spm.js's earlier in-place
+# layout). The current autolinker emits these under the consumer app's
+# build/generated/autolinking/ tree instead, so any copy that lands here is
+# stale and should not be committed.
+Package.swift
+Package.resolved
+include/
+
+# SwiftPM caches
+.build/
+.swiftpm/

packages/react-native-test-library/apple/TestLibraryApple.h

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <React/RCTBridgeModule.h>
+
+@interface TestLibraryApple : NSObject <RCTBridgeModule>
+@end

packages/react-native-test-library/apple/TestLibraryApple.mm

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "TestLibraryApple.h"
+
+// Synth library products are emitted as .library(type: .dynamic, ...), so SPM
+// wraps each autolinked dep as a Foo.framework under PackageFrameworks/. That
+// gives angle-bracket imports the standard <Module/Header.h> resolution path,
+// matching how most React Native libraries already organize their headers.
+#import <ReactNativeTestLibraryCommon/TestLibraryCommon.h>
+
+@implementation TestLibraryApple
+
+RCT_EXPORT_MODULE()
+
+RCT_EXPORT_METHOD(
+    echo : (NSString *)message resolve : (RCTPromiseResolveBlock)resolve reject : (RCTPromiseRejectBlock)reject)
+{
+  NSString *prefix = [TestLibraryCommon defaultPrefix];
+  resolve([NSString stringWithFormat:@"%@apple: %@", prefix, message]);
+}
+
+@end

packages/react-native-test-library/apple/TestLibraryApple.podspec

@@ -0,0 +1,29 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name            = "TestLibraryApple"
+  s.version         = package["version"]
+  s.summary         = package["description"]
+  s.homepage        = "https://github.com/facebook/react-native"
+  s.license         = "MIT"
+  s.platforms       = min_supported_versions
+  s.author          = "Meta Platforms, Inc. and its affiliates"
+  s.source          = { :git => "https://github.com/facebook/react-native.git", :tag => "#{s.version}" }
+  s.source_files    = "*.{h,m,mm,swift}"
+  s.requires_arc    = true
+
+  # TestLibraryApple.mm imports <ReactNativeTestLibraryCommon/TestLibraryCommon.h>.
+  # CocoaPods resolves it leniently through the shared Public headers dir, but the
+  # dependency edge must be declared for SwiftPM (the scaffolder wires sibling
+  # packages from podspec dependencies).
+  s.dependency "TestLibraryCommon"
+
+  install_modules_dependencies(s)
+end

packages/react-native-test-library/apple/__tests__/TestLibraryAppleTests.cpp

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include <this/header/intentionally/does/not/exist.h>
+
+static_assert(
+    false,
+    "TestLibraryAppleTests.cpp must not be compiled by the SPM autolinker");

packages/react-native-test-library/apple/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {Greeting} from '../common';
+
+export function greet(g: Greeting): Promise<string>;

packages/react-native-test-library/apple/index.js

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+import type {Greeting} from '../common';
+
+import {formatGreeting} from '../common';
+import {NativeModules, Platform} from 'react-native';
+
+export function greet(g: Greeting): Promise<string> {
+  const TestLibraryApple = NativeModules.TestLibraryApple;
+  if (TestLibraryApple == null) {
+    return Promise.reject(
+      new Error(
+        `react-native-test-library-apple: native module unavailable on ${Platform.OS}. This package is iOS-only; install a platform-specific sibling (e.g. react-native-test-library-android) for cross-platform coverage.`,
+      ),
+    );
+  }
+  return TestLibraryApple.echo(formatGreeting(g));
+}

packages/react-native-test-library/apple/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "react-native-test-library-apple",
+  "version": "0.87.0-main",
+  "description": "Apple platform implementation for the React Native autolinking fixture. Depends on react-native-test-library-common; used to validate iOS/macOS autolinking discovery and transitive native dependency resolution.",
+  "private": true,
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "react-native.config.js",
+    "TestLibraryApple.podspec",
+    "TestLibraryApple.h",
+    "TestLibraryApple.mm"
+  ],
+  "keywords": [
+    "react-native",
+    "fixture",
+    "autolinking",
+    "ios",
+    "macos"
+  ],
+  "dependencies": {
+    "react-native-test-library-common": "0.87.0-main"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "1000.0.0"
+  }
+}

packages/react-native-test-library/apple/react-native.config.js

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @noflow
+ */
+
+'use strict';
+
+module.exports = {
+  dependency: {
+    platforms: {
+      ios: {},
+    },
+  },
+  spm: {
+    dependencies: ['react-native-test-library-common'],
+  },
+};