@onekeyfe/react-native-background-thread 1.1.46 → 1.1.48

package/BackgroundThread.podspec

@@ -13,8 +13,10 @@ Pod::Spec.new do |s|
   s.platforms    = { :ios => min_ios_version_supported }
   s.source       = { :git => "https://github.com/OneKeyHQ/app-modules/react-native-background-thread.git", :tag => "#{s.version}" }
 
-  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
-  s.public_header_files = "ios/**/*.h"
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}", "cpp/**/*.{h,cpp}"
+  s.public_header_files = "ios/BackgroundThreadManager.h", "ios/BTLogger.h"
+  s.pod_target_xcconfig = { 'HEADER_SEARCH_PATHS' => '"$(PODS_TARGET_SRCROOT)/cpp"', 'DEFINES_MODULE' => 'YES' }
+  s.user_target_xcconfig = { 'SWIFT_INCLUDE_PATHS' => '"$(PODS_ROOT)/Headers/Public/BackgroundThread"' }
 
   s.dependency 'ReactNativeNativeLogger'
 

package/android/CMakeLists.txt

@@ -0,0 +1,29 @@
+cmake_minimum_required(VERSION 3.13)
+project(background_thread)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+
+find_package(fbjni REQUIRED CONFIG)
+find_package(ReactAndroid REQUIRED CONFIG)
+
+add_library(${PROJECT_NAME} SHARED
+    src/main/cpp/cpp-adapter.cpp
+    ../cpp/SharedStore.cpp
+    ../cpp/SharedRPC.cpp
+)
+
+target_include_directories(${PROJECT_NAME} PRIVATE
+    src/main/cpp
+    ../cpp
+)
+
+find_library(LOG_LIB log)
+
+target_link_libraries(${PROJECT_NAME}
+    ${LOG_LIB}
+    fbjni::fbjni
+    ReactAndroid::jsi
+    ReactAndroid::reactnative
+    android
+)

package/android/build.gradle

