@onekeyfe/react-native-split-bundle-loader 3.0.63 → 3.0.65

package/android/CMakeLists.txt

@@ -0,0 +1,51 @@
+cmake_minimum_required(VERSION 3.13)
+
+# Native (JNI) side of the SplitBundleLoader module.
+#
+# WHY THIS EXISTS:
+# The Kotlin `loadSegment` previously called `ReactContext.registerSegment`,
+# whose completion callback fires BEFORE the segment bytecode is evaluated
+# into the runtime (the C++ ReactInstance::registerSegment only ENQUEUES the
+# eval onto the RuntimeScheduler and returns). That races Metro's
+# `import().then(() => __r(moduleId))` and can produce a fatal, uncatchable
+# "Requiring unknown module".
+#
+# This library evaluates the segment OURSELVES on the JS thread via the
+# bridgeless CallInvoker (which receives `jsi::Runtime&`) and signals
+# completion in that SAME callback, so eval + resolve are one atomic unit —
+# mirroring the iOS `callFunctionOnBufferedRuntimeExecutor:` fix.
+project(splitbundleloader)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+
+add_library(
+  splitbundleloader
+  SHARED
+  src/main/cpp/SplitBundleLoaderJSI.cpp
+)
+
+target_include_directories(
+  splitbundleloader
+  PRIVATE
+  src/main/cpp
+)
+
+# jsi, reactnative (which carries CallInvoker / CallInvokerHolder headers and
+# the merged libreactnative.so), and fbjni are all prefab targets exposed by
+# the react-android AAR. See ReactAndroid build.gradle.kts prefab entries:
+#   - jsi               (../ReactCommon/jsi/)
+#   - reactnative       (turbomodule/ReactCommon/CallInvokerHolder.h,
+#                        callinvoker/ReactCommon/CallInvoker.h, ...)
+find_package(ReactAndroid REQUIRED CONFIG)
+find_package(fbjni REQUIRED CONFIG)
+
+target_link_libraries(
+  splitbundleloader
+  android
+  log
+  fbjni::fbjni
+  ReactAndroid::jsi
+  ReactAndroid::reactnative
+)

package/android/build.gradle

