@onekeyfe/react-native-background-thread 3.0.17 → 3.0.19

package/android/src/main/cpp/cpp-adapter.cpp

@@ -1,10 +1,17 @@
 #include <jni.h>
 #include <jsi/jsi.h>
 #include <android/log.h>
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <deque>
+#include <functional>
 #include <memory>
 #include <mutex>
 #include <string>
+#include <thread>
 #include <unordered_map>
+#include <unordered_set>
 
 #include "SharedStore.h"
 #include "SharedRPC.h"
@@ -86,6 +93,358 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeExecuteWork(
     } catch (const std::exception &e) {
         LOGE("Error in nativeExecuteWork: %s", e.what());
     }
+
+    // CRITICAL: Drain the Hermes microtask queue. React Native 0.74+ configures
+    // Hermes with an explicit microtask queue, which must be manually drained
+    // after each JS execution. Without this, Promise.then() / async-await
+    // continuations (including already-resolved promises) are never executed,
+    // causing all awaits to hang forever in the background runtime.
+    try {
+        rt->drainMicrotasks();
+    } catch (const jsi::JSError &e) {
+        LOGE("JSError draining microtasks: %s", e.getMessage().c_str());
+    } catch (const std::exception &e) {
+        LOGE("Error draining microtasks: %s", e.what());
+    }
+}
+
+// ── Timer support for background runtime ──────────────────────────────
+// The background Hermes runtime does NOT have working setTimeout/setInterval
+// out of the box (RN's timer module only wires into the main runtime). We
+// install our own JSI-level setTimeout/setInterval/clearTimeout/clearInterval
+// backed by a single C++ worker thread that dispatches callbacks back to the
+// background JS queue via the same executor used by SharedRPC.
+
+struct TimerEntry {
+    std::shared_ptr<jsi::Function> callback;
+    long long fireAtMs;      // Absolute time in ms when the timer should fire.
+    long long intervalMs;    // 0 if one-shot, >0 if setInterval period.
+    bool cancelled;
+};
+
+static std::mutex gTimerMutex;
+static std::condition_variable gTimerCv;
+static std::unordered_map<int64_t, TimerEntry> gTimers;
+static std::atomic<int64_t> gNextTimerId{1};
+static std::atomic<bool> gTimerWorkerStarted{false};
+static std::atomic<bool> gTimerWorkerStop{false};
+static RPCRuntimeExecutor gBgTimerExecutor;
+static std::thread gTimerWorkerThread;
+
+static long long nowMs() {
+    using namespace std::chrono;
+    return duration_cast<milliseconds>(
+        steady_clock::now().time_since_epoch())
+        .count();
+}
+
+// Called on the bg JS thread. Executes the callback only; the worker has
+// already erased (one-shot) or rescheduled (interval) the timer under lock.
+static void fireTimerOnJsThread(
+    int64_t timerId,
+    std::shared_ptr<jsi::Function> cb,
+    jsi::Runtime &rt) {
+    if (!cb) return;
+    try {
+        cb->call(rt);
+    } catch (const jsi::JSError &e) {
+        LOGE("Timer %lld callback JSError: %s", (long long)timerId,
+             e.getMessage().c_str());
+    } catch (const std::exception &e) {
+        LOGE("Timer %lld callback error: %s", (long long)timerId, e.what());
+    }
+}
+
+static void timerWorkerLoop() {
+    while (!gTimerWorkerStop.load()) {
+        // Snapshot of timers that should be dispatched this iteration and
+        // their callbacks. Captured under the lock; callbacks are invoked on
+        // the JS thread (not here).
+        std::vector<std::pair<int64_t, std::shared_ptr<jsi::Function>>> toFire;
+        RPCRuntimeExecutor executor;
+        {
+            std::unique_lock<std::mutex> lock(gTimerMutex);
+            if (gTimers.empty()) {
+                gTimerCv.wait(lock, [] {
+                    return gTimerWorkerStop.load() || !gTimers.empty();
+                });
+                if (gTimerWorkerStop.load()) return;
+                continue;
+            }
+
+            // Find the earliest fireAt among non-cancelled timers.
+            long long earliest = LLONG_MAX;
+            for (auto &kv : gTimers) {
+                if (!kv.second.cancelled && kv.second.fireAtMs < earliest) {
+                    earliest = kv.second.fireAtMs;
+                }
+            }
+            long long now = nowMs();
+            if (earliest == LLONG_MAX) {
+                // Only cancelled timers remain; clean them up.
+                for (auto it = gTimers.begin(); it != gTimers.end();) {
+                    if (it->second.cancelled) it = gTimers.erase(it);
+                    else ++it;
+                }
+                continue;
+            }
+            if (earliest > now) {
+                gTimerCv.wait_for(
+                    lock, std::chrono::milliseconds(earliest - now));
+                continue;
+            }
+
+            // Collect ready timers AND either erase (one-shot) or reschedule
+            // (interval) them RIGHT HERE under the lock. This is critical:
+            // if we wait to erase in fireTimerOnJsThread, the next worker
+            // iteration would immediately find the same timers still
+            // in-queue and re-dispatch them, causing an infinite flood of
+            // `scheduleOnJSThread` calls.
+            for (auto it = gTimers.begin(); it != gTimers.end();) {
+                if (it->second.cancelled) {
+                    it = gTimers.erase(it);
+                    continue;
+                }
+                if (it->second.fireAtMs <= now) {
+                    toFire.emplace_back(it->first, it->second.callback);
+                    if (it->second.intervalMs > 0) {
+                        // Reschedule interval. Use `now + intervalMs` rather
+                        // than `fireAtMs + intervalMs` so a slow fire path
+                        // cannot produce an infinite backlog.
+                        it->second.fireAtMs = now + it->second.intervalMs;
+                        ++it;
+                    } else {
+                        it = gTimers.erase(it);
+                    }
+                } else {
+                    ++it;
+                }
+            }
+            executor = gBgTimerExecutor;
+        }
+
+        if (!executor) {
+            std::this_thread::sleep_for(std::chrono::milliseconds(10));
+            continue;
+        }
+        for (auto &pair : toFire) {
+            int64_t id = pair.first;
+            std::shared_ptr<jsi::Function> cb = pair.second;
+            executor([id, cb](jsi::Runtime &rt) {
+                fireTimerOnJsThread(id, cb, rt);
+            });
+        }
+    }
+}
+
+static void ensureTimerWorkerStarted() {
+    bool expected = false;
+    if (gTimerWorkerStarted.compare_exchange_strong(expected, true)) {
+        gTimerWorkerStop.store(false);
+        gTimerWorkerThread = std::thread(timerWorkerLoop);
+        LOGI("Timer worker thread started");
+    }
+}
+
+static int64_t scheduleTimer(
+    std::shared_ptr<jsi::Function> cb,
+    double ms,
+    bool isInterval) {
+    int64_t id = gNextTimerId.fetch_add(1);
+    long long intervalMs = isInterval ? static_cast<long long>(ms) : 0;
+    long long delay = static_cast<long long>(ms);
+    if (delay < 0) delay = 0;
+    {
+        std::lock_guard<std::mutex> lock(gTimerMutex);
+        gTimers[id] = TimerEntry{
+            std::move(cb),
+            nowMs() + delay,
+            intervalMs,
+            false,
+        };
+    }
+    gTimerCv.notify_all();
+    ensureTimerWorkerStarted();
+    return id;
+}
+
+static void cancelTimer(int64_t id) {
+    {
+        std::lock_guard<std::mutex> lock(gTimerMutex);
+        auto it = gTimers.find(id);
+        if (it != gTimers.end()) {
+            it->second.cancelled = true;
+        }
+    }
+    gTimerCv.notify_all();
+}
+
+static void installTimersOnRuntime(jsi::Runtime &rt) {
+    auto makeSetter = [](bool isInterval) {
+        return [isInterval](
+                   jsi::Runtime &rt,
+                   const jsi::Value &,
+                   const jsi::Value *args,
+                   size_t count) -> jsi::Value {
+            if (count < 1 || !args[0].isObject() ||
+                !args[0].getObject(rt).isFunction(rt)) {
+                return jsi::Value::undefined();
+            }
+            auto cb = std::make_shared<jsi::Function>(
+                args[0].getObject(rt).getFunction(rt));
+            double ms = 0;
+            if (count >= 2 && args[1].isNumber()) {
+                ms = args[1].asNumber();
+            }
+            int64_t id = scheduleTimer(std::move(cb), ms, isInterval);
+            return jsi::Value(static_cast<double>(id));
+        };
+    };
+    auto makeCanceller = []() {
+        return [](jsi::Runtime &rt,
+                  const jsi::Value &,
+                  const jsi::Value *args,
+                  size_t count) -> jsi::Value {
+            if (count < 1 || !args[0].isNumber()) {
+                return jsi::Value::undefined();
+            }
+            int64_t id = static_cast<int64_t>(args[0].asNumber());
+            cancelTimer(id);
+            return jsi::Value::undefined();
+        };
+    };
+
+    // requestAnimationFrame(cb): fires after ~16ms (60fps) with high-resolution
+    // timestamp arg, matching the DOM contract. Background runtime has no
+    // rendering concept, so we just approximate via setTimeout(16ms).
+    auto rafFn = [](jsi::Runtime &rt,
+                     const jsi::Value &,
+                     const jsi::Value *args,
+                     size_t count) -> jsi::Value {
+        if (count < 1 || !args[0].isObject() ||
+            !args[0].getObject(rt).isFunction(rt)) {
+            return jsi::Value::undefined();
+        }
+        // Wrap callback so it receives a DOMHighResTimeStamp-like arg.
+        auto userCb = std::make_shared<jsi::Function>(
+            args[0].getObject(rt).getFunction(rt));
+        auto wrapper = jsi::Function::createFromHostFunction(
+            rt,
+            jsi::PropNameID::forAscii(rt, "rafWrapper"),
+            0,
+            [userCb](jsi::Runtime &rt2,
+                     const jsi::Value &,
+                     const jsi::Value *,
+                     size_t) -> jsi::Value {
+                try {
+                    userCb->call(rt2, jsi::Value(static_cast<double>(nowMs())));
+                } catch (const jsi::JSError &e) {
+                    LOGE("rAF callback JSError: %s", e.getMessage().c_str());
+                } catch (const std::exception &e) {
+                    LOGE("rAF callback error: %s", e.what());
+                }
+                return jsi::Value::undefined();
+            });
+        auto wrappedCb = std::make_shared<jsi::Function>(std::move(wrapper));
+        int64_t id = scheduleTimer(std::move(wrappedCb), 16.0, false);
+        return jsi::Value(static_cast<double>(id));
+    };
+
+    // requestIdleCallback(cb, {timeout?}): fires "soon" with an IdleDeadline-ish
+    // object. Background runtime has no render frames to be idle between, so
+    // we approximate via setTimeout(1ms) and provide a deadline stub whose
+    // timeRemaining() always returns 50 (reasonable budget).
+    auto ricFn = [](jsi::Runtime &rt,
+                     const jsi::Value &,
+                     const jsi::Value *args,
+                     size_t count) -> jsi::Value {
+        if (count < 1 || !args[0].isObject() ||
+            !args[0].getObject(rt).isFunction(rt)) {
+            return jsi::Value::undefined();
+        }
+        auto userCb = std::make_shared<jsi::Function>(
+            args[0].getObject(rt).getFunction(rt));
+        auto wrapper = jsi::Function::createFromHostFunction(
+            rt,
+            jsi::PropNameID::forAscii(rt, "ricWrapper"),
+            0,
+            [userCb](jsi::Runtime &rt2,
+                     const jsi::Value &,
+                     const jsi::Value *,
+                     size_t) -> jsi::Value {
+                try {
+                    // Build a minimal IdleDeadline: { didTimeout: false,
+                    // timeRemaining: () => 50 }.
+                    jsi::Object deadline(rt2);
+                    deadline.setProperty(rt2, "didTimeout", jsi::Value(false));
+                    deadline.setProperty(
+                        rt2,
+                        "timeRemaining",
+                        jsi::Function::createFromHostFunction(
+                            rt2,
+                            jsi::PropNameID::forAscii(rt2, "timeRemaining"),
+                            0,
+                            [](jsi::Runtime &,
+                               const jsi::Value &,
+                               const jsi::Value *,
+                               size_t) -> jsi::Value {
+                                return jsi::Value(50.0);
+                            }));
+                    userCb->call(rt2, jsi::Value(rt2, std::move(deadline)));
+                } catch (const jsi::JSError &e) {
+                    LOGE("rIC callback JSError: %s", e.getMessage().c_str());
+                } catch (const std::exception &e) {
+                    LOGE("rIC callback error: %s", e.what());
+                }
+                return jsi::Value::undefined();
+            });
+        auto wrappedCb = std::make_shared<jsi::Function>(std::move(wrapper));
+        int64_t id = scheduleTimer(std::move(wrappedCb), 1.0, false);
+        return jsi::Value(static_cast<double>(id));
+    };
+
+    auto global = rt.global();
+    global.setProperty(
+        rt, "setTimeout",
+        jsi::Function::createFromHostFunction(
+            rt, jsi::PropNameID::forAscii(rt, "setTimeout"), 2,
+            makeSetter(false)));
+    global.setProperty(
+        rt, "setInterval",
+        jsi::Function::createFromHostFunction(
+            rt, jsi::PropNameID::forAscii(rt, "setInterval"), 2,
+            makeSetter(true)));
+    global.setProperty(
+        rt, "clearTimeout",
+        jsi::Function::createFromHostFunction(
+            rt, jsi::PropNameID::forAscii(rt, "clearTimeout"), 1,
+            makeCanceller()));
+    global.setProperty(
+        rt, "clearInterval",
+        jsi::Function::createFromHostFunction(
+            rt, jsi::PropNameID::forAscii(rt, "clearInterval"), 1,
+            makeCanceller()));
+    global.setProperty(
+        rt, "requestAnimationFrame",
+        jsi::Function::createFromHostFunction(
+            rt, jsi::PropNameID::forAscii(rt, "requestAnimationFrame"), 1,
+            rafFn));
+    global.setProperty(
+        rt, "cancelAnimationFrame",
+        jsi::Function::createFromHostFunction(
+            rt, jsi::PropNameID::forAscii(rt, "cancelAnimationFrame"), 1,
+            makeCanceller()));
+    global.setProperty(
+        rt, "requestIdleCallback",
+        jsi::Function::createFromHostFunction(
+            rt, jsi::PropNameID::forAscii(rt, "requestIdleCallback"), 1,
+            ricFn));
+    global.setProperty(
+        rt, "cancelIdleCallback",
+        jsi::Function::createFromHostFunction(
+            rt, jsi::PropNameID::forAscii(rt, "cancelIdleCallback"), 1,
+            makeCanceller()));
+    LOGI("Timer + rAF + rIC polyfills installed on bg runtime");
 }
 
 // ── nativeInstallSharedBridge ───────────────────────────────────────────