@@ -25,6 +25,11 @@ def getExtOrIntegerDefault(name) {
   return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["BackgroundThread_" + name]).toInteger()
 }
 
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
 android {
   namespace "com.backgroundthread"
 
@@ -33,10 +38,47 @@ android {
   defaultConfig {
     minSdkVersion getExtOrIntegerDefault("minSdkVersion")
     targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared",
+                  "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters(*reactNativeArchitectures())
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
   }
 
   buildFeatures {
     buildConfig true
+    prefab true
+  }
+
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libfolly_json.so",
+      "**/libfolly_runtime.so",
+      "**/libglog.so",
+      "**/libhermes.so",
+      "**/libhermes-executor-debug.so",
+      "**/libhermes_executor.so",
+      "**/libreactnative.so",
+      "**/libreactnativejni.so",
+      "**/libturbomodulejsijni.so",
+      "**/libreact_nativemodule_core.so",
+      "**/libjscexecutor.so"
+    ]
   }
 
   buildTypes {

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

@@ -0,0 +1,222 @@
+#include <jni.h>
+#include <jsi/jsi.h>
+#include <android/log.h>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+
+#include "SharedStore.h"
+#include "SharedRPC.h"
+
+#define LOG_TAG "BackgroundThread"
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+
+namespace jsi = facebook::jsi;
+
+static JavaVM *gJavaVM = nullptr;
+
+extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
+    gJavaVM = vm;
+    return JNI_VERSION_1_6;
+}
+
+static JNIEnv *getJNIEnv() {
+    JNIEnv *env = nullptr;
+    if (gJavaVM) {
+        gJavaVM->AttachCurrentThread(&env, nullptr);
+    }
+    return env;
+}
+
+// Stub a JSI function on an object (replaces it with a no-op).
+static void stubJsiFunction(jsi::Runtime &runtime, jsi::Object &object, const char *name) {
+    object.setProperty(
+        runtime,
+        name,
+        jsi::Function::createFromHostFunction(
+            runtime, jsi::PropNameID::forUtf8(runtime, name), 1,
+            [](auto &, const auto &, const auto *, size_t) {
+                return jsi::Value::undefined();
+            }));
+}
+
+static void invokeOptionalGlobalFunction(jsi::Runtime &runtime, const char *name) {
+    try {
+        auto fnValue = runtime.global().getProperty(runtime, name);
+        if (!fnValue.isObject() || !fnValue.asObject(runtime).isFunction(runtime)) {
+            return;
+        }
+
+        auto fn = fnValue.asObject(runtime).asFunction(runtime);
+        fn.call(runtime);
+    } catch (const jsi::JSError &e) {
+        LOGE("JSError calling global function %s: %s", name, e.getMessage().c_str());
+    } catch (const std::exception &e) {
+        LOGE("Error calling global function %s: %s", name, e.what());
+    }
+}
+
+// ── Pending work map for cross-runtime executor ───────────────────────
+static std::mutex gWorkMutex;
+static std::unordered_map<int64_t, std::function<void(jsi::Runtime &)>> gPendingWork;
+static int64_t gNextWorkId = 0;
+
+// Called from Kotlin after runOnJSQueueThread dispatches to the correct thread.
+extern "C" JNIEXPORT void JNICALL
+Java_com_backgroundthread_BackgroundThreadManager_nativeExecuteWork(
+    JNIEnv *env, jobject thiz, jlong runtimePtr, jlong workId) {
+    LOGI("nativeExecuteWork: runtimePtr=%ld, workId=%ld", (long)runtimePtr, (long)workId);
+    auto *rt = reinterpret_cast<jsi::Runtime *>(runtimePtr);
+    if (!rt) return;
+
+    std::function<void(jsi::Runtime &)> work;
+    {
+        std::lock_guard<std::mutex> lock(gWorkMutex);
+        auto it = gPendingWork.find(workId);
+        if (it == gPendingWork.end()) return;
+        work = std::move(it->second);
+        gPendingWork.erase(it);
+    }
+    try {
+        work(*rt);
+    } catch (const jsi::JSError &e) {
+        LOGE("JSError in nativeExecuteWork: %s", e.getMessage().c_str());
+    } catch (const std::exception &e) {
+        LOGE("Error in nativeExecuteWork: %s", e.what());
+    }
+}
+
+// ── nativeInstallSharedBridge ───────────────────────────────────────────
+// Install SharedStore and SharedRPC into a runtime.
+extern "C" JNIEXPORT void JNICALL
+Java_com_backgroundthread_BackgroundThreadManager_nativeInstallSharedBridge(
+    JNIEnv *env, jobject thiz, jlong runtimePtr, jboolean isMain) {
+
+    auto *rt = reinterpret_cast<jsi::Runtime *>(runtimePtr);
+    if (!rt) return;
+
+    SharedStore::install(*rt);
+
+    // Create executor that schedules work on this runtime's JS thread via Kotlin
+    jobject ref = env->NewGlobalRef(thiz);
+    bool capturedIsMain = static_cast<bool>(isMain);
+
+    RPCRuntimeExecutor executor = [ref, capturedIsMain](std::function<void(jsi::Runtime &)> work) {
+        JNIEnv *env = getJNIEnv();
+        if (!env || !ref) {
+            LOGE("executor: env=%p, ref=%p — aborting", env, ref);
+            return;
+        }
+
+        int64_t workId;
+        {
+            std::lock_guard<std::mutex> lock(gWorkMutex);
+            workId = gNextWorkId++;
+            gPendingWork[workId] = std::move(work);
+        }
+
+        jclass cls = env->GetObjectClass(ref);
+        jmethodID mid = env->GetMethodID(cls, "scheduleOnJSThread", "(ZJ)V");
+        if (mid) {
+            LOGI("executor: calling scheduleOnJSThread(isMain=%d, workId=%ld)", capturedIsMain, (long)workId);
+            env->CallVoidMethod(ref, mid, static_cast<jboolean>(capturedIsMain), static_cast<jlong>(workId));
+            if (env->ExceptionCheck()) {
+                LOGE("executor: JNI exception after scheduleOnJSThread");
+                env->ExceptionDescribe();
+                env->ExceptionClear();
+            }
+        } else {
+            LOGE("executor: scheduleOnJSThread method not found!");
+            if (env->ExceptionCheck()) {
+                env->ExceptionDescribe();
+                env->ExceptionClear();
+            }
+        }
+        env->DeleteLocalRef(cls);
+    };
+
+    std::string runtimeId = isMain ? "main" : "background";
+    SharedRPC::install(*rt, std::move(executor), runtimeId);
+    LOGI("SharedStore and SharedRPC installed (isMain=%d)", static_cast<int>(isMain));
+    if (!capturedIsMain) {
+        invokeOptionalGlobalFunction(*rt, "__setupBackgroundRPCHandler");
+    }
+}
+
+// ── nativeSetupErrorHandler ─────────────────────────────────────────────
+// Wrap the global error handler in the background runtime.
+// Mirrors iOS BackgroundRunnerReactNativeDelegate.setupErrorHandler:.
+extern "C" JNIEXPORT void JNICALL
+Java_com_backgroundthread_BackgroundThreadManager_nativeSetupErrorHandler(
+    JNIEnv *env, jobject thiz, jlong runtimePtr) {
+
+    auto *runtime = reinterpret_cast<jsi::Runtime *>(runtimePtr);
+    if (!runtime) return;
+
+    try {
+        jsi::Object global = runtime->global();
+        jsi::Value errorUtilsVal = global.getProperty(*runtime, "ErrorUtils");
+        if (!errorUtilsVal.isObject()) {
+            LOGE("ErrorUtils is not available on global object");
+            return;
+        }
+
+        jsi::Object errorUtils = errorUtilsVal.asObject(*runtime);
+
+        // Capture the current global error handler
+        auto originalHandler = std::make_shared<jsi::Value>(
+            errorUtils.getProperty(*runtime, "getGlobalHandler")
+                .asObject(*runtime).asFunction(*runtime).call(*runtime));
+
+        // Create a custom handler that delegates to the original
+        auto handlerFunc = jsi::Function::createFromHostFunction(
+            *runtime,
+            jsi::PropNameID::forAscii(*runtime, "customGlobalErrorHandler"),
+            2,
+            [originalHandler](
+                jsi::Runtime &rt, const jsi::Value &,
+                const jsi::Value *args, size_t count) -> jsi::Value {
+                if (count < 2) {
+                    return jsi::Value::undefined();
+                }
+
+                if (originalHandler->isObject() &&
+                    originalHandler->asObject(rt).isFunction(rt)) {
+                    jsi::Function original =
+                        originalHandler->asObject(rt).asFunction(rt);
+                    original.call(rt, args, count);
+                }
+
+                return jsi::Value::undefined();
+            });
+
+        // Set the new global error handler
+        jsi::Function setHandler =
+            errorUtils.getProperty(*runtime, "setGlobalHandler")
+                .asObject(*runtime).asFunction(*runtime);
+        setHandler.call(*runtime, {std::move(handlerFunc)});
+
+        // Disable further setGlobalHandler from background JS
+        stubJsiFunction(*runtime, errorUtils, "setGlobalHandler");
+
+        LOGI("Error handler installed in background runtime");
+    } catch (const jsi::JSError &e) {
+        LOGE("JSError setting up error handler: %s", e.getMessage().c_str());
+    } catch (const std::exception &e) {
+        LOGE("Error setting up error handler: %s", e.what());
+    }
+}
+
+// ── nativeDestroy ───────────────────────────────────────────────────────
+// Clean up native resources.
+// Called from BackgroundThreadManager.destroy().
+extern "C" JNIEXPORT void JNICALL
+Java_com_backgroundthread_BackgroundThreadManager_nativeDestroy(
+    JNIEnv *env, jobject thiz) {
+
+    SharedRPC::reset();
+
+    LOGI("Native resources cleaned up");
+}

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