@@ -33,10 +33,36 @@ android {
   defaultConfig {
     minSdkVersion getExtOrIntegerDefault("minSdkVersion")
     targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        // C++20 to match React Native's prefab targets.
+        cppFlags "-O2", "-frtti", "-fexceptions", "-std=c++20"
+        // The react-android / hermestooling prefab targets are built against
+        // the shared STL; without this the default static STL is selected and
+        // CMake configure fails ("static STL but library requires a shared
+        // STL [//ReactAndroid/hermestooling]"). Matches react-native-background-thread.
+        arguments "-DANDROID_STL=c++_shared"
+        // Only build the ABIs the app ships.
+        abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
+      }
+    }
   }
 
   buildFeatures {
     buildConfig true
+    // Consume react-android / fbjni prefab packages (jsi, reactnative, fbjni)
+    // from the AAR for the native (JNI) side.
+    prefab true
+  }
+
+  // Native (JNI) side: evaluates split-bundle segments on the JS thread and
+  // resolves the promise strictly AFTER eval (fixes the "Requiring unknown
+  // module" race). See src/main/cpp/SplitBundleLoaderJSI.cpp.
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
   }
 
   buildTypes {

package/android/src/main/cpp/SplitBundleLoaderJSI.cpp

@@ -0,0 +1,239 @@
+/*
+ * SplitBundleLoaderJSI.cpp
+ *
+ * JNI bridge that evaluates a Metro split-bundle segment into the CURRENT
+ * Hermes runtime and signals completion ONLY AFTER the segment's `__d(...)`
+ * module definitions have actually run.
+ *
+ * WHY THIS EXISTS — the "Requiring unknown module" race:
+ * The previous Kotlin implementation called `ReactContext.registerSegment`,
+ * which routes (bridgeless) through `ReactHostImpl.registerSegment` →
+ * `ReactInstance.registerSegment` → C++ `ReactInstance::registerSegment`, and
+ * that only does `runtimeScheduler_->scheduleWork([]{ evaluateJavaScript() })`
+ * — i.e. it ENQUEUES the eval and returns. `ReactHostImpl.registerSegment`
+ * then invokes the completion callback immediately on `Task.IMMEDIATE_EXECUTOR`,
+ * so the loadSegment promise resolves BEFORE the segment is evaluated. Metro's
+ * `import().then(() => __r(moduleId))` microtask can therefore run `__r` before
+ * the module table is populated → a fatal, uncatchable "Requiring unknown
+ * module" inside metroRequire.
+ *
+ * THE FIX (mirrors iOS callFunctionOnBufferedRuntimeExecutor:):
+ * We evaluate the segment OURSELVES on the JS thread via the bridgeless
+ * CallInvoker. `CallInvoker::invokeAsync(CallFunc&&)` schedules the callback
+ * onto the SAME RuntimeScheduler that registerSegment would have used, and the
+ * callback receives `jsi::Runtime&`. We read the segment file, call
+ * `runtime.evaluateJavaScript(...)`, and invoke the completion callback from
+ * INSIDE that same block, strictly AFTER eval. Eval + completion are one atomic
+ * unit of work on the JS thread, so any subsequent `__r(moduleId)` is
+ * guaranteed to find the module.
+ *
+ * SEGMENT FORMAT: OneKey segments are standalone-evaluatable Metro bundles
+ * (top-level `__d(moduleId, factory, deps)` calls; the `.seg.hbc` is just the
+ * Hermes-compiled form of the same `.seg.js`). C++ ReactInstance::registerSegment
+ * itself just calls `runtime.evaluateJavaScript(buffer, ...)` with no RAM/indexed
+ * segment manifest wiring, confirming these are evaluatable as plain scripts.
+ */
+
+#include <fbjni/fbjni.h>
+#include <jsi/jsi.h>
+
+#include <ReactCommon/CallInvoker.h>
+#include <ReactCommon/CallInvokerHolder.h>
+
+#include <android/log.h>
+
+#include <cstdio>
+#include <memory>
+#include <string>
+#include <vector>
+
+#define SBL_LOG_TAG "SplitBundleLoader"
+#define SBL_LOGI(...) \
+  __android_log_print(ANDROID_LOG_INFO, SBL_LOG_TAG, __VA_ARGS__)
+#define SBL_LOGW(...) \
+  __android_log_print(ANDROID_LOG_WARN, SBL_LOG_TAG, __VA_ARGS__)
+
+namespace facebook::react::splitbundleloader {
+
+namespace {
+
+// Reads the whole file at `path` into a std::string. Returns false on failure.
+bool readFileToString(const std::string& path, std::string& out) {
+  FILE* f = std::fopen(path.c_str(), "rb");
+  if (f == nullptr) {
+    return false;
+  }
+  if (std::fseek(f, 0, SEEK_END) != 0) {
+    std::fclose(f);
+    return false;
+  }
+  long size = std::ftell(f);
+  if (size < 0) {
+    std::fclose(f);
+    return false;
+  }
+  if (std::fseek(f, 0, SEEK_SET) != 0) {
+    std::fclose(f);
+    return false;
+  }
+  out.resize(static_cast<size_t>(size));
+  size_t read = (size == 0)
+      ? 0
+      : std::fread(&out[0], 1, static_cast<size_t>(size), f);
+  std::fclose(f);
+  return read == static_cast<size_t>(size);
+}
+
+} // namespace
+
+// Java callback contract — implemented in Kotlin as
+// SplitBundleLoaderModule.SegmentEvalCallback. `onComplete(null)` on success,
+// `onComplete(errorMessage)` on failure. Invoked exactly once.
+//
+// Error-message prefix convention (read by the Kotlin side to pick the contract
+// reject code): a message prefixed with "IO_ERROR:" is a segment file read/mmap
+// failure → SPLIT_BUNDLE_IO_ERROR (non-retryable). Any other message is a
+// segment JS/Hermes eval throw → SPLIT_BUNDLE_EVAL_ERROR (non-retryable).
+struct JSegmentEvalCallback
+    : jni::JavaClass<JSegmentEvalCallback> {
+  static constexpr auto kJavaDescriptor =
+      "Lcom/splitbundleloader/SplitBundleLoaderModule$SegmentEvalCallback;";
+
+  // `error` empty → success (passes Java null); non-empty → failure (passes the
+  // message). We always pass null on success and a non-empty message on failure,
+  // so this mapping is unambiguous. `const` so it can be invoked through a
+  // (const) global_ref / alias_ref.
+  void onComplete(const std::string& error) const {
+    static const auto method =
+        javaClassStatic()->getMethod<void(jni::alias_ref<jni::JString>)>(
+            "onComplete");
+    jni::local_ref<jni::JString> arg =
+        error.empty() ? jni::local_ref<jni::JString>(nullptr)
+                      : jni::make_jstring(error);
+    method(self(), arg);
+  }
+};
+
+class SplitBundleLoaderJSI
+    : public jni::JavaClass<SplitBundleLoaderJSI> {
+ public:
+  static constexpr auto kJavaDescriptor =
+      "Lcom/splitbundleloader/SplitBundleLoaderModule;";
+
+  // Schedules evaluation of the segment at `segmentPath` onto the JS thread via
+  // the bridgeless CallInvoker, then invokes `callback` from INSIDE the same JS
+  // thread block, strictly AFTER the segment has been evaluated. This is the
+  // ordering guarantee that fixes the "Requiring unknown module" race.
+  //
+  // Does NOT block the calling (native modules) thread — returns immediately
+  // after scheduling. Resolution happens later on the JS thread.
+  static void nativeEvaluateSegment(
+      jni::alias_ref<jclass> /* unused */,
+      jni::alias_ref<CallInvokerHolder::javaobject> callInvokerHolder,
+      jni::alias_ref<jstring> segmentPath,
+      jni::alias_ref<jstring> sourceURL,
+      jni::alias_ref<JSegmentEvalCallback> callback) {
+    // Capture everything we need as values / global refs because the callback
+    // runs later on a different thread.
+    auto globalCallback = jni::make_global(callback);
+
+    if (!callInvokerHolder) {
+      globalCallback->onComplete("CallInvokerHolder is null");
+      return;
+    }
+
+    std::shared_ptr<CallInvoker> callInvoker =
+        callInvokerHolder->cthis()->getCallInvoker();
+    if (!callInvoker) {
+      globalCallback->onComplete("CallInvoker is null");
+      return;
+    }
+
+    std::string path = segmentPath ? segmentPath->toStdString() : std::string();
+    std::string url =
+        sourceURL ? sourceURL->toStdString() : std::string("segment");
+
+    if (path.empty()) {
+      globalCallback->onComplete("Empty segment path");
+      return;
+    }
+
+    // F: Read the segment file HERE, on the calling (native module) thread,
+    // BEFORE invokeAsync. Doing the disk read inside the JS-thread callback
+    // would block the JS thread on I/O and race the Kotlin watchdog. We move
+    // the already-read buffer into the lambda so only evaluateJavaScript +
+    // completion run on the JS thread (mirrors iOS, which mmaps off-thread and
+    // only evaluates on the runtime thread). The read error is surfaced as a
+    // dedicated IO error so JS can classify it as NON-retryable.
+    std::string source;
+    bool ioOk = readFileToString(path, source);
+    if (!ioOk) {
+      globalCallback->onComplete("IO_ERROR:Failed to read segment file: " + path);
+      return;
+    }
+    if (source.empty()) {
+      globalCallback->onComplete("IO_ERROR:Empty segment file: " + path);
+      return;
+    }
+
+    // CallFunc = std::function<void(jsi::Runtime&)>; this runs on the JS thread
+    // on the SAME RuntimeScheduler the segment registration would have used.
+    callInvoker->invokeAsync([globalCallback,
+                              source = std::move(source),
+                              url = std::move(url)](jsi::Runtime& runtime) {
+      std::string error;
+      try {
+        {
+          SBL_LOGI(
+              "[SplitBundle] evaluating segment %s (%zu bytes)",
+              url.c_str(),
+              source.size());
+          auto buffer = std::make_shared<jsi::StringBuffer>(std::move(source));
+          // Evaluate the segment into the CURRENT runtime. evaluateJavaScript
+          // runs the segment's top-level __d(...) module definitions
+          // synchronously on this JS thread before returning.
+          runtime.evaluateJavaScript(std::move(buffer), url);
+          SBL_LOGI("[SplitBundle] segment %s evaluated", url.c_str());
+        }
+      } catch (const jsi::JSError& e) {
+        error = std::string("Segment evaluation JSError for ") + url + ": " +
+            e.getMessage();
+        SBL_LOGW("[SplitBundle] %s", error.c_str());
+      } catch (const std::exception& e) {
+        error = std::string("Segment evaluation failed for ") + url + ": " +
+            e.what();
+        SBL_LOGW("[SplitBundle] %s", error.c_str());
+      } catch (...) {
+        error = std::string("Segment evaluation failed for ") + url +
+            " (unknown C++ exception)";
+        SBL_LOGW("[SplitBundle] %s", error.c_str());
+      }
+
+      // Attach to the JVM for this (JS) thread before calling back into Java.
+      // The JS thread is a native (pthread) thread not implicitly attached to
+      // the JVM; ThreadScope ensures a valid JNIEnv for the callback.
+      jni::ThreadScope ts;
+      // Resolve/reject from INSIDE this same JS-thread block, strictly AFTER
+      // eval above — the ordering guarantee that fixes the race.
+      globalCallback->onComplete(error);
+    });
+  }
+
+  static void registerNatives() {
+    // Static JNI methods on a plain JavaClass (NOT a HybridClass): bind via
+    // the class's registerNatives, not registerHybrid.
+    javaClassStatic()->registerNatives({
+        makeNativeMethod(
+            "nativeEvaluateSegment",
+            SplitBundleLoaderJSI::nativeEvaluateSegment),
+    });
+  }
+};
+
+} // namespace facebook::react::splitbundleloader
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* /* reserved */) {
+  return facebook::jni::initialize(vm, [] {
+    facebook::react::splitbundleloader::SplitBundleLoaderJSI::registerNatives();
+  });
+}

package/android/src/main/java/com/splitbundleloader/SplitBundleLoaderModule.kt

@@ -5,13 +5,18 @@ import android.content.res.AssetManager
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.common.annotations.FrameworkAPI
 import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.turbomodule.core.CallInvokerHolderImpl
 import java.io.File
 import java.io.FileInputStream
 import java.io.FileOutputStream
 import java.io.IOException
 import java.security.MessageDigest
 import java.util.concurrent.Semaphore