@@ -145,9 +504,20 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeInstallSharedBridge(
     };
 
     std::string runtimeId = isMain ? "main" : "background";
+    // Save the bg executor so our custom timer worker can dispatch callbacks
+    // back to the bg JS queue. We must do this BEFORE moving `executor` into
+    // SharedRPC::install (which will std::move it out).
+    if (!capturedIsMain) {
+        gBgTimerExecutor = executor;
+    }
     SharedRPC::install(*rt, std::move(executor), runtimeId);
     LOGI("SharedStore and SharedRPC installed (isMain=%d)", static_cast<int>(isMain));
     if (!capturedIsMain) {
+        // Install setTimeout/setInterval/clearTimeout/clearInterval on the
+        // background runtime. React Native's built-in timer module only wires
+        // into the main runtime, so without this, any `await wait(ms)` or
+        // setTimeout callback in the background thread would never fire.
+        installTimersOnRuntime(*rt);
         invokeOptionalGlobalFunction(*rt, "__setupBackgroundRPCHandler");
     }
 }
@@ -226,5 +596,41 @@ Java_com_backgroundthread_BackgroundThreadManager_nativeDestroy(
     SharedRPC::reset();
     SharedStore::reset();
 
+    // Stop and join the timer worker before touching any shared state it
+    // reads. Without this, the worker could finish one last dispatch after
+    // we clear gTimers / gBgTimerExecutor and enqueue stale work against
+    // the about-to-be-destroyed runtime.
+    gTimerWorkerStop.store(true);
+    gTimerCv.notify_all();
+    if (gTimerWorkerThread.joinable()) {
+        gTimerWorkerThread.join();
+    }
+    gTimerWorkerStarted.store(false);
+
+    // Intentionally leak remaining jsi::Function callbacks (same rationale
+    // as SharedRPC::reset): destroying them here would run ~jsi::Function
+    // on the torn-down runtime and crash.
+    {
+        std::lock_guard<std::mutex> lock(gTimerMutex);
+        for (auto &entry : gTimers) {
+            if (entry.second.callback) {
+                new std::shared_ptr<jsi::Function>(std::move(entry.second.callback));
+            }
+        }
+        gTimers.clear();
+        gBgTimerExecutor = nullptr;
+    }
+
+    // Drain pending cross-runtime work. Each std::function may capture a
+    // shared_ptr<jsi::Function> tied to the destroyed runtime; leak them
+    // for the same reason as above.
+    {
+        std::lock_guard<std::mutex> lock(gWorkMutex);
+        for (auto &entry : gPendingWork) {
+            new std::function<void(jsi::Runtime &)>(std::move(entry.second));
+        }
+        gPendingWork.clear();
+    }
+
     LOGI("Native resources cleaned up");
 }