@@ -0,0 +1,55 @@
+package com.backgroundthread
+
+/**
+ * Lightweight logging wrapper that dynamically dispatches to OneKeyLog.
+ * Uses reflection to avoid a hard dependency on the native-logger module.
+ * Falls back to android.util.Log when OneKeyLog is not available.
+ *
+ * Mirrors iOS BTLogger.
+ */
+object BTLogger {
+    private const val TAG = "BackgroundThread"
+
+    private val logClass: Class<*>? by lazy {
+        try {
+            Class.forName("com.margelo.nitro.nativelogger.OneKeyLog")
+        } catch (_: ClassNotFoundException) {
+            null
+        }
+    }
+
+    private val methods by lazy {
+        val cls = logClass ?: return@lazy null
+        mapOf(
+            "debug" to cls.getMethod("debug", String::class.java, String::class.java),
+            "info" to cls.getMethod("info", String::class.java, String::class.java),
+            "warn" to cls.getMethod("warn", String::class.java, String::class.java),
+            "error" to cls.getMethod("error", String::class.java, String::class.java),
+        )
+    }
+
+    @JvmStatic
+    fun debug(message: String) = log("debug", message, android.util.Log.DEBUG)
+
+    @JvmStatic
+    fun info(message: String) = log("info", message, android.util.Log.INFO)
+
+    @JvmStatic
+    fun warn(message: String) = log("warn", message, android.util.Log.WARN)
+
+    @JvmStatic
+    fun error(message: String) = log("error", message, android.util.Log.ERROR)
+
+    private fun log(level: String, message: String, androidLogLevel: Int) {
+        val method = methods?.get(level)
+        if (method != null) {
+            try {
+                method.invoke(null, TAG, message)
+                return
+            } catch (_: Exception) {
+                // Fall through to android.util.Log
+            }
+        }
+        android.util.Log.println(androidLogLevel, TAG, message)
+    }
+}

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

