expo-modules-jsi 56.0.1 → 56.0.3

package/CHANGELOG.md

@@ -10,6 +10,19 @@
 
 ### 💡 Others
 
+## 56.0.3 — 2026-05-11
+
+### 🐛 Bug fixes
+
+- [iOS] Fixed launch-time crash in apps with source-built React Native. ([#45636](https://github.com/expo/expo/pull/45636) by [@tsapeta](https://github.com/tsapeta))
+
+## 56.0.2 — 2026-05-08
+
+### 🐛 Bug fixes
+
+- [iOS] Fixed `ExpoModulesJSI.xcframework` build failing under `useFrameworks: "static"` + `buildReactNativeFromSource: true` due to missing header search paths. ([#45508](https://github.com/expo/expo/pull/45508) by [@chrfalch](https://github.com/chrfalch))
+- [iOS] Fixed missing slices in `ExpoModulesJSI.xcframework` causing `No such module 'ExpoModulesJSI'` build errors. ([#45542](https://github.com/expo/expo/pull/45542) by [@tsapeta](https://github.com/tsapeta))
+
 ## 56.0.1 — 2026-05-06
 
 _This version does not introduce any user-facing changes._

package/apple/ExpoModulesJSI.podspec

@@ -51,7 +51,6 @@ Pod::Spec.new do |s|
 
   s.dependency 'React-Core'
   s.dependency 'ReactCommon'
-  s.dependency 'React-runtimescheduler'
 
   # Create a stub xcframework if needed, so CocoaPods generates the
   # "[CP] Copy XCFrameworks" and "[CP] Embed Pods Frameworks" build phases.

package/apple/Package.swift

@@ -7,15 +7,19 @@ import Foundation
 let packageDir = URL(fileURLWithPath: #filePath).deletingLastPathComponent().path
 let podsRoot = resolvePodsRoot()
 
-// Header roots needed by ExpoModulesJSI and ExpoModulesJSI-Cxx. The same paths
-// exist in both prebuilt and source-built React Native layouts, so we don't
-// need to detect the mode.
+// Header roots for ExpoModulesJSI and ExpoModulesJSI-Cxx. The
+// Pods/Headers/Public paths cover no-frameworks and prebuilt-RN; the trailing
+// entries fall back to canonical sources for the static + source-built RN
+// combo, where each React-X / third-party-deps pod compiles as a static
+// framework and its headers don't get mirrored to Pods/Headers/Public. Clang
+// ignores missing `-I` paths, so they're no-ops elsewhere. `RN_ROOT` is
+// forwarded from build-xcframework.sh (Node-resolved for hoisted monorepos).
+// `REACT_NATIVE_PATH` is exported by Xcode for hosts that build RN from a
+// non-npm location, e.g. Expo Go.
 let publicHeaders = "\(podsRoot)/Headers/Public"
-// In source-built RN, third-party deps (folly, boost, etc.) live under
-// per-pod dirs like RCT-Folly/folly/. In prebuilt RN they're bundled into
-// ReactNativeDependencies. Some pods nest their headers (e.g. RCT-Folly/folly/),
-// others place them directly (e.g. boost/preprocessor/), so we include both
-// the Headers/Public root and the per-pod dirs for the nested ones.
+let reactNative = ProcessInfo.processInfo.environment["RN_ROOT"]
+  ?? ProcessInfo.processInfo.environment["REACT_NATIVE_PATH"]
+  ?? "\(podsRoot)/../../node_modules/react-native"
 let headerSearchPaths = [
   publicHeaders,
   "\(publicHeaders)/React-jsi",
@@ -33,6 +37,14 @@ let headerSearchPaths = [
   "\(publicHeaders)/DoubleConversion",
   "\(publicHeaders)/fmt",
   "\(publicHeaders)/fast_float",
+  "\(reactNative)/ReactCommon",
+  "\(reactNative)/ReactCommon/jsi",
+  "\(reactNative)/ReactCommon/runtimeexecutor",
+  "\(reactNative)/ReactCommon/callinvoker",
+  "\(podsRoot)/RCT-Folly",
+  "\(podsRoot)/fmt/include",
+  "\(podsRoot)/glog/src",
+  "\(podsRoot)/DoubleConversion",
 ]
 
 // Path to the generated module map for the `jsi` Clang module. The

package/apple/Sources/ExpoModulesJSI/Runtime/JavaScriptRuntime.swift

@@ -38,28 +38,55 @@ open class JavaScriptRuntime: Equatable, @unchecked Sendable {
   lazy var runtimeActor: JavaScriptRuntimeActor = JavaScriptRuntimeActor(runtime: self)
 
   /**
-   Creates a runtime from the JSI runtime.
+   Creates a runtime from the JSI runtime. The scheduler runs tasks synchronously
+   on the caller's thread — for the React-backed runtime, use
+   `init(unsafePointer:nativeScheduler:dispatch:)` instead.
    */
   internal init(_ runtime: facebook.jsi.Runtime) {
     self.pointee = runtime
-    self.scheduler = expo.RuntimeScheduler(runtime)
+    self.scheduler = expo.RuntimeScheduler()
   }
 
   /**
-   Creates Hermes runtime.
+   Creates a standalone Hermes runtime. Scheduled tasks run synchronously —
+   no React scheduler is wired up.
    */
   public init() {
     self.pointee = expo.createHermesRuntime()
-    self.scheduler = expo.RuntimeScheduler(pointee)
+    self.scheduler = expo.RuntimeScheduler()
   }
 
   /**
    Creates a runtime from a raw pointer to the underlying `facebook.jsi.Runtime`.
+   Scheduled tasks run synchronously — for the React-backed runtime, use
+   `init(unsafePointer:nativeScheduler:dispatch:)` instead.
    */
   public init(unsafePointer: UnsafeMutableRawPointer) {
     let runtime = unsafeBitCast(unsafePointer, to: facebook.jsi.Runtime.self)
     self.pointee = runtime
-    self.scheduler = expo.RuntimeScheduler(runtime)
+    self.scheduler = expo.RuntimeScheduler()
+  }
+
+  /**
+   Creates a runtime bound to a host-provided React `RuntimeScheduler`. Calls to
+   `schedule(...)` / `.execute(...)` dispatch through `dispatch`, which the host
+   implements against the real `react::RuntimeScheduler`. This is the path the
+   React Native factory uses.
+
+   - `unsafePointer`: raw pointer to the underlying `facebook::jsi::Runtime`.
+   - `scheduler`: raw pointer to the `react::RuntimeScheduler` instance.
+   - `dispatch`: raw pointer to a C function with signature
+     `void (*)(void *scheduler, int priority, void (^callback)())`.
+   */
+  public init(
+    unsafePointer: UnsafeMutableRawPointer,
+    scheduler: UnsafeMutableRawPointer,
+    dispatch: UnsafeRawPointer
+  ) {
+    let runtime = unsafeBitCast(unsafePointer, to: facebook.jsi.Runtime.self)
+    let fn = unsafeBitCast(dispatch, to: expo.RuntimeScheduler.ScheduleFn.self)
+    self.pointee = runtime
+    self.scheduler = expo.RuntimeScheduler(scheduler, fn)
   }
 
   /**
@@ -348,8 +375,8 @@ open class JavaScriptRuntime: Equatable, @unchecked Sendable {
    Schedules a closure to be executed with granted synchronized access to the runtime.
    */
   public func schedule(priority: SchedulerPriority = .normal, @_implicitSelfCapture _ closure: @escaping @JavaScriptActor () -> sending Void) -> Void {
-    let reactPriority = facebook.react.SchedulerPriority(rawValue: priority.rawValue) ?? .NormalPriority
-    scheduler.scheduleTask(reactPriority) {
+    let cxxPriority = expo.RuntimeScheduler.Priority(rawValue: priority.rawValue) ?? .NormalPriority
+    scheduler.scheduleTask(cxxPriority) {
       JavaScriptActor.assumeIsolated(closure)
     }
   }

package/apple/Sources/ExpoModulesJSI-Cxx/include/RuntimeScheduler.h

@@ -2,65 +2,76 @@
 
 #ifdef __cplusplus
 
-#include <memory>
+#include <atomic>
 #include <swift/bridging>
-#include <jsi/jsi.h>
-#include <react/renderer/runtimescheduler/RuntimeScheduler.h>
-#include <react/renderer/runtimescheduler/RuntimeSchedulerBinding.h>
-
-namespace jsi = facebook::jsi;
-namespace react = facebook::react;
 
 namespace expo {
 
 /**
- Wrapper for RuntimeScheduler from React which for some reason cannot be constructed from Swift.
- Imported as a shared reference type so Swift manages its lifetime via retain/release.
+ Wrapper around React Native's RuntimeScheduler. The native scheduler reference
+ and dispatch trampoline are supplied by the host (e.g. ExpoReactNativeFactory)
+ at construction time. The xcframework intentionally avoids linking against
+ React-runtimescheduler so the prebuilt binary works with hosts that build RN
+ either as a dynamic framework or as a static archive — without needing
+ -undefined dynamic_lookup to resolve React internals.
+
+ Priority values mirror facebook::react::SchedulerPriority — kept here as a
+ plain enum so we don't include the React header.
  */
 class RuntimeScheduler {
-private:
-  std::shared_ptr<react::RuntimeScheduler> reactRuntimeScheduler;
+public:
+  enum class Priority : int {
+    ImmediatePriority = 1,
+    UserBlockingPriority = 2,
+    NormalPriority = 3,
+    LowPriority = 4,
+    IdlePriority = 5,
+  };
+
+  using ScheduleTaskCallback = void(^)();
 
   /**
-   Reference count managed by Swift's ARC via SWIFT_SHARED_REFERENCE.
-   Prevents premature deallocation when C++ shared_ptr and Swift references coexist.
+   Trampoline implemented by the host — casts `nativeScheduler` back to
+   react::RuntimeScheduler* and calls scheduleTask on it. Keeping it as a
+   function pointer keeps React types out of this header.
    */
+  using ScheduleFn = void (*)(void *nativeScheduler, int priority, ScheduleTaskCallback callback);
+
+private:
+  void *const nativeScheduler{nullptr};
+  const ScheduleFn scheduleFn{nullptr};
+
   std::atomic<int> refCount{1};
 
 public:
   /**
-   Constructs the scheduler from a React Native runtime binding.
-   Falls back to a no-op scheduler when no binding is installed.
+   Constructs a scheduler bound to a host-provided native RuntimeScheduler.
+   `scheduleTask` dispatches through `fn`, which the host implements against
+   the real react::RuntimeScheduler.
    */
-  RuntimeScheduler(jsi::Runtime &runtime) {
-    if (auto binding = react::RuntimeSchedulerBinding::getBinding(runtime)) {
-      reactRuntimeScheduler = binding->getRuntimeScheduler();
-    }
-  }
+  RuntimeScheduler(void *scheduler, ScheduleFn fn) noexcept
+      : nativeScheduler(scheduler), scheduleFn(fn) {}
 
   /**
-   Constructs a no-op scheduler for standalone runtimes (e.g. tests).
-   Scheduled tasks are executed synchronously by the caller.
+   Constructs a no-op scheduler. Scheduled tasks run synchronously on the
+   caller's thread — intended for standalone runtimes (e.g. tests) that have
+   no React scheduler.
    */
   RuntimeScheduler() {}
 
-  RuntimeScheduler(const RuntimeScheduler &) = delete; // non-copyable
+  RuntimeScheduler(const RuntimeScheduler &) = delete;
 
   /**
    Whether the scheduler can dispatch work asynchronously to the JS thread.
    When false, tasks run synchronously and callers should avoid dispatching to background queues.
    */
   bool supportsAsyncScheduling() const noexcept {
-    return reactRuntimeScheduler != nullptr;
+    return scheduleFn != nullptr;
   }
 
-  using ScheduleTaskCallback = void(^)();
-
-  void scheduleTask(react::SchedulerPriority priority, ScheduleTaskCallback callback) noexcept {
-    if (reactRuntimeScheduler) {
-      reactRuntimeScheduler->scheduleTask(priority, [callback = std::move(callback)](jsi::Runtime &runtime) {
-        callback();
-      });
+  void scheduleTask(Priority priority, ScheduleTaskCallback callback) noexcept {
+    if (scheduleFn != nullptr) {
+      scheduleFn(nativeScheduler, static_cast<int>(priority), callback);
     } else {
       callback();
     }

package/apple/scripts/build-xcframework.sh

@@ -6,8 +6,10 @@
 # but can also be invoked manually with PODS_ROOT set.
 #
 # Features:
-#   - Hash-based caching: skips rebuild if source files haven't changed
-#   - Additive slices: builds only the requested platform, preserves others
+#   - Per-slice hash-based caching: a slice is rebuilt only when its own
+#     recorded source hash differs from the current one. Other slices —
+#     including those built for other platforms in earlier runs — are left
+#     untouched.
 #   - Reads React/JSI/Hermes headers directly from Pods/Headers/Public, so the
 #     same configuration works for both prebuilt and source-built React Native
 #   - Cleans .swiftinterface files for cross-compiler compatibility
@@ -20,13 +22,11 @@
 #   PLATFORM_NAME   (optional) Build for a specific platform (e.g. iphoneos, iphonesimulator).
 #                   When unset, builds for both iphoneos and iphonesimulator.
 
-set -eo pipefail
+set -euo pipefail
 
 PACKAGE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 PACKAGE_NAME="ExpoModulesJSI"
 XCFRAMEWORK_PATH="${PACKAGE_DIR}/Products/${PACKAGE_NAME}.xcframework"
-SLICES_DIR="${PACKAGE_DIR}/.xcframework-slices"
-HASH_FILE="${SLICES_DIR}/.build-hash"
 
 CONFIGURATION="Release"
 DERIVED_DATA_PATH="${PACKAGE_DIR}/.DerivedData"
@@ -34,6 +34,8 @@ SPM_BUILD_PATH="${PACKAGE_DIR}/.build"
 SPM_WORKSPACE_PATH="${PACKAGE_DIR}/.swiftpm"
 BUILD_PRODUCTS_PATH="${DERIVED_DATA_PATH}/Build/Products"
 
+source "${PACKAGE_DIR}/scripts/xcframework-helpers.sh"
+
 CLEAN=false
 
 while [[ $# -gt 0 ]]; do
@@ -49,7 +51,6 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-# Use colors only when stdout is a terminal.
 if [[ -t 1 ]]; then
   BLUE="\033[34m"
   RESET="\033[0m"
@@ -71,9 +72,10 @@ SOURCE_DIRS=(
 SOURCE_FILES=(
   "${PACKAGE_DIR}/Package.swift"
   "${PACKAGE_DIR}/scripts/build-xcframework.sh"
+  "${PACKAGE_DIR}/scripts/create-stub-xcframework.sh"
+  "${PACKAGE_DIR}/scripts/xcframework-helpers.sh"
 )
 
-# Computes a SHA256 hash of all source files.
 compute_hash() {
   local all_files
   all_files=$(
@@ -87,8 +89,10 @@ compute_hash() {
   # Force C locale so sort order is consistent regardless of the environment.
   # Xcode build phases run without locale variables, which changes sort ordering.
   (
-    # Include PODS_ROOT so switching between worktrees invalidates the cache.
+    # Include PODS_ROOT and RN_ROOT so switching between worktrees or RN
+    # sources invalidates the cache.
     echo "PODS_ROOT=${PODS_ROOT:-}"
+    echo "RN_ROOT=${RN_ROOT:-}"
     echo "$all_files" | LC_ALL=C sort | while IFS= read -r file; do
       echo "$file"
       cat "$file"
@@ -111,11 +115,30 @@ platform_destination() {
   esac
 }
 
-# Builds a single framework slice for a given platform and stages it.
+# Resolves the xcframework slice ID that a built platform should land in.
+# Mirrors the slice IDs xcodebuild -create-xcframework would have assigned for
+# a single-arch device build / dual-arch simulator build.
+platform_slice_id() {
+  case "$1" in
+    iphoneos)         echo "ios-arm64" ;;
+    iphonesimulator)  echo "ios-arm64_x86_64-simulator" ;;
+    appletvos)        echo "tvos-arm64" ;;
+    appletvsimulator) echo "tvos-arm64_x86_64-simulator" ;;
+    *)
+      log "error: No slice mapping for platform: $1"
+      exit 1
+      ;;
+  esac
+}
+
+# Builds a single framework slice for the given platform and replaces the
+# matching slice inside XCFRAMEWORK_PATH. Other slices on disk are untouched.
 build_slice() {
   local platform="$1"
   local destination
   destination=$(platform_destination "$platform")
+  local slice_id
+  slice_id=$(platform_slice_id "$platform")
   local build_dir_name="${CONFIGURATION}-${platform}"
 
   log "Building framework slice for ${platform}..."
@@ -124,10 +147,10 @@ build_slice() {
 
   # Use env -i to clear inherited Xcode environment variables from the parent build.
   # Without this, the nested xcodebuild inherits SDKROOT, PLATFORM_NAME, etc.
-  # which causes SDK/platform mismatches. PODS_ROOT is forwarded explicitly
-  # because Package.swift reads it to resolve header search paths.
+  # which causes SDK/platform mismatches. PODS_ROOT and RN_ROOT are forwarded
+  # explicitly because Package.swift reads them to resolve header search paths.
   # Run from PACKAGE_DIR so xcodebuild finds the SPM package, not the Pods project.
-  (cd "$PACKAGE_DIR" && env -i PATH="$PATH" HOME="$HOME" PODS_ROOT="$PODS_ROOT" \
+  (cd "$PACKAGE_DIR" && env -i PATH="$PATH" HOME="$HOME" PODS_ROOT="$PODS_ROOT" RN_ROOT="$RN_ROOT" \
     xcodebuild \
     build \
     -scheme "$PACKAGE_NAME" \
@@ -148,22 +171,29 @@ build_slice() {
   )
 
   local product_path="${BUILD_PRODUCTS_PATH}/${build_dir_name}"
-  local framework_path="${product_path}/PackageFrameworks/${PACKAGE_NAME}.framework"
+  local framework_src="${product_path}/PackageFrameworks/${PACKAGE_NAME}.framework"
   local swiftmodule_src="${product_path}/${PACKAGE_NAME}.swiftmodule"
   local generated_maps="${DERIVED_DATA_PATH}/Build/Intermediates.noindex/GeneratedModuleMaps-${platform}"
 
-  # Stage the built slice for this platform.
-  local slice_staging="${SLICES_DIR}/${platform}"
-  rm -rf "$slice_staging"
-  mkdir -p "$slice_staging"
+  if [[ ! -d "$framework_src" ]]; then
+    log "error: xcodebuild did not produce ${framework_src}"
+    exit 1
+  fi
 
-  cp -r "$framework_path" "$slice_staging/"
+  # Replace the slice in place. Stage to a temp location first so a partial
+  # write can't leave the xcframework in a broken state.
+  local slice_dir="${XCFRAMEWORK_PATH}/${slice_id}"
+  local staging_dir="${XCFRAMEWORK_PATH}/.${slice_id}.new"
+  rm -rf "$staging_dir"
+  mkdir -p "$staging_dir"
+
+  cp -r "$framework_src" "$staging_dir/"
   if [[ -d "${product_path}/${PACKAGE_NAME}.framework.dSYM" ]]; then
-    cp -r "${product_path}/${PACKAGE_NAME}.framework.dSYM" "$slice_staging/"
+    cp -r "${product_path}/${PACKAGE_NAME}.framework.dSYM" "$staging_dir/"
   fi
 
   # Copy Swift module interfaces and generated headers into the staged framework.
-  local modules_dir="${slice_staging}/${PACKAGE_NAME}.framework/Modules"
+  local modules_dir="${staging_dir}/${PACKAGE_NAME}.framework/Modules"
   mkdir -p "$modules_dir"
   cp -r "$swiftmodule_src/" "${modules_dir}/${PACKAGE_NAME}.swiftmodule"
   rm -rf "${modules_dir}/${PACKAGE_NAME}.swiftmodule/Project"
@@ -185,33 +215,15 @@ build_slice() {
   find "${modules_dir}/${PACKAGE_NAME}.swiftmodule" -name '*.swiftinterface' \
     -exec sed -i '' '/^extension __ObjC\./,/^}/d;/^@usableFromInline$/{N;/_ConstraintThatIsNotPartOfTheAPIOfThisLibrary/d;};/_ConstraintThatIsNotPartOfTheAPIOfThisLibrary/d' {} +
 
-  local headers_dir="${slice_staging}/${PACKAGE_NAME}.framework/Headers"
+  local headers_dir="${staging_dir}/${PACKAGE_NAME}.framework/Headers"
   mkdir -p "$headers_dir"
   cp "${generated_maps}/${PACKAGE_NAME}-Swift.h" "$headers_dir/"
   cp "${generated_maps}/${PACKAGE_NAME}.modulemap" "$headers_dir/module.modulemap"
-}
 
-# Assembles the xcframework from all staged slices.
-assemble_xcframework() {
-  rm -rf "$XCFRAMEWORK_PATH"
-
-  local xcframework_args=()
-  for slice_dir in "${SLICES_DIR}"/*/; do
-    local framework="${slice_dir}${PACKAGE_NAME}.framework"
-    local dsym="${slice_dir}${PACKAGE_NAME}.framework.dSYM"
-    if [[ -d "$framework" ]]; then
-      xcframework_args+=(-framework "$framework")
-      if [[ -d "$dsym" ]]; then
-        xcframework_args+=(-debug-symbols "$(cd "$dsym" && pwd)")
-      fi
-    fi
-  done
-
-  xcodebuild -create-xcframework "${xcframework_args[@]}" -output "$XCFRAMEWORK_PATH"
-
-  # Write the hash so subsequent builds can skip if nothing changed.
-  mkdir -p "$SLICES_DIR"
-  echo "$current_hash" > "$HASH_FILE"
+  echo "$current_hash" > "${staging_dir}/.build-hash"
+
+  rm -rf "$slice_dir"
+  mv "$staging_dir" "$slice_dir"
 }
 
 # --- Main ---
@@ -233,6 +245,25 @@ fi
 # whether PODS_ROOT was passed as relative or absolute.
 PODS_ROOT="$(cd "$PODS_ROOT" && pwd)"
 
+# Resolve react-native. Order:
+#   1. REACT_NATIVE_PATH env var (set by Xcode from the Podfile's build setting)
+#      — for hosts that build RN from a non-npm location, e.g. Expo Go which
+#      uses the `react-native-lab/react-native` submodule, not node_modules.
+#   2. `node -p require.resolve(...)` so the script works in any node_modules
+#      layout (hoisted monorepos, pnpm/yarn workspaces).
+#   3. Relative fallback from PODS_ROOT for when `node` isn't on PATH.
+# Forwarded to Package.swift and the modulemap generator below.
+if [[ -n "${REACT_NATIVE_PATH:-}" && -d "${REACT_NATIVE_PATH}" ]]; then
+  RN_ROOT="$(cd "$REACT_NATIVE_PATH" && pwd)"
+else
+  RN_ROOT="$(node -p 'require("path").dirname(require.resolve("react-native/package.json"))' 2>/dev/null \
+    || echo "${PODS_ROOT}/../../node_modules/react-native")"
+fi
+
+mode="$( [[ -d "${PODS_ROOT}/React-Core-prebuilt/React.xcframework" ]] && echo "prebuilt RN" || echo "source-built RN")"
+[[ -f "${PODS_ROOT}/Target Support Files/React-jsi/React-jsi-umbrella.h" ]] && mode="${mode}, static frameworks"
+log "Detected: ${mode} (RN_ROOT=${RN_ROOT})"
+
 # React Native version — forces a rebuild after an RN upgrade. The local
 # podspec is regenerated by `pod install` and only changes when the underlying
 # RN version changes.
@@ -241,17 +272,21 @@ if [[ -f "${PODS_ROOT}/Local Podspecs/React-Core.podspec.json" ]]; then
 fi
 
 # Generate the module map for the `jsi` Clang module.
-env PODS_ROOT="$PODS_ROOT" "${PACKAGE_DIR}/scripts/generate-modulemap.sh"
+env PODS_ROOT="$PODS_ROOT" RN_ROOT="$RN_ROOT" "${PACKAGE_DIR}/scripts/generate-modulemap.sh"
 GENERATED_MODULE_MAP="${PACKAGE_DIR}/.generated/module.modulemap"
 SOURCE_FILES+=("$GENERATED_MODULE_MAP")
 
 if [[ "$CLEAN" == true ]]; then
-  rm -rf "$XCFRAMEWORK_PATH" "$SLICES_DIR" "$DERIVED_DATA_PATH" "$SPM_BUILD_PATH" "$SPM_WORKSPACE_PATH"
-  log "Cleaned existing xcframework, staged slices, DerivedData, and SwiftPM state"
+  rm -rf "$XCFRAMEWORK_PATH" "$DERIVED_DATA_PATH" "$SPM_BUILD_PATH" "$SPM_WORKSPACE_PATH"
+  log "Cleaned existing xcframework, DerivedData, and SwiftPM state"
+  # Re-stamp stub slices so the post-clean state matches a fresh `pod install`:
+  # CocoaPods reads Info.plist before this script runs, and would fail to
+  # resolve any slice not declared there.
+  "${PACKAGE_DIR}/scripts/create-stub-xcframework.sh"
 fi
 
 # Determine which platforms to build.
-if [[ -n "$PLATFORM_NAME" ]]; then
+if [[ -n "${PLATFORM_NAME:-}" ]]; then
   PLATFORMS=("$PLATFORM_NAME")
 else
   PLATFORMS=("iphoneos" "iphonesimulator")
@@ -259,42 +294,31 @@ fi
 
 current_hash=$(compute_hash)
 
-# Check if sources have changed since the last build.
-if [[ -f "$HASH_FILE" ]]; then
-  previous_hash=$(cat "$HASH_FILE")
-  if [[ "$current_hash" == "$previous_hash" ]]; then
-    # Sources haven't changed — filter out platforms that already have a staged slice.
-    platforms_to_build=()
-    for platform in "${PLATFORMS[@]}"; do
-      if [[ ! -d "${SLICES_DIR}/${platform}/${PACKAGE_NAME}.framework" ]]; then
-        platforms_to_build+=("$platform")
-      fi
-    done
-
-    if [[ ${#platforms_to_build[@]} -eq 0 ]]; then
-      log "xcframework is up to date, skipping build"
-      exit 0
-    fi
-
-    PLATFORMS=("${platforms_to_build[@]}")
-  else
-    # Sources changed — remove all staged slices so they get rebuilt.
-    # Also wipe DerivedData and .build because Swift Package Manager caches
-    # the resolved package graph there and Package.swift reads PODS_ROOT at
-    # resolve time; without this, switching PODS_ROOT (e.g. between apps)
-    # leaks paths from the previous resolution into the new build.
-    log "Source files changed, rebuilding all slices"
-    rm -rf "$SLICES_DIR" "$XCFRAMEWORK_PATH" "$DERIVED_DATA_PATH" "$SPM_BUILD_PATH" "$SPM_WORKSPACE_PATH"
+# Filter out platforms whose slice is already up to date.
+platforms_to_build=()
+for platform in "${PLATFORMS[@]}"; do
+  slice_id=$(platform_slice_id "$platform")
+  slice_hash_file="${XCFRAMEWORK_PATH}/${slice_id}/.build-hash"
+  if [[ -f "$slice_hash_file" ]] && [[ "$(cat "$slice_hash_file")" == "$current_hash" ]]; then
+    continue
   fi
+  platforms_to_build+=("$platform")
+done
+
+if [[ ${#platforms_to_build[@]} -eq 0 ]]; then
+  log "xcframework slices up to date, skipping build"
+  exit 0
 fi
 
+PLATFORMS=("${platforms_to_build[@]}")
+
 SECONDS=0
 
 for platform in "${PLATFORMS[@]}"; do
   build_slice "$platform"
 done
 
-assemble_xcframework
+write_xcframework_plist "$XCFRAMEWORK_PATH" "$PACKAGE_NAME"
 
-SLICE_NAMES=$(for d in "${XCFRAMEWORK_PATH}"/*/; do basename "$d"; done | paste -sd', ' - | sed 's/,/, /g')
+SLICE_NAMES=$(for d in "${XCFRAMEWORK_PATH}"/*/; do basename "$d"; done | LC_ALL=C sort | tr '\n' ',' | sed 's/,$//;s/,/, /g')
 log "Built xcframework successfully in ${SECONDS}s (${SLICE_NAMES})"

package/apple/scripts/create-stub-xcframework.sh

@@ -1,102 +1,57 @@
 #!/bin/bash
 
-# Creates a stub xcframework with a minimal dynamic library so that
-# CocoaPods detects it as a dynamic framework and generates the
-# "[CP] Copy XCFrameworks" and "[CP] Embed Pods Frameworks" build phases.
-# The real xcframework is built by the build-xcframework.sh script at build time.
+# Ensures every required slice in ExpoModulesJSI.xcframework exists with at
+# least a stub binary so CocoaPods detects the package as a dynamic framework
+# and generates the "[CP] Copy XCFrameworks" and "[CP] Embed Pods Frameworks"
+# build phases for every supported platform. The real xcframework is built by
+# build-xcframework.sh at build time.
+#
+# Non-destructive: existing slice binaries (real or stub) are kept; only
+# missing required slices are stamped. Info.plist is rewritten from whatever
+# slices are on disk so additional slices built via Xcode survive.
 
-set -eo pipefail
+set -euo pipefail
 
 PACKAGE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 PACKAGE_NAME="ExpoModulesJSI"
 XCFRAMEWORK_PATH="${PACKAGE_DIR}/Products/${PACKAGE_NAME}.xcframework"
 
-# Use colors only when run in the terminal
+source "$(dirname "${BASH_SOURCE[0]}")/xcframework-helpers.sh"
+
 BLUE=""; RESET=""
 if [ -t 1 ]; then
   BLUE="\033[34m"
   RESET="\033[0m"
 fi
-echo -e "${BLUE}[Expo]${RESET} Creating stub xcframework for ${PACKAGE_NAME}"
-
-# Platform slices the podspec supports. CocoaPods reads Info.plist at
-# `pod install` time to generate per-slice cases in its xcframework copy
-# script, so every SDK we want to build for must appear here.
-#
-# Format: slice_id|platform|variant|archs
-SLICES=(
-  "ios-arm64|ios||arm64"
-  "ios-arm64_x86_64-simulator|ios|simulator|arm64 x86_64"
-  "tvos-arm64|tvos||arm64"
-  "tvos-arm64_x86_64-simulator|tvos|simulator|arm64 x86_64"
-)
-
-# Always regenerate the Info.plist so it declares every slice. A previous
-# build may have produced an xcframework with only the target platform's
-# slice (e.g. device-only or simulator-only), which would cause CocoaPods
-# to generate a copy script that is missing the other variant.
+echo -e "${BLUE}[Expo]${RESET} Ensuring required slices in ${PACKAGE_NAME}.xcframework"
 
 # The stub binary is only inspected by CocoaPods at install time to detect
 # that this is a dynamic framework — it is never linked against (the real
 # xcframework replaces it before the sources compile). Compile it once and
-# reuse the same binary for every slice.
-STUB_SOURCE="${XCFRAMEWORK_PATH}/.stub-binary"
+# reuse the same binary for every slice that needs stamping.
 mkdir -p "$XCFRAMEWORK_PATH"
+STUB_SOURCE="${XCFRAMEWORK_PATH}/.stub-binary"
 echo "" | clang -x c - -dynamiclib \
   -o "$STUB_SOURCE" \
   -install_name "@rpath/${PACKAGE_NAME}.framework/${PACKAGE_NAME}"
 
-available_libraries=""
-for slice in "${SLICES[@]}"; do
-  IFS='|' read -r slice_id platform variant archs <<<"$slice"
-  slice_dir="${XCFRAMEWORK_PATH}/${slice_id}/${PACKAGE_NAME}.framework"
-  mkdir -p "$slice_dir"
-  if [[ ! -f "${slice_dir}/${PACKAGE_NAME}" ]]; then
-    cp "$STUB_SOURCE" "${slice_dir}/${PACKAGE_NAME}"
-  fi
-
-  arch_entries=""
-  for arch in $archs; do
-    arch_entries+="        <string>${arch}</string>
-"
-  done
+for slice_id in "${EXPO_MODULES_JSI_REQUIRED_SLICE_IDS[@]}"; do
+  slice_dir="${XCFRAMEWORK_PATH}/${slice_id}"
+  framework_dir="${slice_dir}/${PACKAGE_NAME}.framework"
+  binary_path="${framework_dir}/${PACKAGE_NAME}"
+  hash_file="${slice_dir}/.build-hash"
 
-  variant_entry=""
-  if [[ -n "$variant" ]]; then
-    variant_entry="      <key>SupportedPlatformVariant</key>
-      <string>${variant}</string>
-"
+  mkdir -p "$framework_dir"
+  if [[ ! -f "$binary_path" ]]; then
+    cp "$STUB_SOURCE" "$binary_path"
+  fi
+  # Empty hash marks the slice as a stub. build-xcframework.sh treats any
+  # mismatch (including stub vs. real source hash) as needing a rebuild.
+  if [[ ! -f "$hash_file" ]]; then
+    : > "$hash_file"
   fi
-
-  available_libraries+="    <dict>
-      <key>BinaryPath</key>
-      <string>${PACKAGE_NAME}.framework/${PACKAGE_NAME}</string>
-      <key>LibraryIdentifier</key>
-      <string>${slice_id}</string>
-      <key>LibraryPath</key>
-      <string>${PACKAGE_NAME}.framework</string>
-      <key>SupportedArchitectures</key>
-      <array>
-${arch_entries}      </array>
-      <key>SupportedPlatform</key>
-      <string>${platform}</string>
-${variant_entry}    </dict>
-"
 done
+
 rm -f "$STUB_SOURCE"
 
-cat > "${XCFRAMEWORK_PATH}/Info.plist" <<PLIST
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>AvailableLibraries</key>
-  <array>
-${available_libraries}  </array>
-  <key>CFBundlePackageType</key>
-  <string>XFWK</string>
-  <key>XCFrameworkFormatVersion</key>
-  <string>1.0</string>
-</dict>
-</plist>
-PLIST
+write_xcframework_plist "$XCFRAMEWORK_PATH" "$PACKAGE_NAME"

package/apple/scripts/generate-modulemap.sh

@@ -3,11 +3,13 @@
 # Writes `.generated/module.modulemap` for the `jsi` Clang module.
 #
 # The umbrella header is referenced by absolute path so the modulemap works
-# regardless of where Pods lives. The same Pods/Headers/Public/React-jsi/jsi/jsi.h
-# path exists in both prebuilt and source-built React Native layouts. Stored
-# outside `.build/` so SwiftPM state can be wiped without losing this file.
+# regardless of where Pods lives. The `Pods/Headers/Public` path exists in
+# non-frameworks and prebuilt-RN layouts; under static frameworks +
+# source-built RN it doesn't, so we fall back to the canonical RN source.
+# Stored outside `.build/` so SwiftPM state can be wiped without losing this
+# file.
 #
-# Idempotent: re-running with the same PODS_ROOT rewrites identical content.
+# Idempotent: re-running with the same inputs rewrites identical content.
 # Switching PODS_ROOT updates the umbrella header path.
 #
 # Used by build-xcframework.sh and test.sh; can also be run manually before
@@ -34,10 +36,20 @@ GENERATED_DIR="${PACKAGE_DIR}/.generated"
 GENERATED_MODULE_MAP="${GENERATED_DIR}/module.modulemap"
 mkdir -p "$GENERATED_DIR"
 
+JSI_UMBRELLA="${PODS_ROOT}/Headers/Public/React-jsi/jsi/jsi.h"
+if [[ ! -f "$JSI_UMBRELLA" ]]; then
+  # Resolution order matches build-xcframework.sh: RN_ROOT (forwarded by the
+  # build script), REACT_NATIVE_PATH (exported by Xcode for hosts like Expo Go
+  # that build RN from a submodule), node resolve, then a relative fallback.
+  RN="${RN_ROOT:-${REACT_NATIVE_PATH:-$(node -p 'require("path").dirname(require.resolve("react-native/package.json"))' 2>/dev/null || echo "${PODS_ROOT}/../../node_modules/react-native")}}"
+  JSI_UMBRELLA="${RN}/ReactCommon/jsi/jsi/jsi.h"
+fi
+[[ -f "$JSI_UMBRELLA" ]] || { echo "error: cannot locate jsi.h" >&2; exit 1; }
+
 # Avoid touching the file when contents would be identical, so the xcframework
-# hash cache and Xcode don't see a spurious change when PODS_ROOT is unchanged.
+# hash cache and Xcode don't see a spurious change when inputs are unchanged.
 NEW_CONTENT="module jsi {
-  umbrella header \"${PODS_ROOT}/Headers/Public/React-jsi/jsi/jsi.h\"
+  umbrella header \"${JSI_UMBRELLA}\"
 
   export *
   module * { export * }

package/apple/scripts/xcframework-helpers.sh

@@ -0,0 +1,124 @@
+# Shared helpers for managing ExpoModulesJSI.xcframework.
+#
+# Sourced by create-stub-xcframework.sh and build-xcframework.sh. Defines the
+# canonical slice metadata and the Info.plist writer used by both scripts so
+# the manifest is produced from a single place.
+
+# All slice IDs known to the xcframework, mapped to their plist metadata.
+# CocoaPods reads Info.plist at `pod install` time and generates a per-slice
+# copy script; any slice missing from this table will be skipped by
+# write_xcframework_plist with a warning.
+#
+# Format: slice_id|platform|variant|archs
+EXPO_MODULES_JSI_KNOWN_SLICES=(
+  "ios-arm64|ios||arm64"
+  "ios-arm64_x86_64-simulator|ios|simulator|arm64 x86_64"
+  "tvos-arm64|tvos||arm64"
+  "tvos-arm64_x86_64-simulator|tvos|simulator|arm64 x86_64"
+)
+
+# Slice IDs the xcframework must always declare, even when only a subset has
+# been built. The stub script materializes empty placeholders for any of these
+# missing on disk so CocoaPods can wire up copy/embed phases for every target
+# the podspec supports.
+EXPO_MODULES_JSI_REQUIRED_SLICE_IDS=(
+  "ios-arm64"
+  "ios-arm64_x86_64-simulator"
+  "tvos-arm64"
+  "tvos-arm64_x86_64-simulator"
+)
+
+# xcframework_slice_descriptor SLICE_ID
+# Echoes the descriptor row for SLICE_ID, or returns 1 if SLICE_ID is unknown.
+xcframework_slice_descriptor() {
+  local slice_id="$1"
+  local entry
+  for entry in "${EXPO_MODULES_JSI_KNOWN_SLICES[@]}"; do
+    if [[ "${entry%%|*}" == "$slice_id" ]]; then
+      echo "$entry"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# write_xcframework_plist XCFRAMEWORK_PATH PACKAGE_NAME
+# Writes Info.plist describing every slice directory currently inside
+# XCFRAMEWORK_PATH. Slices are sorted by ID for deterministic output. Slice
+# directories not listed in EXPO_MODULES_JSI_KNOWN_SLICES are skipped with a
+# warning so callers can spot missing metadata instead of silently shipping a
+# slice CocoaPods can't describe.
+write_xcframework_plist() {
+  local xcframework_path="$1"
+  local package_name="$2"
+
+  local slice_dirs=()
+  local entry
+  for entry in "${xcframework_path}"/*/; do
+    [[ -d "$entry" ]] || continue
+    slice_dirs+=("$(basename "$entry")")
+  done
+
+  local sorted_slices=()
+  while IFS= read -r line; do
+    sorted_slices+=("$line")
+  done < <(printf '%s\n' "${slice_dirs[@]}" | LC_ALL=C sort)
+
+  local available_libraries=""
+  local slice_id
+  for slice_id in "${sorted_slices[@]}"; do
+    local descriptor
+    if ! descriptor=$(xcframework_slice_descriptor "$slice_id"); then
+      echo "warning: skipping slice '${slice_id}' — not in EXPO_MODULES_JSI_KNOWN_SLICES" >&2
+      continue
+    fi
+
+    local platform variant archs
+    IFS='|' read -r _ platform variant archs <<<"$descriptor"
+
+    local arch_entries=""
+    local arch
+    for arch in $archs; do
+      arch_entries+="        <string>${arch}</string>
+"
+    done
+
+    local variant_entry=""
+    if [[ -n "$variant" ]]; then
+      variant_entry="      <key>SupportedPlatformVariant</key>
+      <string>${variant}</string>
+"
+    fi
+
+    available_libraries+="    <dict>
+      <key>BinaryPath</key>
+      <string>${package_name}.framework/${package_name}</string>
+      <key>LibraryIdentifier</key>
+      <string>${slice_id}</string>
+      <key>LibraryPath</key>
+      <string>${package_name}.framework</string>
+      <key>SupportedArchitectures</key>
+      <array>
+${arch_entries}      </array>
+      <key>SupportedPlatform</key>
+      <string>${platform}</string>
+${variant_entry}    </dict>
+"
+  done
+
+  cat > "${xcframework_path}/Info.plist" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>AvailableLibraries</key>
+  <array>
+${available_libraries}  </array>
+  <key>CFBundlePackageType</key>
+  <string>XFWK</string>
+  <key>XCFrameworkFormatVersion</key>
+  <string>1.0</string>
+</dict>
+</plist>
+PLIST
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-modules-jsi",
-  "version": "56.0.1",
+  "version": "56.0.3",
   "description": "The JavaScript Interface for Expo Modules",
   "main": "index.js",
   "sideEffects": [],
@@ -41,7 +41,7 @@
       "./apple/scripts/test.sh"
     ]
   },
-  "gitHead": "a8ab3da510a34b7bdb2262aa9887d4f78b102280",
+  "gitHead": "42013232893cb2aa71ab218e9b422d4a8476b3f0",
   "scripts": {
     "build": "apple/scripts/build-xcframework.sh",
     "test": "apple/scripts/test.sh"