package/android/src/main/java/com/backgroundthread/BackgroundThreadManager.kt

@@ -1,6 +1,10 @@
 package com.backgroundthread
 
+import android.app.Activity
+import android.content.Intent
 import android.net.Uri
+import android.os.Handler
+import android.os.Looper
 import com.facebook.react.ReactPackage
 import com.facebook.proguard.annotations.DoNotStrip
 import com.facebook.react.ReactInstanceEventListener
@@ -16,6 +20,7 @@ import com.facebook.react.runtime.ReactHostImpl
 import com.facebook.react.runtime.hermes.HermesInstance
 import com.facebook.react.shell.MainReactPackage
 import java.io.File
+import java.lang.ref.WeakReference
 
 /**
  * Singleton manager for the background React Native runtime.
@@ -31,6 +36,11 @@ class BackgroundThreadManager private constructor() {
     private var bgReactHost: ReactHostImpl? = null
     private var reactPackages: List<ReactPackage> = emptyList()
 
+    // Tracks the last resumed Activity so we can replay it onto the bg
+    // ReactContext as soon as the bg host finishes initializing (covers the
+    // cold-start race where Activity resumes before bg host is ready).
+    private var lastResumedActivityRef: WeakReference<Activity> = WeakReference(null)
+
     @Volatile
     private var bgRuntimePtr: Long = 0
 
@@ -329,6 +339,11 @@ class BackgroundThreadManager private constructor() {
             override fun onReactContextInitialized(context: ReactContext) {
                 val initMs = (System.nanoTime() - bgStartTime) / 1_000_000.0
                 BTLogger.info("[SplitBundle] background ReactContext initialized in ${String.format("%.1f", initMs)}ms")
+                // Replay the most recent Activity resume so TurboModules on the
+                // bg host can see getCurrentActivity()/ActivityEventListeners
+                // from the very first call, even when the bg host finishes
+                // initializing after the Activity is already resumed.
+                replayLastResumedActivityOnUi()
                 context.runOnJSQueueThread {
                     try {
                         val ptr = context.javaScriptContextHolder?.get() ?: 0L
@@ -417,22 +432,328 @@ class BackgroundThreadManager private constructor() {
             return
         }
 
-        context.runOnJSQueueThread {
+        // Use ReactContext.registerSegment which works in both bridge
+        // and bridgeless modes.
+        try {
+            context.registerSegment(segmentId, path) {
+                BTLogger.info("Segment registered in background runtime: id=$segmentId, path=$path")
+                onComplete(null)
+            }
+        } catch (e: Exception) {
+            BTLogger.error("Failed to register segment in background runtime: ${e.message}")
+            onComplete(e)
+        }
+    }
+
+    // ── Activity lifecycle bridge (selective, reflection-based) ─────────────
+    //
+    // Goal: let a small, explicit allowlist of native modules on the bg
+    // ReactHost observe Activity-related state (getCurrentActivity(),
+    // onActivityResult, onNewIntent, and — for the same allowlist —
+    // onHostResume/onHostPause/onHostDestroy) WITHOUT triggering any side
+    // effects on other modules that happen to live on the same ReactContext.
+    //
+    // Why not use ReactHost.onHostResume / onActivityResult directly?
+    //   Those internally fan out to ALL LifecycleEventListeners and
+    //   ActivityEventListeners registered on the ReactContext, which would
+    //   cause every bg TurboModule that tracks host lifecycle (BroadcastReceivers,
+    //   sensors, keyboard observers, etc.) to receive a second set of callbacks
+    //   in addition to the UI host. That doubles resource registration, opens
+    //   requestCode collisions on Activity results, and can tear down the bg
+    //   ReactContext during rotation. We need fine-grained control, which RN
+    //   does not expose, so we operate on the underlying fields directly.
+    //
+    // What we actually do:
+    //   - Reflect-write bg ReactContext's `mCurrentActivity` so
+    //     getCurrentActivity() returns the correct Activity for modules that
+    //     bother to query it. Modules that don't query it are unaffected.
+    //   - Read `mActivityEventListeners` via reflection and invoke ONLY the
+    //     listeners whose class FQCN matches an entry in
+    //     `bgActivityBridgeListenerClassAllowlist` (for onActivityResult/onNewIntent).
+    //   - Read `mLifecycleEventListeners` via reflection and invoke
+    //     onHostResume/onHostPause/onHostDestroy on listeners whose class
+    //     FQCN matches the same allowlist. Non-allowlisted listeners are
+    //     never fired on the bg host — preserving the pre-existing baseline
+    //     that bg was "never resumed".
+    //   - Deliberately do NOT touch `mLifecycleState` — setting it to RESUMED
+    //     would cause `addLifecycleEventListener(...)` to auto-fire
+    //     `onHostResume()` on EVERY newly-registered listener (including
+    //     non-allowlisted ones), reintroducing the double-dispatch we're
+    //     trying to avoid. Instead we fire onHostResume manually on each
+    //     dispatchActivityResumed, which covers the common case; a listener
+    //     registered strictly between two resume events will catch up on
+    //     the next cycle.
+    //
+    // Trade-off:
+    //   We rely on RN-internal field names `mCurrentActivity`,
+    //   `mActivityEventListeners`, `mLifecycleEventListeners` on
+    //   `com.facebook.react.bridge.ReactContext`. An RN upgrade that
+    //   renames or restructures these fields will cause reflection to fail
+    //   (caught and logged via BTLogger → OneKeyLog). Mitigate with a
+    //   dev-build smoke assertion at the call site.
+    //
+    // Thread safety:
+    //   ReactContext.onHostResume / onActivityResult are @ThreadConfined(UI);
+    //   we match that by bouncing to the main looper. The underlying sets
+    //   are CopyOnWriteArraySet, so iterating them off-thread would still be
+    //   safe, but UI-thread is the documented contract and we stick to it.
+
+    // ── Allowlist (registered externally by the host app) ───────────────────
+    //
+    // FQCN prefixes of ActivityEventListener / LifecycleEventListener
+    // implementations that are allowed to receive Activity-bound events
+    // (onActivityResult, onNewIntent, onHostResume/Pause/Destroy) on the
+    // bg ReactHost. Anything not matching a registered prefix is fully
+    // ignored on bg, preserving the pre-existing baseline.
+    //
+    // The bg-thread module deliberately ships an EMPTY default — the host
+    // application is the only place that knows which third-party modules
+    // are bg-eligible. Register entries early in Application.onCreate via
+    // addBgActivityBridgeListenerClassPrefix(...) so the allowlist is populated
+    // before the first Activity lifecycle callback can fire.
+    //
+    // Adding a prefix is a cross-runtime change. Verify:
+    //   1. The module's listener is idempotent and safe to fire.
+    //   2. ActivityResult requestCodes do not collide with other modules.
+    //   3. Any LifecycleEventListener side-effects are double-host safe.
+    @Volatile
+    private var bgActivityBridgeListenerClassAllowlist: Set<String> = emptySet()
+
+    /** Add a single FQCN-prefix entry to the allowlist (idempotent). */
+    @Synchronized
+    fun addBgActivityBridgeListenerClassPrefix(prefix: String) {
+        if (prefix.isEmpty()) return
+        if (bgActivityBridgeListenerClassAllowlist.contains(prefix)) return
+        bgActivityBridgeListenerClassAllowlist = bgActivityBridgeListenerClassAllowlist + prefix
+        BTLogger.info("addBgActivityBridgeListenerClassPrefix: $prefix " +
+            "(total=${bgActivityBridgeListenerClassAllowlist.size})")
+    }
+
+    /** Replace the allowlist wholesale. Intended for test setup / reload. */
+    @Synchronized
+    fun setBgActivityBridgeListenerClassAllowlist(prefixes: Set<String>) {
+        bgActivityBridgeListenerClassAllowlist = prefixes.toSet()
+        BTLogger.info("setBgActivityBridgeListenerClassAllowlist: ${prefixes.size} entries")
+    }
+
+    /** Inspect the current allowlist (snapshot). */
+    fun getBgActivityBridgeListenerClassAllowlist(): Set<String> =
+        bgActivityBridgeListenerClassAllowlist
+
+    fun dispatchActivityResumed(activity: Activity) {
+        lastResumedActivityRef = WeakReference(activity)
+        runOnUiThread {
+            writeBgCurrentActivity(activity)
+            dispatchLifecycleEventToAllowlisted(LifecycleEvent.RESUME)
+        }
+    }
+
+    fun dispatchActivityPaused(activity: Activity) {
+        // Keep mCurrentActivity — Activity is still valid until destroyed,
+        // and clearing it between pause/resume would flap getCurrentActivity().
+        // LifecycleEventListener.onHostPause() IS fired for allowlisted
+        // modules so they can quiesce work (mirrors RN's UI-host behaviour).
+        runOnUiThread {
+            dispatchLifecycleEventToAllowlisted(LifecycleEvent.PAUSE)
+        }
+    }
+
+    fun dispatchActivityDestroyed(activity: Activity) {
+        if (lastResumedActivityRef.get() === activity) {
+            lastResumedActivityRef = WeakReference(null)
+        }
+        runOnUiThread {
+            val ctx = bgReactHost?.currentReactContext ?: return@runOnUiThread
+            // Only clear if the bg context's tracked Activity IS the one
+            // being destroyed. Guards against a stale clear when the host
+            // Activity is swapped (e.g. multi-Activity deep-link flows).
+            if (ctx.currentActivity === activity) {
+                writeBgCurrentActivity(null)
+                dispatchLifecycleEventToAllowlisted(LifecycleEvent.DESTROY)
+            }
+        }
+    }
+
+    private enum class LifecycleEvent { RESUME, PAUSE, DESTROY }
+
+    /**
+     * Iterate bg ReactContext's LifecycleEventListener set and fire the
+     * requested callback on listeners whose class FQCN matches the
+     * allowlist. Modules outside the allowlist are completely unaffected
+     * (they stay on the pre-existing "never-resumed on bg" baseline).
+     *
+     * Note on edge case: a LifecycleEventListener registered AFTER the
+     * corresponding dispatch event will miss that event, because we don't
+     * touch mLifecycleState (doing so would cause RN's
+     * addLifecycleEventListener to auto-fire onHostResume on EVERY new
+     * listener, including non-allowlisted ones). The next resume/pause/
+     * destroy cycle picks it up. This is consistent with how modules that
+     * register late behave against the UI host anyway.
+     */
+    private fun dispatchLifecycleEventToAllowlisted(event: LifecycleEvent) {
+        val listeners = readBgLifecycleListeners() ?: return
+        for (l in listeners) {
+            if (!isBgListenerAllowed(l)) continue
             try {
-                if (context.hasCatalystInstance()) {
-                    context.catalystInstance.registerSegment(segmentId, path)
-                    BTLogger.info("Segment registered in background runtime: id=$segmentId, path=$path")
-                    onComplete(null)
-                } else {
-                    onComplete(IllegalStateException("Background CatalystInstance not available for segment registration"))
+                when (event) {
+                    LifecycleEvent.RESUME -> l.onHostResume()
+                    LifecycleEvent.PAUSE -> l.onHostPause()
+                    LifecycleEvent.DESTROY -> l.onHostDestroy()
+                }
+            } catch (t: Throwable) {
+                BTLogger.error("bg lifecycle ${event.name} dispatch (${l.javaClass.name}): ${t.message}")
+            }
+        }
+    }
+
+    fun dispatchActivityResult(
+        activity: Activity,
+        requestCode: Int,
+        resultCode: Int,
+        data: Intent?
+    ) {
+        runOnUiThread {
+            val listeners = readBgActivityListeners() ?: return@runOnUiThread
+            for (l in listeners) {
+                if (!isBgListenerAllowed(l)) continue
+                try {
+                    l.onActivityResult(activity, requestCode, resultCode, data)
+                } catch (t: Throwable) {
+                    BTLogger.error("bg onActivityResult dispatch (${l.javaClass.name}): ${t.message}")
+                }
+            }
+        }
+    }
+
+    fun dispatchNewIntent(intent: Intent) {
+        runOnUiThread {
+            val listeners = readBgActivityListeners() ?: return@runOnUiThread
+            for (l in listeners) {
+                if (!isBgListenerAllowed(l)) continue
+                try {
+                    l.onNewIntent(intent)
+                } catch (t: Throwable) {
+                    BTLogger.error("bg onNewIntent dispatch (${l.javaClass.name}): ${t.message}")
                 }
-            } catch (e: Exception) {
-                BTLogger.error("Failed to register segment in background runtime: ${e.message}")
-                onComplete(e)
             }
         }
     }
 
+    /**
+     * Called when the bg ReactContext becomes available so we can install
+     * the last resumed Activity right away, covering the window where the
+     * host Activity resumes before the bg host finishes initializing.
+     */
+    private fun replayLastResumedActivityOnUi() {
+        val activity = lastResumedActivityRef.get() ?: return
+        runOnUiThread {
+            if (writeBgCurrentActivity(activity)) {
+                BTLogger.info("replayLastResumedActivityOnUi: mCurrentActivity=${activity.javaClass.simpleName}")
+            }
+            // Fire RESUME for allowlisted modules whose listener was
+            // registered before the bg ReactContext finished initializing.
+            dispatchLifecycleEventToAllowlisted(LifecycleEvent.RESUME)
+        }
+    }
+
+    /**
+     * Reflect-write `mCurrentActivity` on the bg ReactContext so
+     * TurboModules on that host see a non-null getCurrentActivity().
+     *
+     * Returns true on success.
+     */
+    private fun writeBgCurrentActivity(activity: Activity?): Boolean {
+        val ctx = bgReactHost?.currentReactContext ?: return false
+        return try {
+            val field = findField(ctx.javaClass, "mCurrentActivity") ?: run {
+                BTLogger.error("writeBgCurrentActivity: mCurrentActivity field not found (RN upgrade?)")
+                return false
+            }
+            field.isAccessible = true
+            field.set(ctx, if (activity != null) WeakReference(activity) else null)
+            true
+        } catch (t: Throwable) {
+            BTLogger.error("writeBgCurrentActivity: ${t.message}")
+            false
+        }
+    }
+
+    /**
+     * Reflect-read bg ReactContext's `mActivityEventListeners` set so we
+     * can iterate it without going through ReactContext.onActivityResult
+     * (which would fan out to every listener unconditionally).
+     */
+    @Suppress("UNCHECKED_CAST")
+    private fun readBgActivityListeners(): Collection<com.facebook.react.bridge.ActivityEventListener>? {
+        val ctx = bgReactHost?.currentReactContext ?: return null
+        return try {
+            val field = findField(ctx.javaClass, "mActivityEventListeners") ?: run {
+                BTLogger.error("readBgActivityListeners: field not found (RN upgrade?)")
+                return null
+            }
+            field.isAccessible = true
+            field.get(ctx) as? Collection<com.facebook.react.bridge.ActivityEventListener>
+        } catch (t: Throwable) {
+            BTLogger.error("readBgActivityListeners: ${t.message}")
+            null
+        }
+    }
+
+    /**
+     * Reflect-read bg ReactContext's `mLifecycleEventListeners` set. Same
+     * rationale as readBgActivityListeners — we iterate ourselves so we
+     * can apply the allowlist filter, avoiding a fan-out to every
+     * LifecycleEventListener on the bg ReactContext.
+     */
+    @Suppress("UNCHECKED_CAST")
+    private fun readBgLifecycleListeners(): Collection<com.facebook.react.bridge.LifecycleEventListener>? {
+        val ctx = bgReactHost?.currentReactContext ?: return null
+        return try {
+            val field = findField(ctx.javaClass, "mLifecycleEventListeners") ?: run {
+                BTLogger.error("readBgLifecycleListeners: field not found (RN upgrade?)")
+                return null
+            }
+            field.isAccessible = true
+            field.get(ctx) as? Collection<com.facebook.react.bridge.LifecycleEventListener>
+        } catch (t: Throwable) {
+            BTLogger.error("readBgLifecycleListeners: ${t.message}")
+            null
+        }
+    }
+
+    /**
+     * Walks the class hierarchy to find a declared field by name.
+     * `mCurrentActivity` and `mActivityEventListeners` live on
+     * `ReactContext`, but bg runs `BridgelessReactContext` which subclasses
+     * `ReactApplicationContext` which subclasses `ReactContext`, so we
+     * can't use getDeclaredField directly on the runtime class.
+     */
+    private fun findField(cls: Class<*>, name: String): java.lang.reflect.Field? {
+        var c: Class<*>? = cls
+        while (c != null) {
+            try { return c.getDeclaredField(name) } catch (_: NoSuchFieldException) {}
+            c = c.superclass
+        }
+        return null
+    }
+
+    private fun isBgListenerAllowed(listener: Any): Boolean {
+        val fqcn = listener.javaClass.name
+        val list = bgActivityBridgeListenerClassAllowlist
+        for (prefix in list) {
+            if (fqcn.startsWith(prefix)) return true
+        }
+        return false
+    }
+
+    private fun runOnUiThread(block: () -> Unit) {
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            block()
+        } else {
+            Handler(Looper.getMainLooper()).post(block)
+        }
+    }
+
     // ── Lifecycle ───────────────────────────────────────────────────────────
 
     val isBackgroundStarted: Boolean get() = isStarted