@@ -0,0 +1,258 @@
+package com.backgroundthread
+
+import android.net.Uri
+import com.facebook.react.ReactPackage
+import com.facebook.proguard.annotations.DoNotStrip
+import com.facebook.react.ReactInstanceEventListener
+import com.facebook.react.bridge.JSBundleLoader
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContext
+import com.facebook.react.common.annotations.UnstableReactNativeAPI
+import com.facebook.react.defaults.DefaultComponentsRegistry
+import com.facebook.react.defaults.DefaultReactHostDelegate
+import com.facebook.react.defaults.DefaultTurboModuleManagerDelegate
+import com.facebook.react.fabric.ComponentFactory
+import com.facebook.react.runtime.ReactHostImpl
+import com.facebook.react.runtime.hermes.HermesInstance
+import com.facebook.react.shell.MainReactPackage
+import java.io.File
+
+/**
+ * Singleton manager for the background React Native runtime.
+ * Mirrors iOS BackgroundThreadManager.
+ *
+ * Responsibilities:
+ * - Manages background ReactHostImpl lifecycle
+ * - Installs SharedBridge into main and background runtimes
+ * - Cross-runtime communication via SharedRPC onWrite notifications
+ */
+class BackgroundThreadManager private constructor() {
+
+    private var bgReactHost: ReactHostImpl? = null
+    private var reactPackages: List<ReactPackage> = emptyList()
+
+    @Volatile
+    private var bgRuntimePtr: Long = 0
+
+    @Volatile
+    private var mainRuntimePtr: Long = 0
+    private var mainReactContext: ReactApplicationContext? = null
+    private var isStarted = false
+
+    companion object {
+        private const val MODULE_NAME = "background"
+
+        init {
+            System.loadLibrary("background_thread")
+        }
+
+        @Volatile
+        private var instance: BackgroundThreadManager? = null
+
+        @JvmStatic
+        fun getInstance(): BackgroundThreadManager {
+            return instance ?: synchronized(this) {
+                instance ?: BackgroundThreadManager().also { instance = it }
+            }
+        }
+    }
+
+    // ── JNI declarations ────────────────────────────────────────────────────
+
+    private external fun nativeInstallSharedBridge(runtimePtr: Long, isMain: Boolean)
+    private external fun nativeSetupErrorHandler(runtimePtr: Long)
+    private external fun nativeDestroy()
+    private external fun nativeExecuteWork(runtimePtr: Long, workId: Long)
+
+    // ── SharedBridge ────────────────────────────────────────────────────────
+
+    /**
+     * Install SharedBridge HostObject into the main (UI) runtime.
+     * Call this from installSharedBridge().
+     */
+    fun setReactPackages(packages: List<ReactPackage>) {
+        reactPackages = packages.toList()
+    }
+
+    fun installSharedBridgeInMainRuntime(context: ReactApplicationContext) {
+        mainReactContext = context
+        context.runOnJSQueueThread {
+            try {
+                val ptr = context.javaScriptContextHolder?.get() ?: 0L
+                if (ptr != 0L) {
+                    mainRuntimePtr = ptr
+                    nativeInstallSharedBridge(ptr, true)
+                    BTLogger.info("SharedBridge installed in main runtime")
+                } else {
+                    BTLogger.warn("Main runtime pointer is 0, cannot install SharedBridge")
+                }
+            } catch (e: Exception) {
+                BTLogger.error("Error installing SharedBridge in main runtime: ${e.message}")
+            }
+        }
+    }
+
+    // ── Background runner lifecycle ─────────────────────────────────────────
+
+    private fun isRemoteBundleUrl(entryURL: String): Boolean {
+        return entryURL.startsWith("http://") || entryURL.startsWith("https://")
+    }
+
+    private fun resolveLocalBundlePath(entryURL: String): String? {
+        if (entryURL.startsWith("file://")) {
+            return Uri.parse(entryURL).path
+        }
+        if (entryURL.startsWith("/")) {
+            return entryURL
+        }
+        return null
+    }
+
+    private fun createDownloadedBundleLoader(appContext: android.content.Context, entryURL: String): JSBundleLoader {
+        return object : JSBundleLoader() {
+            override fun loadScript(delegate: com.facebook.react.bridge.JSBundleLoaderDelegate): String {
+                val tempFile = File(appContext.cacheDir, "background.bundle")
+                try {
+                    java.net.URL(entryURL).openStream().use { input ->
+                        tempFile.outputStream().use { output ->
+                            input.copyTo(output)
+                        }
+                    }
+                    BTLogger.info("Background bundle downloaded to ${tempFile.absolutePath}")
+                } catch (e: Exception) {
+                    BTLogger.error("Failed to download background bundle: ${e.message}")
+                    throw RuntimeException("Failed to download background bundle from $entryURL", e)
+                }
+                delegate.loadScriptFromFile(tempFile.absolutePath, entryURL, false)
+                return entryURL
+            }
+        }
+    }
+
+    private fun createLocalFileBundleLoader(localPath: String, sourceURL: String): JSBundleLoader {
+        return object : JSBundleLoader() {
+            override fun loadScript(delegate: com.facebook.react.bridge.JSBundleLoaderDelegate): String {
+                val bundleFile = File(localPath)
+                if (!bundleFile.exists()) {
+                    BTLogger.error("Background bundle file does not exist: $localPath")
+                    throw RuntimeException("Background bundle file does not exist: $localPath")
+                }
+                delegate.loadScriptFromFile(bundleFile.absolutePath, sourceURL, false)
+                return sourceURL
+            }
+        }
+    }
+
+    @OptIn(UnstableReactNativeAPI::class)
+    fun startBackgroundRunnerWithEntryURL(context: ReactApplicationContext, entryURL: String) {
+        if (isStarted) {
+            BTLogger.warn("Background runner already started")
+            return
+        }
+        BTLogger.info("Starting background runner with entryURL: $entryURL")
+
+        val appContext = context.applicationContext
+        val packages =
+            if (reactPackages.isNotEmpty()) {
+                reactPackages
+            } else {
+                BTLogger.warn("No ReactPackages registered for background runtime; call setReactPackages(...) from host before start. Falling back to MainReactPackage only.")
+                listOf(MainReactPackage())
+            }
+
+        val localBundlePath = resolveLocalBundlePath(entryURL)
+        val bundleLoader =
+            when {
+                isRemoteBundleUrl(entryURL) -> createDownloadedBundleLoader(appContext, entryURL)
+                localBundlePath != null -> createLocalFileBundleLoader(localBundlePath, entryURL)
+                entryURL.startsWith("assets://") -> JSBundleLoader.createAssetLoader(appContext, entryURL, true)
+                else -> JSBundleLoader.createAssetLoader(appContext, "assets://$entryURL", true)
+            }
+
+        val delegate = DefaultReactHostDelegate(
+            jsMainModulePath = MODULE_NAME,
+            jsBundleLoader = bundleLoader,
+            reactPackages = packages,
+            jsRuntimeFactory = HermesInstance(),
+            turboModuleManagerDelegateBuilder = DefaultTurboModuleManagerDelegate.Builder(),
+        )
+
+        val componentFactory = ComponentFactory()
+        DefaultComponentsRegistry.register(componentFactory)
+
+        val host = ReactHostImpl(
+            appContext,
+            delegate,
+            componentFactory,
+            true,  /* allowPackagerServerAccess */
+            false, /* useDevSupport */
+        )
+        bgReactHost = host
+
+        host.addReactInstanceEventListener(object : ReactInstanceEventListener {
+            override fun onReactContextInitialized(context: ReactContext) {
+                BTLogger.info("Background ReactContext initialized")
+                context.runOnJSQueueThread {
+                    try {
+                        val ptr = context.javaScriptContextHolder?.get() ?: 0L
+                        if (ptr != 0L) {
+                            bgRuntimePtr = ptr
+                            nativeInstallSharedBridge(ptr, false)
+                            nativeSetupErrorHandler(ptr)
+                            BTLogger.info("SharedBridge and error handler installed in background runtime")
+                        } else {
+                            BTLogger.error("Background runtime pointer is 0")
+                        }
+                    } catch (e: Exception) {
+                        BTLogger.error("Error installing bindings in background runtime: ${e.message}")
+                    }
+                }
+            }
+        })
+
+        host.start()
+        isStarted = true
+    }
+
+    /**
+     * Called from C++ RuntimeExecutor to schedule work on the correct JS thread.
+     * Routes to main or background runtime's JS queue thread, then calls nativeExecuteWork.
+     */
+    @DoNotStrip
+    fun scheduleOnJSThread(isMain: Boolean, workId: Long) {
+        val context = if (isMain) mainReactContext else bgReactHost?.currentReactContext
+        BTLogger.info("scheduleOnJSThread: isMain=$isMain, workId=$workId, context=${context != null}")
+        if (context == null) {
+            BTLogger.error("scheduleOnJSThread: context is null! isMain=$isMain, mainCtx=${mainReactContext != null}, bgHost=${bgReactHost != null}, bgCtx=${bgReactHost?.currentReactContext != null}")
+        }
+        context?.runOnJSQueueThread {
+            // Re-read ptr inside the block — if a reload happened between
+            // scheduling and execution, the old ptr may be stale.
+            val ptr = if (isMain) mainRuntimePtr else bgRuntimePtr
+            BTLogger.info("scheduleOnJSThread runOnJSQueueThread: isMain=$isMain, workId=$workId, ptr=$ptr")
+            if (ptr != 0L) {
+                try {
+                    nativeExecuteWork(ptr, workId)
+                } catch (e: Exception) {
+                    BTLogger.error("Error executing work on JS thread: ${e.message}")
+                }
+            } else {
+                BTLogger.error("scheduleOnJSThread: ptr is 0! isMain=$isMain")
+            }
+        }
+    }
+
+    // ── Lifecycle ───────────────────────────────────────────────────────────
+
+    val isBackgroundStarted: Boolean get() = isStarted
+
+    fun destroy() {
+        nativeDestroy()
+        bgRuntimePtr = 0
+        mainRuntimePtr = 0
+        mainReactContext = null
+        bgReactHost?.destroy("BackgroundThreadManager destroyed", null)
+        bgReactHost = null
+        isStarted = false
+    }
+}

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