+import java.util.concurrent.atomic.AtomicBoolean
+import android.os.Handler
+import android.os.Looper
 
 /**
  * TurboModule entry point for SplitBundleLoader.
@@ -26,9 +31,65 @@ import java.util.concurrent.Semaphore
 class SplitBundleLoaderModule(reactContext: ReactApplicationContext) :
     NativeSplitBundleLoaderSpec(reactContext) {
 
+    /**
+     * Completion contract invoked by the native (JNI) side AFTER the segment
+     * has been evaluated into the runtime. Called from the JS thread.
+     *
+     * @param error null on success; a non-empty message on failure. A failure
+     *   message prefixed with "IO_ERROR:" denotes a segment file read/mmap
+     *   failure (mapped to SPLIT_BUNDLE_IO_ERROR); any other message denotes a
+     *   segment JS/Hermes eval throw (mapped to SPLIT_BUNDLE_EVAL_ERROR).
+     */
+    fun interface SegmentEvalCallback {
+        fun onComplete(error: String?)
+    }
+
     companion object {
         const val NAME = "SplitBundleLoader"
         private const val BUILTIN_EXTRACT_DIR = "onekey-builtin-segments"
+
+        // Bounded watchdog: if the JS thread is wedged and the segment eval
+        // never runs, reject rather than leaving the JS promise pending forever.
+        // Generous because a cold JS thread under load can legitimately take a
+        // while to drain to our scheduled eval.
+        private const val SEGMENT_EVAL_TIMEOUT_MS = 30_000L
+
+        // Loads the JNI library that provides nativeEvaluateSegment. Wrapped so
+        // a missing/failed load is detectable: loadSegment then fail-closes with
+        // SPLIT_BUNDLE_NATIVE_UNAVAILABLE instead of crashing (we deliberately do
+        // NOT fall back to the legacy registerSegment path).
+        @JvmStatic
+        @Volatile
+        var nativeLibLoaded: Boolean = false
+            private set
+
+        init {
+            nativeLibLoaded = try {
+                System.loadLibrary("splitbundleloader")
+                true
+            } catch (e: Throwable) {
+                SBLLogger.warn("[SplitBundle] failed to load native lib 'splitbundleloader': ${e.message}")
+                false
+            }
+        }
+
+        /**
+         * JNI entry point. Schedules evaluation of the segment at [segmentPath]
+         * onto the JS thread via the bridgeless CallInvoker and invokes
+         * [callback] from inside that same JS-thread block, strictly AFTER the
+         * segment's `__d(...)` module definitions have run. This is the ordering
+         * guarantee that fixes the "Requiring unknown module" race.
+         *
+         * Returns immediately; [callback] fires later on the JS thread.
+         */
+        @JvmStatic
+        @OptIn(FrameworkAPI::class)
+        external fun nativeEvaluateSegment(
+            callInvokerHolder: CallInvokerHolderImpl,
+            segmentPath: String,
+            sourceURL: String,
+            callback: SegmentEvalCallback
+        )
         // #18: Limit concurrent asset extractions to avoid I/O contention
         private const val MAX_CONCURRENT_EXTRACTS = 2
         private val extractSemaphore = Semaphore(MAX_CONCURRENT_EXTRACTS)
@@ -197,6 +258,7 @@ class SplitBundleLoaderModule(reactContext: ReactApplicationContext) :
     // loadSegment
     // -----------------------------------------------------------------------
 
+    @OptIn(FrameworkAPI::class)
     override fun loadSegment(
         segmentId: Double,
         segmentKey: String,
@@ -229,15 +291,119 @@ class SplitBundleLoaderModule(reactContext: ReactApplicationContext) :
                 return
             }
 
-            // Use ReactContext.registerSegment which works in both bridge
-            // and bridgeless modes. In bridge mode it delegates to
-            // CatalystInstance; in bridgeless mode it delegates to ReactHost.
             val reactContext = reactApplicationContext
             val segStart = System.nanoTime()
-            reactContext.registerSegment(segId, absolutePath) {
-                val segMs = (System.nanoTime() - segStart) / 1_000_000.0
-                SBLLogger.info("[SplitBundle] segment $segmentKey (id=$segId) registered in ${String.format("%.1f", segMs)}ms")
-                promise.resolve(null)
+
+            // PRIMARY PATH (fixes the "Requiring unknown module" race):
+            // Evaluate the segment OURSELVES on the JS thread via the bridgeless
+            // CallInvoker and resolve ONLY after eval completes. We intentionally
+            // do NOT use ReactContext.registerSegment here: that resolves its
+            // callback immediately (on Task.IMMEDIATE_EXECUTOR) while the actual
+            // segment eval is merely ENQUEUED onto the RuntimeScheduler, so the
+            // promise resolves BEFORE the segment's __d(...) module definitions
+            // run — Metro's import().then(() => __r(moduleId)) can then hit a
+            // fatal "Requiring unknown module". nativeEvaluateSegment collapses
+            // eval + resolve into one JS-thread block (mirrors the iOS
+            // callFunctionOnBufferedRuntimeExecutor: fix).
+            val callInvokerHolder =
+                reactContext.jsCallInvokerHolder as? CallInvokerHolderImpl
+
+            if (nativeLibLoaded && callInvokerHolder != null) {
+                val sourceURL = File(absolutePath).name
+                // One-shot guard: native success/error AND the watchdog can each
+                // try to settle the promise; only the first wins.
+                val settled = AtomicBoolean(false)
+
+                // Bounded watchdog: if the JS thread never drains to our eval,
+                // reject instead of hanging the JS promise forever.
+                val watchdog = Handler(Looper.getMainLooper())
+                val timeoutRunnable = Runnable {
+                    if (settled.compareAndSet(false, true)) {
+                        SBLLogger.warn("[SplitBundle] segment $segmentKey (id=$segId) eval timed out after ${SEGMENT_EVAL_TIMEOUT_MS}ms")
+                        // D: Reject with the RETRYABLE timeout code from the shared
+                        // contract (NOT SPLIT_BUNDLE_EVAL_TIMEOUT). A wedged JS
+                        // thread is a transient condition; using the retryable
+                        // SPLIT_BUNDLE_TIMEOUT lets the JS loader re-attempt rather
+                        // than caching this segment as a permanent failure.
+                        promise.reject(
+                            "SPLIT_BUNDLE_TIMEOUT",
+                            "Segment eval timed out: $segmentKey (id=$segId)"
+                        )
+                    }
+                }
+                watchdog.postDelayed(timeoutRunnable, SEGMENT_EVAL_TIMEOUT_MS)
+
+                // Catch Throwable, NOT just Exception, around the native call.
+                // nativeEvaluateSegment is `external`: if the symbol is
+                // registered-but-broken (or the lib half-loaded) the JVM raises
+                // UnsatisfiedLinkError, which is a java.lang.Error — it would
+                // sail past the outer `catch (e: Exception)` and leave the JS
+                // promise unsettled forever (the watchdog would eventually fire,
+                // but only after a 30s hang). Settle exactly once here via the
+                // same AtomicBoolean one-shot guard and cancel the watchdog.
+                try {
+                    nativeEvaluateSegment(
+                        callInvokerHolder,
+                        absolutePath,
+                        sourceURL
+                    ) { error ->
+                        if (settled.compareAndSet(false, true)) {
+                            watchdog.removeCallbacks(timeoutRunnable)
+                            if (error == null) {
+                                val segMs = (System.nanoTime() - segStart) / 1_000_000.0
+                                SBLLogger.info("[SplitBundle] segment $segmentKey (id=$segId) evaluated in ${String.format("%.1f", segMs)}ms (eval-complete)")
+                                promise.resolve(null)
+                            } else {
+                                // The native side prefixes I/O failures (file
+                                // read/mmap) with "IO_ERROR:" so we can map them to
+                                // SPLIT_BUNDLE_IO_ERROR (non-retryable). Everything
+                                // else is a segment JS/Hermes eval throw →
+                                // SPLIT_BUNDLE_EVAL_ERROR (also non-retryable, a real
+                                // bug in the segment's own code).
+                                if (error.startsWith("IO_ERROR:")) {
+                                    val msg = error.removePrefix("IO_ERROR:")
+                                    SBLLogger.warn("[SplitBundle] segment $segmentKey (id=$segId) IO failed: $msg")
+                                    promise.reject("SPLIT_BUNDLE_IO_ERROR", msg)
+                                } else {
+                                    SBLLogger.warn("[SplitBundle] segment $segmentKey (id=$segId) eval failed: $error")
+                                    promise.reject("SPLIT_BUNDLE_EVAL_ERROR", error)
+                                }
+                            }
+                        }
+                    }
+                } catch (t: Throwable) {
+                    // UnsatisfiedLinkError / any native dispatch failure. The
+                    // callback never fired (the native side never got far enough
+                    // to invoke it), so settle the promise ourselves — exactly
+                    // once — as a fatal, non-retryable native fault.
+                    if (settled.compareAndSet(false, true)) {
+                        watchdog.removeCallbacks(timeoutRunnable)
+                        SBLLogger.error("[SplitBundle] FATAL: nativeEvaluateSegment threw for $segmentKey (id=$segId): ${t.message}")
+                        promise.reject(
+                            "SPLIT_BUNDLE_NATIVE_UNAVAILABLE",
+                            "Native segment eval threw: $segmentKey (id=$segId): ${t.message}"
+                        )
+                    }
+                }
+            } else {
+                // B: FAIL CLOSED. On this app (RN 0.81, NewArch / bridgeless),
+                // jsCallInvokerHolder is always a CallInvokerHolderImpl and the
+                // JNI lib ships in the AAR, so reaching here means a genuine
+                // native fault (loadLibrary failed or the holder cast failed) —
+                // NOT a benign legacy-bridge mode (this app never runs the old
+                // bridge). We deliberately do NOT fall back to the legacy
+                // ReactContext.registerSegment path: that resolves before eval
+                // and reintroduces the intermittent, uncatchable "Requiring
+                // unknown module" native crash. Failing closed (segment load
+                // unavailable → JS error boundary) is strictly better than an
+                // intermittent crash, so we reject with the dedicated
+                // NATIVE_UNAVAILABLE code (non-retryable; the JS loader will not
+                // hammer-retry a structurally broken native primitive).
+                SBLLogger.error("[SplitBundle] FATAL: native eval primitive unavailable (libLoaded=$nativeLibLoaded, holderCast=${callInvokerHolder != null}) for $segmentKey (id=$segId); failing closed instead of using the race-prone legacy registerSegment fallback")
+                promise.reject(
+                    "SPLIT_BUNDLE_NATIVE_UNAVAILABLE",
+                    "Native segment eval unavailable (libLoaded=$nativeLibLoaded, holderCast=${callInvokerHolder != null}): $segmentKey (id=$segId)"
+                )
             }
         } catch (e: Exception) {
             promise.reject("SPLIT_BUNDLE_LOAD_ERROR", e.message, e)

package/ios/SplitBundleLoader.mm

@@ -3,9 +3,415 @@
 #import <ReactCommon/RCTHost.h>
 #import <ReactCommon/RCTHost+Internal.h>
 #import <ReactCommon/RCTInstance.h>
+#import <UIKit/UIKit.h>
 #import <objc/runtime.h>
 #import <CommonCrypto/CommonDigest.h>
+#import <os/lock.h>
 #include <jsi/jsi.h>
+#include <cstdint>
+
+namespace {
+
+// Zero-copy jsi::Buffer over an NSData (M4/M5).
+//
+// WHY: the previous code did `std::string(data.bytes, data.length)` inside a
+// jsi::StringBuffer — a FULL second copy of the (potentially multi-MB) segment
+// bytes on top of whatever the NSData read already cost. For the hot segment
+// path that doubles peak memory and adds a memcpy on the JS thread.
+//
+// This buffer instead RETAINS the NSData and hands jsi the NSData's own bytes
+// directly. Combined with NSDataReadingMappedIfSafe at the read site, the
+// segment is mmap'd and Hermes parses straight from the mapped pages — no heap
+// copy at all on the happy path. The retained NSData also makes the buffer's
+// lifetime explicit and self-owned: the executor block runs ASYNCHRONOUSLY
+// (it's buffered until the entry bundle finishes), so the NSData MUST outlive
+// the originating scope. Holding it inside the Buffer (which jsi keeps alive
+// via the shared_ptr for the duration of evaluateJavaScript) guarantees that.
+class NSDataJSIBuffer : public facebook::jsi::Buffer {
+ public:
+  explicit NSDataJSIBuffer(NSData *data) : data_(data) {}
+  size_t size() const override { return data_.length; }
+  const uint8_t *data() const override {
+    return static_cast<const uint8_t *>(data_.bytes);
+  }
+
+ private:
+  NSData *data_;  // strong retain (ARC) — keeps mmap/heap bytes alive for jsi.
+};
+
+}  // namespace
+
+// Exactly-once settle guard for the C1 watchdog. Wraps a BOOL behind an
+// os_unfair_lock. WHY AN OBJECT (not a __block BOOL + manual free): the executor
+// block and the watchdog dispatch_after BOTH capture it and BOTH may run
+// (dispatch_after is not cancellable, and on a wedge the executor can run AFTER
+// the watchdog). Tying the lock's lifetime to ARC — both blocks retain this
+// object, it deallocs only after both release — eliminates the use-after-free a
+// manual free() in either block would cause. `tryClaim` returns YES to exactly
+// one caller; the loser does nothing.
+@interface SBLSettleGuard : NSObject
+- (BOOL)tryClaim;
+@end
+
+@implementation SBLSettleGuard {
+  os_unfair_lock _lock;
+  BOOL _settled;
+}
+- (instancetype)init {
+  if (self = [super init]) {
+    _lock = OS_UNFAIR_LOCK_INIT;
+    _settled = NO;
+  }
+  return self;
+}
+- (BOOL)tryClaim {
+  os_unfair_lock_lock(&_lock);
+  BOOL won = !_settled;
+  if (won) {
+    _settled = YES;
+  }
+  os_unfair_lock_unlock(&_lock);
+  return won;
+}
+@end
+
+// ACTIVE-TIME watchdog for the buffered runtime executor (replaces the bare
+// dispatch_after C1 watchdog).
+//
+// WHY: the old watchdog was a single `dispatch_after(NOW + 30s)`. dispatch_after
+// arms against an ABSOLUTE wall/uptime deadline that keeps elapsing while the
+// app is backgrounded/suspended. If the app is suspended during cold start while
+// a segment's eval is still BUFFERED (waiting for the entry bundle to finish),
+// the 30s deadline can pass entirely off-screen; on FOREGROUND RESUME the stale
+// block fires essentially instantly and wins the SBLSettleGuard race against the
+// buffered executor that was ~1ms from succeeding — false-rejecting the segment
+// as SPLIT_BUNDLE_TIMEOUT and white-screening the app.
+//
+// This watchdog instead accumulates ONLY foreground/active wall-time: suspended
+// time never accrues toward the 30s, and a fresh foreground-grace window after
+// every resume guarantees the buffered executor gets a chance to flush first, so
+// a stale deadline can never fire instantly on resume.
+//
+// Time base: CLOCK_UPTIME_RAW already excludes device sleep; on top of that we
+// only count intervals during which the app is in the active state. All mutable
+// timing state is confined to a single serial queue (_queue) so the timer tick,
+// the start/cancel calls, and the foreground/background notification callbacks
+// never race. The fired/cancelled one-shot flag makes both onTimeout and teardown
+// happen at most once regardless of which thread triggers them.
+@interface SBLActiveWatchdog : NSObject
+- (instancetype)initWithTimeoutMs:(uint64_t)timeoutMs
+                 foregroundGraceMs:(uint64_t)foregroundGraceMs
+                         onTimeout:(dispatch_block_t)onTimeout;
+- (void)start;
+- (void)cancel;
+@end
+
+@implementation SBLActiveWatchdog {
+  // Serial queue that owns ALL mutable state below — every read/write of these
+  // ivars happens on _queue, so no additional lock is needed.
+  dispatch_queue_t _queue;
+  dispatch_source_t _timer;
+
+  uint64_t _timeoutMs;          // active-time budget before firing (e.g. 30000).
+  uint64_t _foregroundGraceMs;  // post-resume window during which we won't fire.
+
+  uint64_t _accumulatedActiveMs;   // folded active time from completed intervals.
+  uint64_t _currentIntervalStartUptimeNs;  // CLOCK_UPTIME_RAW at active start.
+  uint64_t _graceUntilUptimeNs;    // no fire before this uptime (grace window).
+  BOOL _isActive;                  // app currently in active/foreground state.
+  BOOL _finished;                  // one-shot: fired OR cancelled.
+
+  dispatch_block_t _onTimeout;
+  BOOL _observersRegistered;
+}
+
+- (instancetype)initWithTimeoutMs:(uint64_t)timeoutMs
+                 foregroundGraceMs:(uint64_t)foregroundGraceMs
+                         onTimeout:(dispatch_block_t)onTimeout {
+  if (self = [super init]) {
+    _queue = dispatch_queue_create("com.onekey.splitbundle.watchdog", DISPATCH_QUEUE_SERIAL);
+    _timeoutMs = timeoutMs;
+    _foregroundGraceMs = foregroundGraceMs;
+    _onTimeout = [onTimeout copy];
+    _accumulatedActiveMs = 0;
+    _currentIntervalStartUptimeNs = 0;
+    _graceUntilUptimeNs = 0;
+    _isActive = NO;
+    _finished = NO;
+    _observersRegistered = NO;
+  }
+  return self;
+}
+
+static uint64_t SBLNowUptimeNs(void) {
+  return clock_gettime_nsec_np(CLOCK_UPTIME_RAW);
+}
+
+// Current active-interval elapsed (ms) while _isActive; 0 otherwise. _queue only.
+- (uint64_t)currentIntervalMsLocked {
+  if (!_isActive || _currentIntervalStartUptimeNs == 0) {
+    return 0;
+  }
+  uint64_t now = SBLNowUptimeNs();
+  if (now <= _currentIntervalStartUptimeNs) {
+    return 0;
+  }
+  return (now - _currentIntervalStartUptimeNs) / 1000000ULL;
+}
+
+- (void)start {
+  // Seed initial app-state + register observers on the MAIN thread:
+  // -applicationState and the notification center are both main-thread concerns.
+  // We then hop to _queue with the captured `activeNow` to prime timing + timer,
+  // so the timing-state ivars are only ever touched on _queue.
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [self registerObservers];
+    // Treat anything other than Background as "active" for timing purposes
+    // (Inactive still makes progress toward the wedge).
+    UIApplicationState appState = UIApplication.sharedApplication.applicationState;
+    BOOL activeNow = (appState != UIApplicationStateBackground);
+    dispatch_async(self->_queue, ^{
+      [self primeTimerLockedWithActive:activeNow];
+    });
+  });
+}
+
+// Initialize timing state and create+resume the polling timer. _queue only.
+- (void)primeTimerLockedWithActive:(BOOL)activeNow {
+  if (_finished) {
+    return;  // cancelled before we got to prime — nothing to do.
+  }
+  _isActive = activeNow;
+  // Apply an initial grace window so a slow first foreground frame doesn't
+  // immediately trip the watchdog the very first tick. Read the clock ONCE so
+  // the interval start and the grace deadline share the same base instant.
+  if (activeNow) {
+    uint64_t now = SBLNowUptimeNs();
+    _currentIntervalStartUptimeNs = now;
+    _graceUntilUptimeNs = now + _foregroundGraceMs * 1000000ULL;
+  } else {
+    _currentIntervalStartUptimeNs = 0;
+  }
+
+  // Polling timer: survives pause/resume trivially (unlike a one-shot
+  // dispatch_after). Tick every 500ms. Leeway gives the scheduler slack.
+  _timer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0, _queue);
+  if (!_timer) {
+    // Fail safe: if the timer source can't be created we cannot guard against a
+    // wedge. Settle now (as a RETRYABLE timeout) via fireLocked rather than
+    // leaving the watchdog half-started (observers registered, _finished=NO,
+    // tick never firing) — that stuck state would hang loadSegment: forever.
+    // The JS loader re-attempts on SPLIT_BUNDLE_TIMEOUT, and the buffered
+    // executor, if it does run, still benefits the module table.
+    [self fireLocked];
+    return;
+  }
+  dispatch_source_set_timer(_timer,
+                            dispatch_time(DISPATCH_TIME_NOW, (int64_t)(500 * NSEC_PER_MSEC)),
+                            (uint64_t)(500 * NSEC_PER_MSEC),
+                            (uint64_t)(100 * NSEC_PER_MSEC));
+  __weak SBLActiveWatchdog *weakSelf = self;
+  dispatch_source_set_event_handler(_timer, ^{
+    SBLActiveWatchdog *strongSelf = weakSelf;
+    if (strongSelf) {
+      [strongSelf tickLocked];
+    }
+  });
+  dispatch_resume(_timer);
+}
+
+// Timer tick — runs on _queue (the timer's own queue), so state is consistent.
+- (void)tickLocked {
+  if (_finished) {
+    return;
+  }
+  if (!_isActive) {
+    return;  // only foreground/active time counts toward the timeout.
+  }
+  uint64_t now = SBLNowUptimeNs();
+  if (now < _graceUntilUptimeNs) {
+    return;  // inside the post-resume grace window — give the executor a chance.
+  }
+  uint64_t totalActiveMs = _accumulatedActiveMs + [self currentIntervalMsLocked];
+  if (totalActiveMs >= _timeoutMs) {
+    [self fireLocked];
+  }
+}
+
+// Fire onTimeout at most once, then tear everything down. _queue only.
+- (void)fireLocked {
+  if (_finished) {
+    return;
+  }
+  _finished = YES;
+  dispatch_block_t cb = _onTimeout;
+  _onTimeout = nil;
+  [self teardownTimerLocked];
+  // Remove observers on the main thread (where they were registered).
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [self removeObservers];
+  });
+  if (cb) {
+    cb();
+  }
+}
+
+// Cancel the timer source exactly once. _queue only.
+- (void)teardownTimerLocked {
+  if (_timer) {
+    dispatch_source_cancel(_timer);
+    _timer = nil;  // drop our ref; the source is retained until cancel completes.
+  }
+}
+
+// Public cancel — thread-safe, may be called from the executor block's success
+// path on a DIFFERENT thread. Hops onto _queue so it serializes with the tick.
+- (void)cancel {
+  dispatch_async(_queue, ^{
+    if (self->_finished) {
+      return;
+    }
+    self->_finished = YES;
+    self->_onTimeout = nil;
+    [self teardownTimerLocked];
+    dispatch_async(dispatch_get_main_queue(), ^{
+      [self removeObservers];
+    });
+  });
+}
+
+// MARK: - App-state observers (main thread)
+
+- (void)registerObservers {
+  if (_observersRegistered) {
+    return;
+  }
+  _observersRegistered = YES;
+  NSNotificationCenter *nc = [NSNotificationCenter defaultCenter];
+  [nc addObserver:self
+         selector:@selector(handleDidBecomeActive)
+             name:UIApplicationDidBecomeActiveNotification
+           object:nil];
+  [nc addObserver:self
+         selector:@selector(handleWillResignActive)
+             name:UIApplicationWillResignActiveNotification
+           object:nil];
+  // DidEnterBackground is folded in too: on some transitions WillResignActive
+  // and DidEnterBackground both arrive; the resign handler is idempotent (it
+  // no-ops when already inactive), so treating background like resign is safe.
+  [nc addObserver:self
+         selector:@selector(handleWillResignActive)
+             name:UIApplicationDidEnterBackgroundNotification
+           object:nil];
+}
+
+- (void)removeObservers {
+  if (!_observersRegistered) {
+    return;
+  }
+  _observersRegistered = NO;
+  [[NSNotificationCenter defaultCenter] removeObserver:self];
+}
+
+- (void)handleWillResignActive {
+  // Sample the resign instant on the main thread BEFORE the app can suspend.
+  uint64_t resignAtUptimeNs = SBLNowUptimeNs();
+  // Fold + pause SYNCHRONOUSLY (dispatch_sync, not async). The pause must take
+  // effect before this lifecycle callback returns — i.e. before the app is
+  // suspended. Why sync is required, not just a synchronous timestamp:
+  //   - the polling timer fires on _queue; a tick may already be PENDING on
+  //     _queue when we resign. tickLocked recomputes `now` at EXECUTION time, so
+  //     if that pending tick doesn't run until the app RESUMES (minutes later),
+  //     it would see _isActive==YES + the old interval start and fold all the
+  //     suspended-but-awake time (CLOCK_UPTIME_RAW keeps advancing) → fire a
+  //     false SPLIT_BUNDLE_TIMEOUT before the resume grace is even armed.
+  //   - dispatch_sync drains the serial queue first: any pending tick runs NOW
+  //     (at resign time, pre-suspension, with a valid small interval — no false
+  //     fire), then this fold runs and sets _isActive=NO. So by the time the app
+  //     suspends, the clock is stopped and no stale tick can fire on resume.
+  // Safe from deadlock: _queue blocks never dispatch_sync back to the main
+  // thread (observer removal uses dispatch_async), and the queue's blocks are
+  // all O(1).
+  dispatch_sync(_queue, ^{
+    if (self->_finished || !self->_isActive) {
+      return;  // idempotent: already inactive or already settled.
+    }
+    // Fold ONLY the active interval up to resignAt into the accumulator, then
+    // stop the clock. Suspended time after this point does NOT accrue.
+    if (self->_currentIntervalStartUptimeNs != 0 &&
+        resignAtUptimeNs > self->_currentIntervalStartUptimeNs) {
+      self->_accumulatedActiveMs +=
+          (resignAtUptimeNs - self->_currentIntervalStartUptimeNs) / 1000000ULL;
+    }
+    self->_isActive = NO;
+    self->_currentIntervalStartUptimeNs = 0;
+  });
+}
+
+- (void)handleDidBecomeActive {
+  dispatch_async(_queue, ^{
+    if (self->_finished || self->_isActive) {
+      return;
+    }
+    // Resume the clock and arm a fresh grace window so the buffered executor
+    // gets a chance to flush before the watchdog can fire again. One clock read
+    // so the interval start and the grace deadline share the same base instant.
+    uint64_t now = SBLNowUptimeNs();
+    self->_isActive = YES;
+    self->_currentIntervalStartUptimeNs = now;
+    self->_graceUntilUptimeNs = now + self->_foregroundGraceMs * 1000000ULL;
+  });
+}
+
+- (void)dealloc {
+  // Defensive: observers are normally removed via cancel/fire, but if this
+  // object is released without either (shouldn't happen — the executor block
+  // retains it until cancel), make sure we don't leave a dangling observer.
+  if (_observersRegistered) {
+    [[NSNotificationCenter defaultCenter] removeObserver:self];
+  }
+  // Make the "timer is nil by dealloc" invariant explicit: cancel/fireLocked
+  // both null _timer before the last retain drops, but guard here so a future
+  // early-return on those paths can't orphan a running dispatch_source_t. Safe
+  // to touch _timer without hopping to _queue — no other thread references a
+  // deallocating object.
+  if (_timer) {
+    dispatch_source_cancel(_timer);
+    _timer = nil;
+  }
+}
+@end
+
+// Watchdog window for the buffered runtime executor (C1). Post-entry eval is
+// sub-millisecond, so this only ever elapses on a genuine wedge (entry bundle
+// never finished evaluating) — never on a healthy slow device.
+//
+// Fix G: 30s (matching Android and the bg-runtime watchdog). The executor stays
+// buffered until the main ENTRY bundle finishes evaluating; on a slow/throttled
+// cold start that entry eval can itself exceed 10s, which would falsely trip the
+// watchdog on a segment load that was about to succeed. 30s keeps the
+// genuine-wedge safety net while leaving headroom for slow cold starts.
+static const NSTimeInterval kSegmentEvalWatchdogSeconds = 30.0;
+
+// NSError `code` values produced by +evaluateSegmentAtPath:... . These are
+// DISTINCT (L8) so loadSegment: can map each to its own JS reject code and JS
+// can classify retryable-vs-fatal:
+//   - HostMissing / NilInstance → SPLIT_BUNDLE_NO_RUNTIME (retryable):
+//       the runtime/host simply wasn't ready yet; a later attempt may succeed.
+//   - IvarMissing → SPLIT_BUNDLE_NATIVE_UNAVAILABLE (NOT retryable): a renamed
+//       ivar is a structural/build defect that no retry can fix.
+//   - Timeout → SPLIT_BUNDLE_TIMEOUT (retryable): buffered executor never ran.
+//   - IORead → SPLIT_BUNDLE_IO_ERROR: file read/mmap failed.
+//   - EvalThrow → SPLIT_BUNDLE_EVAL_ERROR (NOT retryable): a real bug in the
+//       segment's own JS/Hermes code; retrying just re-throws.
+typedef NS_ENUM(NSInteger, ESegmentEvalError) {
+    ESegmentEvalErrorHostMissing = 1,
+    ESegmentEvalErrorIvarMissing = 2,
+    ESegmentEvalErrorNilInstance = 3,
+    ESegmentEvalErrorIORead = 4,
+    ESegmentEvalErrorEvalThrow = 5,
+    ESegmentEvalErrorTimeout = 6,
+};
 
 @implementation SplitBundleLoader
 
