react-native 0.87.0-rc.4 → 0.87.1

package/Libraries/Animated/AnimatedEvent.js

@@ -199,7 +199,7 @@ export class AnimatedEvent {
     this._attachedEvent && this._attachedEvent.detach();
   }
 
-  __getHandler(): any | ((...args: any) => void) {
+  __getHandler(): (...args: any) => void {
     if (this.__isNative) {
       if (__DEV__) {
         let validatedMapping = false;

package/Libraries/Animated/AnimatedImplementation.js

@@ -576,10 +576,14 @@ function unforkEventImpl(
   }
 }
 
-const eventImpl = function <T>(
+// NOTE: With `useNativeDriver: true` this returns an `AnimatedEvent` instance
+// rather than a callable handler. That object is only ever meant to be handed
+// straight back to an animated component's event prop, so the declared type
+// describes the handler shape both branches are consumed as.
+const eventImpl: <T>(
   argMapping: ReadonlyArray<?Mapping>,
   config: EventConfig<T>,
-): any {
+) => (...args: Array<any>) => void = function (argMapping, config): any {
   const animatedEvent = new AnimatedEvent(argMapping, config);
   if (animatedEvent.__isNative) {
     return animatedEvent;

package/Libraries/Animated/nodes/AnimatedNode.js

@@ -13,7 +13,7 @@ import type {PlatformConfig} from '../AnimatedPlatformConfig';
 import NativeAnimatedHelper from '../../../src/private/animated/NativeAnimatedHelper';
 import invariant from 'invariant';
 
-type ValueListenerCallback = (state: {value: number, ...}) => unknown;
+export type ValueListenerCallback = (state: {value: number}) => unknown;
 
 export type AnimatedNodeConfig = Readonly<{
   debugID?: string,

package/Libraries/Animated/nodes/AnimatedValue.js

@@ -17,7 +17,7 @@ import type {
   InterpolationConfigType,
 } from './AnimatedInterpolation';
 import type AnimatedNode from './AnimatedNode';
-import type {AnimatedNodeConfig} from './AnimatedNode';
+import type {AnimatedNodeConfig, ValueListenerCallback} from './AnimatedNode';
 import type AnimatedTracking from './AnimatedTracking';
 
 import NativeAnimatedHelper from '../../../src/private/animated/NativeAnimatedHelper';
@@ -138,7 +138,7 @@ export default class AnimatedValue extends AnimatedWithChildren {
     }
   }
 
-  addListener(callback: (value: any) => unknown): string {
+  addListener(callback: ValueListenerCallback): string {
     const id = super.addListener(callback);
     this._listenerCount++;
     if (this.__isNative) {

package/Libraries/Core/ReactNativeVersion.js

@@ -28,8 +28,8 @@
 export default class ReactNativeVersion {
   static major: number = 0;
   static minor: number = 87;
-  static patch: number = 0;
-  static prerelease: string | null = 'rc.4';
+  static patch: number = 1;
+  static prerelease: string | null = null;
 
   static getVersionString(): string {
     return `${this.major}.${this.minor}.${this.patch}${this.prerelease != null ? `-${this.prerelease}` : ''}`;

package/React/Base/RCTVersion.m

@@ -23,8 +23,8 @@ NSDictionary* RCTGetReactNativeVersion(void)
     __rnVersion = @{
                   RCTVersionMajor: @(0),
                   RCTVersionMinor: @(87),
-                  RCTVersionPatch: @(0),
-                  RCTVersionPrerelease: @"rc.4",
+                  RCTVersionPatch: @(1),
+                  RCTVersionPrerelease: [NSNull null],
                   };
   });
   return __rnVersion;

package/ReactAndroid/gradle.properties

@@ -1,4 +1,4 @@
-VERSION_NAME=0.87.0-rc.4
+VERSION_NAME=0.87.1
 react.internal.publishingGroup=com.facebook.react
 react.internal.hermesPublishingGroup=com.facebook.hermes
 

package/ReactAndroid/src/main/java/com/facebook/react/modules/intent/IntentModule.kt

@@ -87,11 +87,15 @@ public open class IntentModule(reactContext: ReactApplicationContext) :
           override fun onHostResume() {
             reactApplicationContext.removeLifecycleEventListener(this)
             synchronized(this@IntentModule) {
-              for (pendingPromise in pendingOpenURLPromises) {
+              // getInitialURL can re-enter and re-add to pendingOpenURLPromises when the activity
+              // is still null at resume, so drain a snapshot (after clearing the list and listener)
+              // to avoid mutating the list being iterated (ConcurrentModificationException).
+              val pendingPromises = ArrayList(pendingOpenURLPromises)
+              pendingOpenURLPromises.clear()
+              initialURLListener = null
+              for (pendingPromise in pendingPromises) {
                 getInitialURL(pendingPromise)
               }
-              initialURLListener = null
-              pendingOpenURLPromises.clear()
             }
           }
 

package/ReactAndroid/src/main/java/com/facebook/react/modules/systeminfo/ReactNativeVersion.kt

@@ -14,7 +14,7 @@ public object ReactNativeVersion {
   public val VERSION: Map<String, Any?> = mapOf(
     "major" to 0,
     "minor" to 87,
-    "patch" to 0,
-    "prerelease" to "rc.4"
+    "patch" to 1,
+    "prerelease" to null
   )
 }

package/ReactCommon/cxxreact/ReactNativeVersion.h

@@ -14,15 +14,15 @@
 
 #define REACT_NATIVE_VERSION_MAJOR 0
 #define REACT_NATIVE_VERSION_MINOR 87
-#define REACT_NATIVE_VERSION_PATCH 0
+#define REACT_NATIVE_VERSION_PATCH 1
 
 namespace facebook::react {
 
 struct ReactNativeVersionType {
   int32_t Major = 0;
   int32_t Minor = 87;
-  int32_t Patch = 0;
-  std::string_view Prerelease = "rc.4";
+  int32_t Patch = 1;
+  std::string_view Prerelease = "";
 };
 
 constexpr ReactNativeVersionType ReactNativeVersion;

package/ReactCommon/react/renderer/textlayoutmanager/platform/ios/react/renderer/textlayoutmanager/RCTFontUtils.mm

@@ -361,7 +361,7 @@ UIFont *RCTFontWithFontProperties(RCTFontProperties fontProperties)
       font = [UIFont fontWithName:fontProperties.family size:effectiveFontSize];
       if (font != nullptr) {
         fontNames = [UIFont fontNamesForFamilyName:font.familyName];
-        fontWeight = (fontWeight != 0.0) ?: RCTGetFontWeight(font);
+        fontWeight = (fontWeight != 0.0) ? fontWeight : RCTGetFontWeight(font);
       } else {
         // Failback to system font.
         font = RCTDefaultFontWithFontProperties(fontProperties);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native",
-  "version": "0.87.0-rc.4",
+  "version": "0.87.1",
   "description": "A framework for building native apps using React",
   "license": "MIT",
   "repository": {
@@ -150,19 +150,19 @@
     }
   },
   "dependencies": {
-    "@react-native/asset-utils": "0.87.0-rc.4",
-    "@react-native/codegen": "0.87.0-rc.4",
-    "@react-native/community-cli-plugin": "0.87.0-rc.4",
-    "@react-native/gradle-plugin": "0.87.0-rc.4",
-    "@react-native/normalize-colors": "0.87.0-rc.4",
-    "@react-native/virtualized-lists": "0.87.0-rc.4",
+    "@react-native/asset-utils": "0.87.1",
+    "@react-native/codegen": "0.87.1",
+    "@react-native/community-cli-plugin": "0.87.1",
+    "@react-native/gradle-plugin": "0.87.1",
+    "@react-native/normalize-colors": "0.87.1",
+    "@react-native/virtualized-lists": "0.87.1",
     "anser": "^1.4.9",
     "ansi-regex": "^5.0.0",
     "babel-plugin-syntax-hermes-parser": "0.36.1",
     "base64-js": "^1.5.1",
     "commander": "^12.0.0",
     "flow-enums-runtime": "^0.0.6",
-    "hermes-compiler": "250829098.0.16",
+    "hermes-compiler": "250829098.0.17",
     "invariant": "^2.2.4",
     "memoize-one": "^5.0.0",
     "metro-runtime": "^0.87.0",

package/scripts/cocoapods/rndependencies.rb

@@ -6,7 +6,6 @@
 require "json"
 require 'net/http'
 require 'rexml/document'
-require 'shellwords'
 
 require_relative './utils.rb'
 
@@ -34,38 +33,26 @@ def add_rn_third_party_dependencies(s)
             s.dependency "RCT-Folly/Fabric"
         end
 
-        header_search_paths = current_pod_target_xcconfig["HEADER_SEARCH_PATHS"] || []
-
-        if header_search_paths.is_a?(String)
-            header_search_paths = Shellwords.shellsplit(header_search_paths)
-        end
-
-        header_search_paths << "$(PODS_ROOT)/glog"
-        header_search_paths << "$(PODS_ROOT)/boost"
-        header_search_paths << "$(PODS_ROOT)/DoubleConversion"
-        header_search_paths << "$(PODS_ROOT)/fast_float/include"
-        header_search_paths << "$(PODS_ROOT)/fmt/include"
-        header_search_paths << "$(PODS_ROOT)/SocketRocket"
-        header_search_paths << "$(PODS_ROOT)/RCT-Folly"
-
-        # uniq so a second call on the same spec can't duplicate entries.
-        current_pod_target_xcconfig["HEADER_SEARCH_PATHS"] = header_search_paths.uniq
+        ReactNativeDependenciesUtils.append_header_search_paths(current_pod_target_xcconfig, [
+            "$(PODS_ROOT)/glog",
+            "$(PODS_ROOT)/boost",
+            "$(PODS_ROOT)/DoubleConversion",
+            "$(PODS_ROOT)/fast_float/include",
+            "$(PODS_ROOT)/fmt/include",
+            "$(PODS_ROOT)/SocketRocket",
+            "$(PODS_ROOT)/RCT-Folly",
+        ])
     else
         # Prebuilt-deps mode: this pod SELF-SERVES the third-party headers from its
         # own xcframework (incl. SocketRocket - sole supplier in this mode). See
         # scripts/cocoapods/__docs__/prebuilt-deps.md for the full contract.
         s.dependency "ReactNativeDependencies"
 
-        header_search_paths = current_pod_target_xcconfig["HEADER_SEARCH_PATHS"] || []
-        if header_search_paths.is_a?(String)
-            header_search_paths = Shellwords.shellsplit(header_search_paths)
-        end
         # Artifact headers are flattened into the pod-local Headers/ by the podspec
         # prepare_command (see __docs__/prebuilt-deps.md).
-        header_search_paths << "$(PODS_ROOT)/ReactNativeDependencies/Headers"
-
-        # uniq so a second call on the same spec can't duplicate entries.
-        current_pod_target_xcconfig["HEADER_SEARCH_PATHS"] = header_search_paths.uniq
+        ReactNativeDependenciesUtils.append_header_search_paths(current_pod_target_xcconfig, [
+            "$(PODS_ROOT)/ReactNativeDependencies/Headers",
+        ])
     end
 
     s.pod_target_xcconfig = current_pod_target_xcconfig
@@ -148,6 +135,25 @@ class ReactNativeDependenciesUtils
         end
     end
 
+    # Xcode splits HEADER_SEARCH_PATHS on whitespace, so every path we add is
+    # quoted - PODS_ROOT can expand to a directory with spaces in its name.
+    # Paths already in the xcconfig are left untouched: they carry the podspec
+    # author's own quoting, and re-quoting them would break it.
+    def self.append_header_search_paths(xcconfig, paths)
+        quoted = paths.map { |path| "\"#{path}\"" }
+        existing = xcconfig["HEADER_SEARCH_PATHS"]
+
+        # reject so a second call on the same spec can't duplicate entries.
+        case existing
+        when nil
+            xcconfig["HEADER_SEARCH_PATHS"] = quoted
+        when Array
+            xcconfig["HEADER_SEARCH_PATHS"] = existing + quoted.reject { |path| existing.include?(path) }
+        else
+            xcconfig["HEADER_SEARCH_PATHS"] = ([existing] + quoted.reject { |path| existing.include?(path) }).join(" ")
+        end
+    end
+
     def self.abort_if_use_local_rndeps_with_no_file()
       if !File.exist?(ENV["RCT_USE_LOCAL_RN_DEP"])
         abort("RCT_USE_LOCAL_RN_DEP is set to #{ENV["RCT_USE_LOCAL_RN_DEP"]} but the file does not exist!")

package/scripts/replace-rncore-version.js

@@ -18,6 +18,9 @@ const yargs = require('yargs');
 
 const LAST_BUILD_FILENAME = 'React-Core-prebuilt/.last_build_configuration';
 
+// Not a valid configuration, so finding it means the swap did not finish.
+const REPLACEMENT_IN_PROGRESS = 'in-progress';
+
 function validateBuildConfiguration(configuration /*: string */) {
   if (!['Debug', 'Release'].includes(configuration)) {
     throw new Error(`Invalid configuration ${configuration}`);
@@ -42,10 +45,12 @@ function shouldReplaceRnCoreConfiguration(configuration /*: string */) {
       );
       return false;
     }
+    return true;
   }
 
-  // Assumption: if there is no stored last build, we assume that it was build for debug.
-  if (!fileExists && configuration === 'Debug') {
+  // With no marker the on-disk flavor is Debug: the podspec installs the debug
+  // tarball (see resolve_podspec_source in scripts/cocoapods/rncore.rb).
+  if (configuration === 'Debug') {
     console.log(
       'No previous build detected, but Debug Configuration. No need to replace React-Core-prebuilt',
     );
@@ -130,6 +135,10 @@ function updateLastBuildConfiguration(configuration /*: string */) {
   fs.writeFileSync(LAST_BUILD_FILENAME, configuration);
 }
 
+function markReplacementInProgress() /*: void */ {
+  fs.writeFileSync(LAST_BUILD_FILENAME, REPLACEMENT_IN_PROGRESS);
+}
+
 function main(
   configuration /*: string */,
   version /*: string */,
@@ -139,9 +148,16 @@ function main(
   validateVersion(version);
 
   if (!shouldReplaceRnCoreConfiguration(configuration)) {
+    // A fresh install leaves no marker; record the flavor we skipped on.
+    if (!fs.existsSync(LAST_BUILD_FILENAME)) {
+      updateLastBuildConfiguration(configuration);
+    }
     return;
   }
 
+  // Invalidate before touching the framework so an interrupted swap is
+  // detectable on the next run.
+  markReplacementInProgress();
   replaceRNCoreConfiguration(configuration, version, podsRoot);
   updateLastBuildConfiguration(configuration);
   console.log('Done replacing React Native prebuilt');

package/scripts/setup-apple-spm.js

@@ -44,8 +44,10 @@
  * directing you to `--deintegrate`).
  *
  * Options:
- *   --version <ver>             React Native version (default: the resolved
- *                               node_modules/react-native version).
+ *   --version <ver>             React Native version. Pinned into
+ *                               .spm-injected.json and reused by later runs
+ *                               until a new one is passed (default: the
+ *                               resolved node_modules/react-native version).
  *   --yes                       Skip the dirty-pbxproj confirmation prompt.
  *   [add] --xcodeproj <path>    Which .xcodeproj to inject into (when several).
  *   [add] --product-name <name> Which app target to inject into (when several).
@@ -96,6 +98,7 @@ const {
   cleanupLeftoverPodsGroup,
   findInjectedXcodeproj,
   injectSpmIntoExistingXcodeproj,
+  readArtifactsVersionOverride,
   readPinnedConfigCommand,
   removeSpmInjection,
 } = require('./spm/generate-spm-xcodeproj');
@@ -153,7 +156,7 @@ function parseArgs(argv /*: Array<string> */) /*: SetupArgs */ {
     .option('version', {
       type: 'string',
       describe:
-        'React Native version (e.g. 0.80.0). Defaults to the version in node_modules/react-native/package.json',
+        'React Native version (e.g. 0.80.0). Sticks: later runs reuse it until you pass a new one. Defaults to the version in node_modules/react-native/package.json',
     })
     .option('yes', {
       type: 'boolean',
@@ -377,19 +380,31 @@ function resolveReactNativeRoot(
   return reactNativeRoot;
 }
 
+// Explicit `--version` → the version an earlier `--version` pinned into the
+// injection marker → node_modules/react-native/package.json. The pin makes
+// `--version` stick for later flagless runs, which would otherwise re-point the
+// project at a different artifact slot than the one it was wired to.
 function determineVersion(
   args /*: SetupArgs */,
   reactNativeRoot /*: string */,
+  appRoot /*: string */,
 ) /*: string */ {
-  let version = args.version;
-  if (version == null) {
-    // $FlowFixMe[incompatible-type] JSON.parse returns any
-    const pkgJson /*: {version: string} */ = JSON.parse(
-      fs.readFileSync(path.join(reactNativeRoot, 'package.json'), 'utf8'),
+  if (args.version != null) {
+    return args.version;
+  }
+  const pinned = readArtifactsVersionOverride(appRoot);
+  if (pinned != null) {
+    log(
+      `Using version ${pinned} pinned in ${SPM_INJECTED_MARKER} by an earlier ` +
+        '--version. Pass --version to change it.',
     );
-    version = pkgJson.version;
+    return pinned;
   }
-  return version;
+  // $FlowFixMe[incompatible-type] JSON.parse returns any
+  const pkgJson /*: {version: string} */ = JSON.parse(
+    fs.readFileSync(path.join(reactNativeRoot, 'package.json'), 'utf8'),
+  );
+  return pkgJson.version;
 }
 
 function runCodegenStep(
@@ -442,7 +457,7 @@ async function runScaffold(
   // a comment — that's how SPM's manifest hash bumps on slot transitions.
   let cacheSlotLabel /*: ?string */ = null;
   try {
-    const rawVersion = args.version ?? determineVersion(args, reactNativeRoot);
+    const rawVersion = determineVersion(args, reactNativeRoot, appRoot);
     const slotVersion = await resolveCacheSlotVersion(rawVersion);
     cacheSlotLabel = `${slotVersion}/dual-flavor`;
   } catch {
@@ -1094,7 +1109,7 @@ async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
     autolinkingConfigResult,
     projectRoot,
   );
-  const version = determineVersion(args, reactNativeRoot);
+  const version = determineVersion(args, reactNativeRoot, appRoot);
   log(`React Native version: ${version}`);
 
   // Resolve remote SPM mode ONCE up front. remotePackageConfig throws
@@ -1256,6 +1271,7 @@ if (require.main === module) {
 module.exports = {
   main,
   detectStandardRnLayoutRedirect,
+  determineVersion,
   findInjectedXcodeproj,
   generateAutolinkingConfigOrFailClosed,
   parseArgs,

package/scripts/spm/autolinking-plugins.js

@@ -69,6 +69,14 @@
  *         // dir add/remove there re-triggers the sync. Relative/empty/non-string
  *         // entries are dropped with a warning; a non-array is ignored.
  *         watchPaths: ['/abs/path/Package.swift', '/abs/dir'],
+ *         // Build-time shell phases on the app target — SwiftPM has no
+ *         // `script_phase`. Only id/name/script are required; `id` is the
+ *         // ledger key and UUID seed, `position` defaults to 'end'. Recorded
+ *         // to `.spm-plugin-script-phases.json`, from which the `spm add`/
+ *         // `update` injector emits a PBXShellScriptBuildPhase per entry.
+ *         // Malformed entries and duplicate ids are fatal.
+ *         scriptPhases: [{id, name, script, position, inputPaths, outputPaths,
+ *           alwaysOutOfDate}],
  *       };
  *     };
  *
@@ -76,12 +84,14 @@
  * the merge, so regeneration stays deterministic and idempotent.
  */
 
+const {isValidScriptPhaseId, isValidScriptPhaseName} = require('./spm-utils');
 const path = require('path');
 
 /*:: import type {
   AutolinkedDep,
   PluginContext,
   PluginResult,
+  PluginScriptPhase,
   DiscoveredPlugin,
 } from './spm-types';
 */
@@ -149,6 +159,12 @@ function discoverPlugins(
   return found;
 }
 
+const isNonEmptyString = (value /*: unknown */) /*: boolean */ =>
+  typeof value === 'string' && value.length > 0;
+
+const isOptionalStringList = (value /*: unknown */) /*: boolean */ =>
+  value == null || (Array.isArray(value) && value.every(isNonEmptyString));
+
 /**
  * Invoke discovered plugins and merge their results. Each plugin gets the same
  * context. Fail-closed: a throwing plugin aborts (named), and a malformed
@@ -169,10 +185,12 @@ function invokePlugins(
   const flavoredFrameworks /*: Array<{id: string, frameworkName: string, linkage: 'dynamic', flavors: {debug: string, release: string}}> */ =
     [];
   const watchPaths /*: Array<string> */ = [];
+  const scriptPhases /*: Array<PluginScriptPhase> */ = [];
   const seenPackages /*: Set<string> */ = new Set();
   const seenProducts /*: Set<string> */ = new Set();
   const seenFrameworkIds /*: Set<string> */ = new Set();
   const seenFrameworkNames /*: Set<string> */ = new Set();
+  const seenScriptPhaseIds /*: Set<string> */ = new Set();
 
   for (const {depName, pluginPath, plugin} of plugins) {
     let result /*: unknown */ = null;
@@ -203,11 +221,18 @@ function invokePlugins(
     const rawFrameworks = result.flavoredFrameworks ?? [];
     // $FlowFixMe[incompatible-use]
     const rawWatch = result.watchPaths ?? [];
+    // $FlowFixMe[incompatible-use]
+    const rawScriptPhases = result.scriptPhases ?? [];
     if (!Array.isArray(rawFrameworks)) {
       throw new Error(
         `react-native spm: '${depName}' returned a non-array flavoredFrameworks.`,
       );
     }
+    if (!Array.isArray(rawScriptPhases)) {
+      throw new Error(
+        `react-native spm: '${depName}' returned a non-array scriptPhases.`,
+      );
+    }
     // Watch paths are best-effort staleness hints, so
     // a non-array is ignored (warn, never fatal).
     if (!Array.isArray(rawWatch)) {
@@ -314,6 +339,60 @@ function invokePlugins(
       }
       watchPaths.push(w);
     }
+    // Fatal like flavoredFrameworks, not dropped like watchPaths: a missing
+    // phase produces a GREEN build whose generated content was never written.
+    for (const phase of rawScriptPhases) {
+      if (
+        phase == null ||
+        !isValidScriptPhaseId(phase.id) ||
+        !isNonEmptyString(phase.script) ||
+        (phase.position != null &&
+          phase.position !== 'beforeCompile' &&
+          phase.position !== 'end') ||
+        !isOptionalStringList(phase.inputPaths) ||
+        !isOptionalStringList(phase.outputPaths) ||
+        (phase.alwaysOutOfDate != null &&
+          typeof phase.alwaysOutOfDate !== 'boolean')
+      ) {
+        const named = typeof phase?.id === 'string' ? ` '${phase.id}'` : '';
+        throw new Error(
+          `react-native spm: '${depName}' returned an invalid scriptPhase${named} ` +
+            '(need {id (matching /^[@A-Za-z0-9_./-]+$/, and not __proto__, ' +
+            'constructor or prototype), name, script} plus optional ' +
+            '{position: "beforeCompile" | "end", inputPaths, outputPaths, ' +
+            'alwaysOutOfDate}).',
+        );
+      }
+      if (!isValidScriptPhaseName(phase.name)) {
+        throw new Error(
+          `react-native spm: '${depName}' returned an invalid scriptPhase name for ` +
+            `'${phase.id}' (a name must be a non-empty single-line string — it is ` +
+            "the phase's display name in Xcode).",
+        );
+      }
+      if (seenScriptPhaseIds.has(phase.id)) {
+        throw new Error(
+          `react-native spm: duplicate script phase id '${phase.id}'.`,
+        );
+      }
+      seenScriptPhaseIds.add(phase.id);
+      const normalized /*: PluginScriptPhase */ = {
+        id: phase.id,
+        name: phase.name,
+        script: phase.script,
+        position: phase.position ?? 'end',
+      };
+      if (phase.inputPaths != null) {
+        normalized.inputPaths = [...phase.inputPaths];
+      }
+      if (phase.outputPaths != null) {
+        normalized.outputPaths = [...phase.outputPaths];
+      }
+      if (phase.alwaysOutOfDate != null) {
+        normalized.alwaysOutOfDate = phase.alwaysOutOfDate;
+      }
+      scriptPhases.push(normalized);
+    }
   }
 
   return {
@@ -322,6 +401,7 @@ function invokePlugins(
     generatedSources,
     flavoredFrameworks,
     watchPaths,
+    scriptPhases,
   };
 }
 

package/scripts/spm/download-spm-artifacts.js

@@ -393,15 +393,63 @@ async function resolveRNDepsArtifact(
   return {url: snapshotUrl, version};
 }
 
+/**
+ * Resolves the `hermes-compiler` npm package's version from THIS project's own
+ * node_modules — the exact same lookup generate-spm-xcodeproj.js's
+ * resolveHermesCliPathSetting() uses to find the hermesc binary that will
+ * compile the JS bundle, and the same one react-native-xcode.sh falls back to
+ * for SwiftPM builds. Returns null when the package isn't resolvable (e.g.
+ * USE_HERMES=false apps that never installed it) so the caller can fall back
+ * to the npm dist-tag lookup.
+ */
+function resolveLocalHermesCompilerVersion(
+  rnRoot /*: string */,
+) /*: string | null */ {
+  try {
+    const pkgPath = require.resolve('hermes-compiler/package.json', {
+      paths: [rnRoot],
+    });
+    // $FlowFixMe[incompatible-type] JSON.parse returns any
+    const pkg /*: {version: string} */ = JSON.parse(
+      fs.readFileSync(pkgPath, 'utf8'),
+    );
+    assertSafeVersion(pkg.version, 'local hermes-compiler/package.json');
+    return pkg.version;
+  } catch (error) {
+    // A MODULE_NOT_FOUND resolution failure is the expected case (e.g.
+    // USE_HERMES=false apps that never installed hermes-compiler) — fall back
+    // silently. Any other failure means hermes-compiler IS installed but its
+    // package.json is unreadable/malformed or carries an unsafe version; warn
+    // loudly rather than silently regressing to the live latest-v1 dist-tag,
+    // which would re-introduce the version-skew crash this resolves (#57917).
+    if (error.code !== 'MODULE_NOT_FOUND') {
+      log(
+        `  WARNING: hermes-compiler is installed but its version could not be resolved (${error.message}); falling back to the latest-v1 dist-tag, which may not match the pinned hermesc and can crash at launch with "Wrong bytecode version".`,
+      );
+    }
+    return null;
+  }
+}
+
 /**
  * Returns {url, version} for Hermes. Hermes uses its own version space
  * decoupled from React Native's nightly cadence — RN's `hermes-compiler`
  * npm package publishes a `latest-v1` dist-tag that always resolves to a
- * binary that's been built and uploaded to Maven. Our default mirrors RN's
- * CocoaPods prebuild path (see scripts/ios-prebuild/hermes.js):
+ * binary that's been built and uploaded to Maven.
  *
- *   HERMES_VERSION unset       → 'latest-v1' dist-tag
- *   HERMES_VERSION=latest-v1   → same (explicit)
+ *   HERMES_VERSION unset       → version pinned by the locally installed
+ *                                hermes-compiler package (node_modules).
+ *                                This is the SAME source
+ *                                resolveHermesCliPathSetting() reads for
+ *                                HERMES_CLI_PATH, so the downloaded VM and
+ *                                the hermesc that compiles the JS bundle
+ *                                always agree — a mismatched pair crashes at
+ *                                launch with "Wrong bytecode version" (#57917).
+ *                                Falls back to the 'latest-v1' npm dist-tag
+ *                                (RN's CocoaPods prebuild default; see
+ *                                scripts/ios-prebuild/hermes.js) only when
+ *                                hermes-compiler isn't locally resolvable.
+ *   HERMES_VERSION=latest-v1   → 'latest-v1' dist-tag (explicit)
  *   HERMES_VERSION=nightly     → hermes-compiler@nightly dist-tag
  *   HERMES_VERSION=<literal>   → use that version verbatim
  *
@@ -413,8 +461,17 @@ async function resolveHermesArtifact(
   rnVersion /*: string */,
   flavor /*: string */,
   rawVersion /*: string | null */,
+  rnRoot /*: string */,
 ) /*: Promise<ResolvedArtifact> */ {
-  let version = process.env.HERMES_VERSION ?? 'latest-v1';
+  let version = process.env.HERMES_VERSION;
+
+  if (version == null) {
+    const localVersion = resolveLocalHermesCompilerVersion(rnRoot);
+    if (localVersion != null) {
+      log(`  Using locally pinned hermes-compiler: ${localVersion}`);
+    }
+    version = localVersion ?? 'latest-v1';
+  }
 
   if (version === 'nightly') {
     version = await resolveNightlyVersion('hermes-compiler');
@@ -1119,7 +1176,7 @@ async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
       label: 'hermes',
       name: 'hermes-engine',
       resolve: () =>
-        resolveHermesArtifact(resolvedRnVersion, flavor, rawVersion),
+        resolveHermesArtifact(resolvedRnVersion, flavor, rawVersion, rnRoot),
       sharedName: (v /*: string */) => `hermes-ios-${v}-${flavor}.tar.gz`,
     },
   ];
@@ -1390,6 +1447,7 @@ module.exports = {
   main,
   resolveCacheSlotVersion,
   resolveHermesArtifact,
+  resolveLocalHermesCompilerVersion,
   REQUIRED_ARTIFACTS,
   validateArtifactsCache,
   // Exposed for unit tests (pure / fetch-stubbable helpers).