@@ -3,27 +3,27 @@ package com.backgroundthread
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.module.annotations.ReactModule
 
+/**
+ * TurboModule entry point for BackgroundThread.
+ * Delegates all heavy lifting to [BackgroundThreadManager] singleton.
+ *
+ * Mirrors iOS BackgroundThread.mm.
+ */
 @ReactModule(name = BackgroundThreadModule.NAME)
 class BackgroundThreadModule(reactContext: ReactApplicationContext) :
-  NativeBackgroundThreadSpec(reactContext) {
+    NativeBackgroundThreadSpec(reactContext) {
 
-  override fun getName(): String {
-    return NAME
-  }
+    companion object {
+        const val NAME = "BackgroundThread"
+    }
 
-  override fun initBackgroundThread() {
-    // TODO: Implement initBackgroundThread
-  }
+    override fun getName(): String = NAME
 
-  override fun postBackgroundMessage(message: String) {
-    // TODO: Implement postBackgroundMessage
-  }
+    override fun installSharedBridge() {
+        BackgroundThreadManager.getInstance().installSharedBridgeInMainRuntime(reactApplicationContext)
+    }
 
-  override fun startBackgroundRunnerWithEntryURL(entryURL: String) {
-    // TODO: Implement startBackgroundRunnerWithEntryURL
-  }
-
-  companion object {
-    const val NAME = "BackgroundThread"
-  }
+    override fun startBackgroundRunnerWithEntryURL(entryURL: String) {
+        BackgroundThreadManager.getInstance().startBackgroundRunnerWithEntryURL(reactApplicationContext, entryURL)
+    }
 }