@@ -127,30 +533,217 @@
     return result;
 }
 
-// MARK: - Segment registration helper
+// MARK: - RCTHost resolution helper
 
-/// Registers a segment with the current runtime via bridgeless (RCTHost) architecture (#13).
-///
-/// Thread safety (#57): This method is called from the TurboModule (JS thread).
-/// No queue dispatch is needed.
-+ (BOOL)registerSegment:(int)segmentId path:(NSString *)path error:(NSError **)outError
+/// Resolves the bridgeless RCTHost via the AppDelegate's `reactHost` accessor
+/// (New Architecture). Returns nil when the host is unavailable so callers can
+/// reject gracefully. Extracted so both segment registration and the
+/// evaluate-then-resolve path (#race) share one lookup.
++ (nullable RCTHost *)currentReactHost
 {
-    // Bridgeless (New Architecture): get RCTHost via AppDelegate
     id<UIApplicationDelegate> appDelegate = [UIApplication sharedApplication].delegate;
     if ([appDelegate respondsToSelector:NSSelectorFromString(@"reactHost")]) {
         RCTHost *host = [appDelegate performSelector:NSSelectorFromString(@"reactHost")];
-        if (host && [host respondsToSelector:@selector(registerSegmentWithId:path:)]) {
-            [host registerSegmentWithId:@(segmentId) path:path];
-            return YES;
+        if (host) {
+            return host;
         }
     }
+    return nil;
+}
+
+// MARK: - Segment evaluation helper (resolve-after-eval, fixes lazy-segment race)
+
+/// Evaluates a segment bundle into the CURRENT runtime and invokes `onEvaluated`
+/// from INSIDE the same runtime-executor block, immediately after the segment's
+/// `__d(...)` module definitions have run.
+///
+/// WHY THIS EXISTS — the "Requiring unknown module" race (#race):
+/// The previous implementation called `RCTHost registerSegmentWithId:path:`,
+/// which routes to `ReactInstance::registerSegment` →
+/// `runtimeScheduler_->scheduleWork([]{ runtime.evaluateJavaScript(segment) })`.
+/// That only ENQUEUES the eval onto the runtime scheduler and returns; the
+/// loadSegment promise was resolved IMMEDIATELY afterwards. Metro's
+/// `import().then(() => __r(moduleId))` microtask could therefore run `__r`
+/// BEFORE the scheduled eval populated the module table → a FATAL, uncatchable
+/// "Requiring unknown module" inside metroRequire.
+///
+/// We cannot fix this by merely scheduling `resolve` after `registerSegment` on
+/// the same executor: `RuntimeScheduler_Modern::scheduleWork` pushes
+/// ImmediatePriority tasks into a `std::priority_queue` keyed only on
+/// `expirationTime` (RuntimeScheduler_Modern.cpp / Task.h `TaskPriorityComparer`).
+/// `std::priority_queue` is NOT stable, so two same-tick tasks have UNDEFINED
+/// relative order — FIFO is not guaranteed under the Modern scheduler.
+///
+/// Instead we evaluate the segment OURSELVES inside a single
+/// `callFunctionOnBufferedRuntimeExecutor:` block (exactly like
+/// `loadEntryBundle:`) and signal completion in that SAME block. Eval and the
+/// resolve are now one atomic unit of work — there is no cross-task ordering to
+/// lose, so any subsequent `__r(moduleId)` is guaranteed to find the module.
+///
+/// This is safe because OneKey segments are STANDALONE-EVALUATABLE Metro
+/// bundles (the serializer emits `baseJSBundle`/`bundleToString` output — plain
+/// top-level `__d(moduleId, factory, deps)` calls, NOT Hermes RAM/indexed
+/// segments that would require the registerSegment manifest wiring). The paired
+/// `.seg.hbc` is just the Hermes-compiled form of that same source, which
+/// `evaluateJavaScript` runs identically to the entry bundle's `.hbc`.
+///
+/// `onEvaluated` is invoked EXACTLY ONCE with nil on success or a populated
+/// NSError on failure. The NSError `code` is meaningful and mapped by the caller
+/// to a distinct JS reject code (see ESegmentEvalError below + loadSegment:):
+/// callers use it to classify retryable (no-runtime / timeout) vs fatal
+/// (eval-throw / IO) failures.
++ (void)evaluateSegmentAtPath:(NSString *)bundlePath
+                    segmentId:(int)segmentId
+                   segmentKey:(NSString *)segmentKey
+                  onEvaluated:(void (^)(NSError *_Nullable error))onEvaluated
+{
+    RCTHost *host = [SplitBundleLoader currentReactHost];
+    if (!host) {
+        onEvaluated([NSError errorWithDomain:@"SplitBundleLoader"
+                                        code:ESegmentEvalErrorHostMissing
+                                    userInfo:@{NSLocalizedDescriptionKey: @"RCTHost not available for segment evaluation"}]);
+        return;
+    }
 
-    if (outError) {
-        *outError = [NSError errorWithDomain:@"SplitBundleLoader"
-                                        code:1
-                                    userInfo:@{NSLocalizedDescriptionKey: @"RCTHost not available for segment registration"}];
+    // Reach the RCTInstance the same way loadEntryBundle: does, so we can use
+    // the buffered runtime executor primitive (callFunctionOnBufferedRuntimeExecutor:).
+    Ivar ivar = class_getInstanceVariable([host class], "_instance");
+    if (!ivar) {
+        // L7: a missing `_instance` ivar means a future RN bump renamed/removed
+        // the field our reflection depends on. That silently disables ALL
+        // segment loading, so log loudly (error, with the class name) instead of
+        // failing quietly — the next RN upgrade then surfaces visibly in logs.
+        [SBLLogger error:[NSString stringWithFormat:@"[SplitBundle] FATAL: _instance ivar not found on %@ — segment loading is DISABLED. An RN upgrade likely renamed this private field; SplitBundleLoader reflection must be updated.", [host class]]];
+        onEvaluated([NSError errorWithDomain:@"SplitBundleLoader"
+                                        code:ESegmentEvalErrorIvarMissing
+                                    userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"_instance ivar not found on %@", [host class]]}]);
+        return;
     }
-    return NO;
+
+    RCTInstance *instance = object_getIvar(host, ivar);
+    if (!instance) {
+        onEvaluated([NSError errorWithDomain:@"SplitBundleLoader"
+                                        code:ESegmentEvalErrorNilInstance
+                                    userInfo:@{NSLocalizedDescriptionKey: @"RCTInstance is nil"}]);
+        return;
+    }
+
+    // M4/M5: mmap the segment (NSDataReadingMappedIfSafe) instead of a full
+    // heap read, then wrap it zero-copy in NSDataJSIBuffer (which retains the
+    // NSData). Net effect: no second copy, and the bytes stay alive for the
+    // async executor block because the buffer owns the NSData.
+    NSError *readError = nil;
+    NSData *data = [NSData dataWithContentsOfFile:bundlePath
+                                         options:NSDataReadingMappedIfSafe
+                                           error:&readError];
+    if (!data || data.length == 0) {
+        onEvaluated([NSError errorWithDomain:@"SplitBundleLoader"
+                                        code:ESegmentEvalErrorIORead
+                                    userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"Failed to read segment at %@%@", bundlePath, readError ? [NSString stringWithFormat:@": %@", readError.localizedDescription] : @""]}]);
+        return;
+    }
+
+    // M6: preserve a meaningful eval source URL so in-segment crash frames are
+    // symbolicated. RN's registerSegment used
+    // `JSExecutor::getSyntheticBundlePath(segmentId, segmentPath)`, which for a
+    // non-main segment yields `seg-<id>.js` (see cxxreact/JSExecutor.cpp). We
+    // replicate that exact form so Hermes/Metro attribute frames to the segment
+    // the same way the native path did — using `lastPathComponent` here would
+    // degrade symbolication.
+    NSString *sourceURL = [NSString stringWithFormat:@"seg-%d.js", segmentId];
+    CFAbsoluteTime dispatchStart = CFAbsoluteTimeGetCurrent();
+    [SBLLogger info:[NSString stringWithFormat:@"[SplitBundle] loadSegment: evaluating %@ (key=%@, %lu bytes)", sourceURL, segmentKey, (unsigned long)data.length]];
+
+    // C1: the executor block below is BUFFERED — callFunctionOnBufferedRuntimeExecutor
+    // does not run it until the main entry bundle finishes evaluating
+    // (RCTInstance/ReactInstance.cpp). If a segment load is requested before the
+    // entry completes (early startup, reload teardown, host swap) and the entry
+    // never completes, the block NEVER runs → onEvaluated would never fire →
+    // the JS promise hangs forever and inflightSegments wedges with no timeout.
+    //
+    // Guard: invoke `onEvaluated` EXACTLY ONCE. SBLSettleGuard wraps a BOOL
+    // behind an os_unfair_lock; whichever racer wins — the executor block (happy
+    // path) or the watchdog timer (genuine wedge) — gets YES from tryClaim and
+    // settles the promise; the loser does nothing. The guard is an ARC object
+    // captured (retained) by BOTH blocks, so its lock outlives both with no
+    // manual free() and therefore no use-after-free (both blocks can run, in
+    // either order, on a wedge).
+    SBLSettleGuard *settleGuard = [[SBLSettleGuard alloc] init];
+
+    // C1 active-time watchdog. Constructed BEFORE the executor block so the block
+    // can capture (retain) it and tear it down on the happy path. It fires only
+    // on a genuine wedge AND only after kSegmentEvalWatchdogSeconds of
+    // FOREGROUND/active time has accrued — backgrounded/suspended time never
+    // counts, so a stale deadline can never fire instantly on a foreground
+    // resume (the white-screen bug this replaces). On fire it settles the SAME
+    // SBLSettleGuard via tryClaim, so there is still exactly one settle.
+    SBLActiveWatchdog *watchdog = [[SBLActiveWatchdog alloc]
+        initWithTimeoutMs:(uint64_t)(kSegmentEvalWatchdogSeconds * 1000.0)
+        foregroundGraceMs:500
+                onTimeout:^{
+        if ([settleGuard tryClaim]) {
+            [SBLLogger error:[NSString stringWithFormat:@"[SplitBundle] loadSegment: %@ (key=%@) WATCHDOG fired after %.0fs active time — runtime executor never ran (entry bundle likely never finished evaluating). Rejecting as retryable timeout.", sourceURL, segmentKey, kSegmentEvalWatchdogSeconds]];
+            onEvaluated([NSError errorWithDomain:@"SplitBundleLoader"
+                                            code:ESegmentEvalErrorTimeout
+                                        userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"Segment %@ eval timed out after %.0fs active time (buffered runtime executor never ran)", segmentKey, kSegmentEvalWatchdogSeconds]}]);
+        }
+    }];
+
+    [instance callFunctionOnBufferedRuntimeExecutor:^(facebook::jsi::Runtime &runtime) {
+        @autoreleasepool {
+            // If the watchdog already fired (entry took >30s active then
+            // unwedged), the JS promise is already rejected — still evaluate the
+            // segment (the module table benefits) but don't double-settle.
+            BOOL won = [settleGuard tryClaim];
+            NSError *evalError = nil;
+            CFAbsoluteTime evalStart = CFAbsoluteTimeGetCurrent();
+            try {
+                auto buffer = std::make_shared<NSDataJSIBuffer>(data);
+                runtime.evaluateJavaScript(buffer, [sourceURL UTF8String]);
+                double evalMs = (CFAbsoluteTimeGetCurrent() - evalStart) * 1000.0;
+                [SBLLogger info:[NSString stringWithFormat:@"[SplitBundle] loadSegment: %@ evaluated in %.1fms", sourceURL, evalMs]];
+            } catch (const std::exception &e) {
+                // L8: a JS/Hermes eval throw is a REAL BUG in the segment's own
+                // code, not a transient runtime-readiness problem. Mapped to a
+                // NON-retryable code by the caller so JS caches it as failed.
+                evalError = [NSError errorWithDomain:@"SplitBundleLoader"
+                                                code:ESegmentEvalErrorEvalThrow
+                                            userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"Segment evaluation failed for %@: %s", sourceURL, e.what()]}];
+                [SBLLogger warn:[NSString stringWithFormat:@"[SplitBundle] loadSegment: %@ evaluation threw: %s", sourceURL, e.what()]];
+            } catch (...) {
+                evalError = [NSError errorWithDomain:@"SplitBundleLoader"
+                                                code:ESegmentEvalErrorEvalThrow
+                                            userInfo:@{NSLocalizedDescriptionKey: [NSString stringWithFormat:@"Segment evaluation failed for %@ (unknown C++ exception)", sourceURL]}];
+                [SBLLogger warn:[NSString stringWithFormat:@"[SplitBundle] loadSegment: %@ evaluation threw an unknown exception", sourceURL]];
+            }
+            // Tear down the active-time watchdog (timer + observers) regardless
+            // of who won the settle: the buffered executor has now run, so the
+            // watchdog has no further job. Capturing `watchdog` here is also what
+            // RETAINS it for the lifetime of this async block (until cancel). It
+            // is safe to cancel from this (different) thread — cancel hops onto
+            // the watchdog's own serial queue and is a one-shot.
+            [watchdog cancel];
+            if (won) {
+                // Resolve/reject the JS promise from INSIDE this same block,
+                // strictly AFTER the segment eval above — the ordering guarantee
+                // that fixes the "Requiring unknown module" race (see method doc).
+                onEvaluated(evalError);
+            } else {
+                [SBLLogger warn:[NSString stringWithFormat:@"[SplitBundle] loadSegment: %@ evaluated AFTER watchdog already settled (entry was wedged >%.0fs active time)", sourceURL, kSegmentEvalWatchdogSeconds]];
+            }
+        }
+    }];
+
+    // Arm the watchdog AFTER scheduling the executor. Fires only on a genuine
+    // wedge: in steady state the entry bundle is long done and the buffered block
+    // runs sub-millisecond, so it cancels the watchdog (and the guard is already
+    // claimed) long before kSegmentEvalWatchdogSeconds of ACTIVE time elapses.
+    // Because only foreground/active time is counted, a suspend-during-cold-start
+    // can no longer let a stale deadline false-fire on resume.
+    [watchdog start];
+
+    double dispatchMs = (CFAbsoluteTimeGetCurrent() - dispatchStart) * 1000.0;
+    [SBLLogger info:[NSString stringWithFormat:@"[SplitBundle] loadSegment: %@ dispatched in %.1fms (resolve fires after eval; watchdog %.0fs)", sourceURL, dispatchMs, kSegmentEvalWatchdogSeconds]];
 }
 
 // MARK: - getRuntimeBundleContext