@@ -445,5 +766,6 @@ class BackgroundThreadManager private constructor() {
         bgReactHost?.destroy("BackgroundThreadManager destroyed", null)
         bgReactHost = null
         isStarted = false
+        lastResumedActivityRef = WeakReference(null)
     }
 }

package/ios/BackgroundThreadManager.mm

@@ -107,7 +107,12 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
         self.reactNativeFactoryDelegate = [[BackgroundReactNativeDelegate alloc] init];
         self.reactNativeFactory = [[RCTReactNativeFactory alloc] initWithDelegate:self.reactNativeFactoryDelegate];
 
-        [self.reactNativeFactoryDelegate setJsBundleSource:std::string([entryURL UTF8String])];
+        // Only set jsBundleSource for debug HTTP URLs or explicit OTA overrides.
+        // Leaving the default release name ("background.bundle") unset lets the
+        // delegate fall back to split-bundle mode (common.jsbundle + entry).
+        if (![entryURL isEqualToString:@"background.bundle"]) {
+            [self.reactNativeFactoryDelegate setJsBundleSource:std::string([entryURL UTF8String])];
+        }
 
         [self.reactNativeFactory.rootViewFactory viewWithModuleName:MODULE_NAME
                                                      initialProperties:initialProperties

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-background-thread",
-  "version": "3.0.17",
+  "version": "3.0.19",
   "description": "react-native-background-thread",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",