@@ -280,7 +873,12 @@
     return;
   }
 
-  NSData *data = [NSData dataWithContentsOfFile:bundlePath];
+  // M5: mmap + zero-copy (NSDataJSIBuffer retains the NSData for the async block),
+  // mirroring the segment path. Entry bundle is the largest single read, so this
+  // saves the biggest single copy.
+  NSData *data = [NSData dataWithContentsOfFile:bundlePath
+                                       options:NSDataReadingMappedIfSafe
+                                         error:nil];
   if (!data || data.length == 0) {
     [SBLLogger warn:[NSString stringWithFormat:@"loadEntryBundle: failed to read bundle at %@", bundlePath]];
     return;
@@ -293,9 +891,8 @@
   [instance callFunctionOnBufferedRuntimeExecutor:^(facebook::jsi::Runtime &runtime) {
     @autoreleasepool {
       CFAbsoluteTime evalStart = CFAbsoluteTimeGetCurrent();
-      auto buffer = std::make_shared<facebook::jsi::StringBuffer>(
-        std::string(static_cast<const char *>(data.bytes), data.length));
-      runtime.evaluateJavaScript(std::move(buffer), [sourceURL UTF8String]);
+      auto buffer = std::make_shared<NSDataJSIBuffer>(data);
+      runtime.evaluateJavaScript(buffer, [sourceURL UTF8String]);
       double evalMs = (CFAbsoluteTimeGetCurrent() - evalStart) * 1000.0;
       [SBLLogger info:[NSString stringWithFormat:@"[SplitBundle] loadEntryBundle: %@ evaluated in %.1fms", sourceURL, evalMs]];
     }
@@ -342,17 +939,62 @@
             return;
         }
 
-        // Register segment (#13: supports both bridge and bridgeless)
-        NSError *regError = nil;
-        if ([SplitBundleLoader registerSegment:segId path:absolutePath error:&regError]) {
+        // Evaluate the segment into the current runtime and resolve ONLY after
+        // its module definitions have actually run (#race). We intentionally do
+        // NOT use registerSegmentWithId: + immediate resolve here: that resolves
+        // before the scheduler-enqueued eval completes, so Metro's
+        // `import().then(() => __r(moduleId))` can hit "Requiring unknown module"
+        // (a fatal, uncatchable crash). See +evaluateSegmentAtPath:... doc for
+        // the full ordering rationale (Modern scheduler priority_queue is not
+        // FIFO, so we collapse eval+resolve into one runtime-executor block).
+        // segId is threaded through for the synthetic eval source URL (M6) and
+        // for log parity with the previous register flow.
+        [SplitBundleLoader evaluateSegmentAtPath:absolutePath
+                                       segmentId:segId
+                                      segmentKey:segmentKey
+                                     onEvaluated:^(NSError *_Nullable evalError) {
+            if (evalError) {
+                // L8: map the helper's distinct NSError code to a distinct JS
+                // reject code so JS can classify retryable vs fatal (see
+                // ESegmentEvalError + installProdBundleLoader.ts H3).
+                NSString *rejectCode;
+                switch ((ESegmentEvalError)evalError.code) {
+                    case ESegmentEvalErrorTimeout:
+                        rejectCode = @"SPLIT_BUNDLE_TIMEOUT";        // retryable
+                        break;
+                    case ESegmentEvalErrorIORead:
+                        rejectCode = @"SPLIT_BUNDLE_IO_ERROR";       // fatal
+                        break;
+                    case ESegmentEvalErrorEvalThrow:
+                        rejectCode = @"SPLIT_BUNDLE_EVAL_ERROR";     // fatal (segment bug)
+                        break;
+                    case ESegmentEvalErrorIvarMissing:
+                        // Fix 2: `_instance` ivar reflection failed — STRUCTURAL/
+                        // PERMANENT. An RN version bump renamed/removed the
+                        // private field our reflection depends on, so segment
+                        // loading is disabled until the native code is updated.
+                        // Retrying can NEVER recreate a renamed ivar, so this is
+                        // fatal NATIVE_UNAVAILABLE — NOT retryable NO_RUNTIME. By
+                        // contrast HostMissing / NilInstance below are genuinely
+                        // transient (host/instance not up yet → a later attempt
+                        // may succeed).
+                        rejectCode = @"SPLIT_BUNDLE_NATIVE_UNAVAILABLE"; // fatal
+                        break;
+                    case ESegmentEvalErrorHostMissing:
+                    case ESegmentEvalErrorNilInstance:
+                    default:
+                        rejectCode = @"SPLIT_BUNDLE_NO_RUNTIME";     // retryable
+                        break;
+                }
+                reject(rejectCode,
+                       evalError.localizedDescription ?: @"Segment evaluation failed",
+                       evalError);
+                return;
+            }
             double segMs = (CFAbsoluteTimeGetCurrent() - segStart) * 1000.0;
-            [SBLLogger info:[NSString stringWithFormat:@"[SplitBundle] Loaded segment %@ (id=%d) in %.1fms", segmentKey, segId, segMs]];
+            [SBLLogger info:[NSString stringWithFormat:@"[SplitBundle] Loaded segment %@ (id=%d) in %.1fms (eval-complete)", segmentKey, segId, segMs]];
             resolve(nil);
-        } else {
-            reject(@"SPLIT_BUNDLE_NO_RUNTIME",
-                   regError.localizedDescription ?: @"Runtime not available",
-                   regError);
-        }
+        }];
     } @catch (NSException *exception) {
         reject(@"SPLIT_BUNDLE_LOAD_ERROR",
                [NSString stringWithFormat:@"Failed to load segment %@: %@", segmentKey, exception.reason],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-split-bundle-loader",
-  "version": "3.0.63",
+  "version": "3.0.65",
   "description": "react-native-split-bundle-loader",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",