@onekeyfe/react-native-background-thread 3.0.89 → 3.0.91

package/ios/BackgroundRunnerReactNativeDelegate.h

@@ -30,7 +30,13 @@ NS_ASSUME_NONNULL_BEGIN
  * @return Initialized delegate instance with filtered module access
  */
 - (instancetype)init;
-
+/// Configure debug startup as local common HBC followed by a remote
+/// modules-only background entry bundle.
+- (void)configureDevVendorCommonBundlePath:(NSString *)commonBundlePath
+                                  entryURL:(NSURL *)entryURL
+                               fingerprint:(NSString *)fingerprint
+                      backgroundHMREnabled:(BOOL)backgroundHMREnabled
+                         runtimeGeneration:(NSUInteger)runtimeGeneration;
 /**
  * Register a HBC segment in the background runtime (Phase 2.5 spike).
  * Uses RCTInstance's registerSegmentWithId:path: API.

package/ios/BackgroundRunnerReactNativeDelegate.mm

@@ -12,8 +12,9 @@
 #include "SharedRPC.h"
 
 #import <React/RCTBridge.h>
+#import <React/RCTAssert.h>
 #import <React/RCTBundleURLProvider.h>
-
+#import <React/RCTJavaScriptLoader.h>
 #if __has_include(<react/utils/FollyConvert.h>)
   // static libs / header maps (no use_frameworks!)
   #import <react/utils/FollyConvert.h>
@@ -42,7 +43,33 @@
 namespace jsi = facebook::jsi;
 namespace TurboModuleConvertUtils = facebook::react::TurboModuleConvertUtils;
 using namespace facebook::react;
-
+namespace {
+constexpr int64_t kDevVendorLoadTimeoutSeconds = 60;
+class BackgroundNSDataJSIBuffer : public facebook::jsi::Buffer {
+ public:
+  explicit BackgroundNSDataJSIBuffer(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_;
+};
+}  // namespace
+@interface BTDevVendorDownloadState : NSObject
+@property (nonatomic, strong, nullable) NSData *data;
+@property (nonatomic, strong, nullable) NSError *error;
+@property (nonatomic, strong) dispatch_semaphore_t ready;
+@end
+@implementation BTDevVendorDownloadState
+- (instancetype)init
+{
+  if (self = [super init]) {
+    _ready = dispatch_semaphore_create(0);
+  }
+  return self;
+}
+@end
 static void stubJsiFunction(jsi::Runtime &runtime, jsi::Object &object, const char *name)
 {
   object.setProperty(
@@ -163,6 +190,11 @@ static NSURL *resolveBundleSourceURL(NSString *jsBundleSourceNS)
   RCTInstance *_rctInstance;
   std::string _origin;
   std::string _jsBundleSource;
+  NSString *_devVendorCommonBundlePath;
+  NSURL *_devVendorEntryURL;
+  NSString *_devVendorFingerprint;
+  BOOL _devVendorBackgroundHMREnabled;
+  NSUInteger _backgroundRuntimeGeneration;
   // YES when `bundleURL` observed an active OTA main bundle on its most
   // recent invocation, regardless of whether OTA common actually resolved.
   // Captures the invariant "this delegate is locked to OTA territory; IPA
@@ -182,7 +214,11 @@ static NSURL *resolveBundleSourceURL(NSString *jsBundleSourceNS)
 
 - (void)cleanupResources;
 - (void)setupErrorHandler:(jsi::Runtime &)runtime;
-
+- (void)finishHostStartWithBundleData:(NSData * _Nullable)bundleData
+                            sourceURL:(NSString * _Nullable)sourceURL
+                          fingerprint:(NSString * _Nullable)fingerprint
+                       evaluateEntry:(BOOL)evaluateEntry
+                        downloadState:(BTDevVendorDownloadState * _Nullable)downloadState;
 @end
 
 @implementation BackgroundReactNativeDelegate
@@ -221,7 +257,18 @@ static NSURL *resolveBundleSourceURL(NSString *jsBundleSourceNS)
 {
   _jsBundleSource = jsBundleSource;
 }
-
+- (void)configureDevVendorCommonBundlePath:(NSString *)commonBundlePath
+                                  entryURL:(NSURL *)entryURL
+                               fingerprint:(NSString *)fingerprint
+                      backgroundHMREnabled:(BOOL)backgroundHMREnabled
+                         runtimeGeneration:(NSUInteger)runtimeGeneration
+{
+  _devVendorCommonBundlePath = [commonBundlePath copy];
+  _devVendorEntryURL = [entryURL copy];
+  _devVendorFingerprint = [fingerprint copy];
+  _devVendorBackgroundHMREnabled = backgroundHMREnabled;
+  _backgroundRuntimeGeneration = runtimeGeneration;
+}
 - (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
 {
   return [self bundleURL];
@@ -232,7 +279,9 @@ static NSURL *resolveBundleSourceURL(NSString *jsBundleSourceNS)
   // Reset on every call so a re-entry (e.g. host restart) can't carry over
   // a stale OTA assertion from a previous load.
   _otaActiveAtBundleResolve = NO;
-
+  if (_devVendorCommonBundlePath.length > 0) {
+    return [NSURL fileURLWithPath:_devVendorCommonBundlePath];
+  }
   // When _jsBundleSource is set (dev mode or explicit override), use it as-is.
   // This is a single full bundle (not split), so DON'T use common+entry strategy.
   if (!_jsBundleSource.empty()) {
@@ -323,7 +372,56 @@ static NSURL *resolveBundleSourceURL(NSString *jsBundleSourceNS)
   if (!_rctInstance) {
     return;
   }
-
+  if (_devVendorEntryURL) {
+    NSURL *entryURL = _devVendorEntryURL;
+    NSString *fingerprint = _devVendorFingerprint;
+    BTDevVendorDownloadState *downloadState = [[BTDevVendorDownloadState alloc] init];
+    [RCTJavaScriptLoader loadBundleAtURL:entryURL
+        onProgress:^(RCTLoadingProgress *progress) { (void)progress; }
+        onComplete:^(NSError *error, RCTSource *source) {
+          downloadState.error = error;
+          downloadState.data = source.data;
+          dispatch_semaphore_signal(downloadState.ready);
+        }];
+    [self finishHostStartWithBundleData:nil
+                               sourceURL:entryURL.absoluteString
+                             fingerprint:fingerprint
+                          evaluateEntry:YES
+                           downloadState:downloadState];
+    if (_devVendorBackgroundHMREnabled) {
+      NSURLComponents *hmrComponents = [NSURLComponents componentsWithURL:entryURL
+                                                   resolvingAgainstBaseURL:NO];
+      hmrComponents.path = @"/apps/mobile/background.bundle";
+      NSURL *hmrRegistrationURL = hmrComponents.URL;
+      if (!hmrRegistrationURL) {
+        [BTLogger error:@"[BackgroundHMR] failed to construct registration URL"];
+        return;
+      }
+      NSString *path = hmrRegistrationURL.path;
+      if ([path hasPrefix:@"/"]) {
+        path = [path substringFromIndex:1];
+      }
+      NSString *scheme = hmrRegistrationURL.scheme ?: @"http";
+      NSNumber *port = hmrRegistrationURL.port ?: @([scheme isEqualToString:@"https"] ? 443 : 80);
+      [host callFunctionOnJSModule:@"HMRClient"
+                           method:@"setup"
+                             args:@[
+                               @"ios",
+                               path ?: @"apps/mobile/background.bundle",
+                               hmrRegistrationURL.host ?: @"127.0.0.1",
+                               port,
+                               @YES,
+                               scheme,
+                               hmrRegistrationURL.absoluteString
+                             ]];
+      [BTLogger info:[NSString stringWithFormat:
+          @"[BackgroundHMR] client setup queued generation=%lu downloadURL=%@ registrationURL=%@",
+          (unsigned long)_backgroundRuntimeGeneration,
+          entryURL.absoluteString,
+          hmrRegistrationURL.absoluteString]];
+    }
+    return;
+  }
   // When _jsBundleSource is set, the bundle loaded in bundleURL was already
   // a full single bundle (dev mode / explicit override), so skip entry loading.
   BOOL isSplitBundle = _jsBundleSource.empty();
@@ -359,49 +457,118 @@ static NSURL *resolveBundleSourceURL(NSString *jsBundleSourceNS)
       [BTLogger warn:@"Background entry bundle not found, __setupBackgroundRPCHandler may not be defined"];
     }
   }
-
+  [self finishHostStartWithBundleData:bgBundleData
+                             sourceURL:bgBundleSourceURL
+                           fingerprint:nil
+                        evaluateEntry:isSplitBundle
+                         downloadState:nil];
+}
+- (void)finishHostStartWithBundleData:(NSData * _Nullable)bundleData
+                            sourceURL:(NSString * _Nullable)sourceURL
+                          fingerprint:(NSString * _Nullable)fingerprint
+                       evaluateEntry:(BOOL)evaluateEntry
+                        downloadState:(BTDevVendorDownloadState * _Nullable)downloadState
+{
+  RCTInstance *instance = _rctInstance;
+  if (!instance) {
+    return;
+  }
   CFAbsoluteTime bgStartTime = CFAbsoluteTimeGetCurrent();
-
-  [_rctInstance callFunctionOnBufferedRuntimeExecutor:[=](jsi::Runtime &runtime) {
-    [self setupErrorHandler:runtime];
-
-    // Install SharedStore into background runtime
-    SharedStore::install(runtime);
-
-    // Install SharedRPC with executor for cross-runtime notifications.
-    // Capture the bg RCTInstance __weak so executor lambdas still in flight
-    // when the bg host is torn down (BackgroundThread.restart mode=all,
-    // OTA bundle install) no-op cleanly instead of dispatching onto a
-    // freed instance and crashing.
-    __weak RCTInstance *weakBgInstance = _rctInstance;
-    RPCRuntimeExecutor bgExecutor = [weakBgInstance](std::function<void(jsi::Runtime &)> work) {
-        RCTInstance *strongBgInstance = weakBgInstance;
-        if (!strongBgInstance) {
-            return;
+  __weak RCTInstance *weakBgInstance = instance;
+
+  [instance callFunctionOnBufferedRuntimeExecutor:[=](jsi::Runtime &runtime) {
+    try {
+      NSData *entryData = bundleData;
+      if (downloadState) {
+        // Queue this executor before the background surface starts. Once the
+        // local common HBC completes, wait for Metro without blocking main.
+        dispatch_time_t deadline = dispatch_time(
+            DISPATCH_TIME_NOW, kDevVendorLoadTimeoutSeconds * NSEC_PER_SEC);
+        if (dispatch_semaphore_wait(downloadState.ready, deadline) != 0) {
+          NSError *timeoutError = [NSError errorWithDomain:@"BackgroundThread"
+                                                      code:21
+                                                  userInfo:@{
+                                                    NSLocalizedDescriptionKey:
+                                                        @"Timed out loading dev-vendor background delta"
+                                                  }];
+          [BTLogger error:@"Dev-vendor background delta timed out after 60 seconds"];
+          dispatch_async(dispatch_get_main_queue(), ^{ RCTFatal(timeoutError); });
+          return;
         }
-        [strongBgInstance callFunctionOnBufferedRuntimeExecutor:[work](jsi::Runtime &rt) {
-            work(rt);
-        }];
-    };
-    SharedRPC::install(runtime, std::move(bgExecutor), "background");
-    [BTLogger info:@"SharedStore and SharedRPC installed in background runtime"];
-
-    // In split-bundle mode, evaluate the background entry bundle now.
-    // This must happen BEFORE invokeOptionalGlobalFunction since the entry
-    // bundle defines __setupBackgroundRPCHandler.
-    if (isSplitBundle && bgBundleData && bgBundleData.length > 0) {
-      CFAbsoluteTime bgEvalStart = CFAbsoluteTimeGetCurrent();
-      auto buffer = std::make_shared<jsi::StringBuffer>(
-        std::string(static_cast<const char *>(bgBundleData.bytes), bgBundleData.length));
-      runtime.evaluateJavaScript(std::move(buffer), [bgBundleSourceURL UTF8String]);
-      double bgEvalMs = (CFAbsoluteTimeGetCurrent() - bgEvalStart) * 1000.0;
-      [BTLogger info:[NSString stringWithFormat:@"[SplitBundle] bg entry evaluated in %.1fms", bgEvalMs]];
+        if (downloadState.error || downloadState.data.length == 0) {
+          NSError *loadError = downloadState.error ?: [NSError errorWithDomain:@"BackgroundThread"
+                                                                           code:20
+                                                                       userInfo:@{
+                                                                         NSLocalizedDescriptionKey:
+                                                                             @"Dev-vendor background delta is empty"
+                                                                       }];
+          [BTLogger error:[NSString stringWithFormat:
+              @"Dev-vendor background delta failed: %@", loadError.localizedDescription]];
+          dispatch_async(dispatch_get_main_queue(), ^{ RCTFatal(loadError); });
+          return;
+        }
+        entryData = downloadState.data;
+      }
+
+      if (fingerprint.length > 0) {
+        jsi::Value marker = runtime.global().getProperty(
+            runtime, "__ONEKEY_DEV_VENDOR_FINGERPRINT__");
+        if (!marker.isString() ||
+            marker.asString(runtime).utf8(runtime) != std::string(fingerprint.UTF8String)) {
+          throw std::runtime_error("Dev-vendor common fingerprint mismatch");
+        }
+        runtime.global().setProperty(
+            runtime,
+            "__ONEKEY_DEV_VENDOR_FULL_BUNDLE_URL__",
+            jsi::String::createFromUtf8(runtime, sourceURL.UTF8String));
+        runtime.global().setProperty(
+            runtime,
+            "__ONEKEY_RUNTIME_TARGET__",
+            jsi::String::createFromUtf8(runtime, "background"));
+        runtime.global().setProperty(
+            runtime,
+            "__ONEKEY_BACKGROUND_RUNTIME_GENERATION__",
+            static_cast<double>(_backgroundRuntimeGeneration));
+      }
+
+      [self setupErrorHandler:runtime];
+      SharedStore::install(runtime);
+
+      RPCRuntimeExecutor bgExecutor = [weakBgInstance](std::function<void(jsi::Runtime &)> work) {
+          RCTInstance *strongBgInstance = weakBgInstance;
+          if (!strongBgInstance) {
+              return;
+          }
+          [strongBgInstance callFunctionOnBufferedRuntimeExecutor:[work](jsi::Runtime &rt) {
+              work(rt);
+          }];
+      };
+      SharedRPC::install(runtime, std::move(bgExecutor), "background");
+      [BTLogger info:@"SharedStore and SharedRPC installed in background runtime"];
+
+      // The entry defines __setupBackgroundRPCHandler, so it must execute
+      // before the runtime is reported ready.
+      if (evaluateEntry && entryData.length > 0 && sourceURL.length > 0) {
+        CFAbsoluteTime bgEvalStart = CFAbsoluteTimeGetCurrent();
+        auto buffer = std::make_shared<BackgroundNSDataJSIBuffer>(entryData);
+        runtime.evaluateJavaScript(buffer, sourceURL.UTF8String);
+        double bgEvalMs = (CFAbsoluteTimeGetCurrent() - bgEvalStart) * 1000.0;
+        [BTLogger info:[NSString stringWithFormat:@"[SplitBundle] bg entry evaluated in %.1fms", bgEvalMs]];
+      }
+
+      double bgTotalMs = (CFAbsoluteTimeGetCurrent() - bgStartTime) * 1000.0;
+      [BTLogger info:[NSString stringWithFormat:@"[SplitBundle] bg hostDidStart total setup in %.1fms", bgTotalMs]];
+      invokeOptionalGlobalFunction(runtime, "__setupBackgroundRPCHandler");
+    } catch (const std::exception &exception) {
+      NSString *message = [NSString stringWithUTF8String:exception.what()];
+      NSError *evaluationError = [NSError errorWithDomain:@"BackgroundThread"
+                                                      code:21
+                                                  userInfo:@{
+                                                    NSLocalizedDescriptionKey:
+                                                        message ?: @"Dev-vendor background evaluation failed"
+                                                  }];
+      dispatch_async(dispatch_get_main_queue(), ^{ RCTFatal(evaluationError); });
     }
-
-    double bgTotalMs = (CFAbsoluteTimeGetCurrent() - bgStartTime) * 1000.0;
-    [BTLogger info:[NSString stringWithFormat:@"[SplitBundle] bg hostDidStart total setup in %.1fms", bgTotalMs]];
-
-    invokeOptionalGlobalFunction(runtime, "__setupBackgroundRPCHandler");
   }];
 }
 

package/ios/BackgroundThreadManager.h

@@ -66,6 +66,20 @@ typedef NS_ENUM(NSInteger, EBgMgrSegmentEvalError) {
 /// @param host The RCTHost for the main runtime
 + (void)installSharedBridgeInMainRuntime:(RCTHost *)host;
 
+/// Install the main-runtime bridge and start the background runtime only after
+/// that installation has executed on the main JS runtime. Expo initializes its
+/// module registry on the JS thread, so this ordered entry point prevents a
+/// second Expo-backed runtime from registering modules during foreground
+/// runtime startup.
+///
+/// @param host The RCTHost for the main runtime
+/// @param entryURL The custom entry URL for the background runner
++ (void)installSharedBridgeInMainRuntime:(RCTHost *)host
+  thenStartBackgroundRunnerWithEntryURL:(NSString *)entryURL;
+/// Install the main-runtime bridge and start a background runtime from a
+/// local common HBC followed by a remote modules-only entry bundle.
++ (void)installSharedBridgeInMainRuntime:(RCTHost *)host
+  thenStartBackgroundRunnerWithDevVendorConfig:(NSDictionary<NSString *, NSString *> *)config;
 /// Start background runner with default entry URL
 - (void)startBackgroundRunner;
 

package/ios/BackgroundThreadManager.mm

@@ -142,7 +142,11 @@ static const NSTimeInterval kBgSegmentEvalWatchdogSeconds = 30.0;
 // same reason as isStarted: written from the caller's thread (public API
 // doesn't pin start... to main) and read on main by the health-check.
 @property (atomic, copy) NSString *lastEntryURL;
-
+// Debug-only dev-vendor bootstrap contract. Retained across mode='all'
+// reloads so the self-heal path cannot fall back to a monolithic bundle.
+@property (atomic, copy, nullable) NSDictionary<NSString *, NSString *> *lastDevVendorConfig;
+@property (nonatomic, assign) NSUInteger backgroundRuntimeGeneration;
+@property (nonatomic, assign) BOOL backgroundHMRRestartInFlight;
 // Forward declaration so restartWithMode: can call it; definition lives
 // after restartWithMode: for readability (the call site is the natural
 // place to start reading the restart flow).
@@ -150,6 +154,11 @@ static const NSTimeInterval kBgSegmentEvalWatchdogSeconds = 30.0;
                                 isAll:(BOOL)isAll
                            generation:(NSUInteger)myGen
                               retried:(BOOL)retried;
+- (void)startBackgroundRunnerWithDevVendorConfig:(NSDictionary<NSString *, NSString *> *)config;
+- (void)startBackgroundRunnerWithEntryURL:(NSString *)entryURL
+                          devVendorConfig:(NSDictionary<NSString *, NSString *> * _Nullable)devVendorConfig;
+- (void)restartBackgroundForHMRReason:(NSString *)reason
+                           completion:(void (^)(NSError * _Nullable error))completion;
 @end
 
 // First-stage delay for the post-reload health-check. Picked so the host's
@@ -164,7 +173,11 @@ static BackgroundThreadManager *_sharedInstance = nil;
 static dispatch_once_t onceToken;
 static NSString *const MODULE_NAME = @"background";
 static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/background.bundle?platform=ios&dev=true&lazy=false&minify=false&inlineSourceMap=false&modulesOnly=false&runModule=true&excludeSource=true&sourcePaths=url-server&app=so.onekey.wallet&transform.routerRoot=app&transform.engine=hermes&transform.bytecode=1&unstable_transformProfile=hermes-stable";
-
+static NSString *const DEV_VENDOR_COMMON_PATH_KEY = @"commonBundlePath";
+static NSString *const DEV_VENDOR_ENTRY_URL_KEY = @"entryURL";
+static NSString *const DEV_VENDOR_FINGERPRINT_KEY = @"fingerprint";
+static NSString *const DEV_VENDOR_BACKGROUND_HMR_KEY = @"backgroundHMREnabled";
+static NSString *const BACKGROUND_HMR_REASON_PREFIX = @"onekey-bg-hmr:";
 #pragma mark - Singleton
 
 + (instancetype)sharedInstance {
@@ -185,7 +198,8 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
 
 #pragma mark - SharedBridge
 
-+ (void)installSharedBridgeInMainRuntime:(RCTHost *)host {
++ (void)installSharedBridgeInMainRuntime:(RCTHost *)host
+                              completion:(dispatch_block_t)completion {
     if (!host) {
         [BTLogger error:@"Cannot install SharedBridge: RCTHost is nil"];
         return;
@@ -209,15 +223,30 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
         // see a nil strong reference and bail out — instead of dispatching
         // callFunctionOnBufferedRuntimeExecutor on a freed instance and
         // crashing (EXC_BAD_ACCESS / use-after-free).
+        __weak RCTHost *weakHost = host;
         __weak id weakInstance = instance;
-        RPCRuntimeExecutor mainExecutor = [weakInstance](std::function<void(jsi::Runtime &)> work) {
-            id strongInstance = weakInstance;
-            if (!strongInstance) {
-                return;
-            }
-            [strongInstance callFunctionOnBufferedRuntimeExecutor:[work](jsi::Runtime &rt) {
-                work(rt);
-            }];
+        RPCRuntimeExecutor mainExecutor = [weakHost, weakInstance](std::function<void(jsi::Runtime &)> work) {
+            // RCTHost invalidates and swaps its RCTInstance on the main queue.
+            // Serialize the identity check with that swap: retaining the old
+            // Objective-C wrapper is not sufficient because its C++
+            // ReactInstance may already have been reset during reload.
+            dispatch_async(dispatch_get_main_queue(), ^{
+                RCTHost *strongHost = weakHost;
+                id strongInstance = weakInstance;
+                if (!strongHost || !strongInstance) {
+                    return;
+                }
+
+                Ivar currentInstanceIvar = class_getInstanceVariable([strongHost class], "_instance");
+                id currentInstance = object_getIvar(strongHost, currentInstanceIvar);
+                if (currentInstance != strongInstance) {
+                    return;
+                }
+
+                [strongInstance callFunctionOnBufferedRuntimeExecutor:[work](jsi::Runtime &rt) {
+                    work(rt);
+                }];
+            });
         };
         SharedRPC::install(runtime, std::move(mainExecutor), "main");
         // Set the integration-health flag from inside the JS-thread lambda so
@@ -225,9 +254,30 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
         // reload observer reads this to detect host hostDidStart: omissions.
         [BackgroundThreadManager sharedInstance].mainSharedBridgeInstalled = YES;
         [BTLogger info:@"SharedStore and SharedRPC installed in main runtime"];
+        if (completion) {
+            completion();
+        }
     }];
 }
 
++ (void)installSharedBridgeInMainRuntime:(RCTHost *)host {
+    [self installSharedBridgeInMainRuntime:host completion:nil];
+}
+
++ (void)installSharedBridgeInMainRuntime:(RCTHost *)host
+  thenStartBackgroundRunnerWithEntryURL:(NSString *)entryURL {
+    [self installSharedBridgeInMainRuntime:host completion:^{
+        [[BackgroundThreadManager sharedInstance]
+            startBackgroundRunnerWithEntryURL:entryURL];
+    }];
+}
++ (void)installSharedBridgeInMainRuntime:(RCTHost *)host
+  thenStartBackgroundRunnerWithDevVendorConfig:(NSDictionary<NSString *, NSString *> *)config {
+    [self installSharedBridgeInMainRuntime:host completion:^{
+        [[BackgroundThreadManager sharedInstance]
+            startBackgroundRunnerWithDevVendorConfig:config];
+    }];
+}
 #pragma mark - Public Methods
 
 - (void)startBackgroundRunner {
@@ -240,6 +290,35 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
 }
 
 - (void)startBackgroundRunnerWithEntryURL:(NSString *)entryURL {
+    [self startBackgroundRunnerWithEntryURL:entryURL devVendorConfig:nil];
+}
+
+- (void)startBackgroundRunnerWithDevVendorConfig:(NSDictionary<NSString *, NSString *> *)config {
+    NSString *commonBundlePath = config[DEV_VENDOR_COMMON_PATH_KEY];
+    NSString *entryURL = config[DEV_VENDOR_ENTRY_URL_KEY];
+    NSString *fingerprint = config[DEV_VENDOR_FINGERPRINT_KEY];
+    NSString *backgroundHMRValue = config[DEV_VENDOR_BACKGROUND_HMR_KEY];
+    NSURL *parsedEntryURL = [NSURL URLWithString:entryURL];
+    NSRegularExpression *fingerprintPattern =
+        [NSRegularExpression regularExpressionWithPattern:@"^[0-9a-f]{64}$"
+                                                  options:0
+                                                    error:nil];
+    if (commonBundlePath.length == 0 ||
+        ![[NSFileManager defaultManager] fileExistsAtPath:commonBundlePath] ||
+        parsedEntryURL.host.length == 0 ||
+        !([backgroundHMRValue isEqualToString:@"true"] ||
+          [backgroundHMRValue isEqualToString:@"false"]) ||
+        [fingerprintPattern numberOfMatchesInString:fingerprint
+                                            options:0
+                                              range:NSMakeRange(0, fingerprint.length)] != 1) {
+        [BTLogger error:@"Invalid dev-vendor background bootstrap config"];
+        return;
+    }
+    [self startBackgroundRunnerWithEntryURL:entryURL devVendorConfig:config];
+}
+
+- (void)startBackgroundRunnerWithEntryURL:(NSString *)entryURL
+                          devVendorConfig:(NSDictionary<NSString *, NSString *> * _Nullable)devVendorConfig {
     if (self.isStarted) {
         // Surface the URL mismatch when a second start... call would
         // otherwise silently drop the host's intent — most common in the
@@ -262,18 +341,27 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
     // Updated unconditionally — first-time and re-start with a new URL
     // both reflect into lastEntryURL.
     self.lastEntryURL = entryURL;
+    self.lastDevVendorConfig = devVendorConfig;
     [BTLogger info:[NSString stringWithFormat:@"Starting background runner with entryURL: %@", entryURL]];
 
     dispatch_async(dispatch_get_main_queue(), ^{
+        NSUInteger runtimeGeneration = ++self.backgroundRuntimeGeneration;
         NSDictionary *initialProperties = @{};
         NSDictionary *launchOptions = @{};
         self.reactNativeFactoryDelegate = [[BackgroundReactNativeDelegate alloc] init];
         self.reactNativeFactory = CreateBackgroundReactNativeFactory(self.reactNativeFactoryDelegate);
-
+        if (devVendorConfig) {
+            [self.reactNativeFactoryDelegate
+                configureDevVendorCommonBundlePath:devVendorConfig[DEV_VENDOR_COMMON_PATH_KEY]
+                entryURL:[NSURL URLWithString:devVendorConfig[DEV_VENDOR_ENTRY_URL_KEY]]
+                fingerprint:devVendorConfig[DEV_VENDOR_FINGERPRINT_KEY]
+                backgroundHMREnabled:[devVendorConfig[DEV_VENDOR_BACKGROUND_HMR_KEY] isEqualToString:@"true"]
+                runtimeGeneration:runtimeGeneration];
+        }
         // 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.bundle + entry).
-        if (![entryURL isEqualToString:@"background.bundle"]) {
+        if (!devVendorConfig && ![entryURL isEqualToString:@"background.bundle"]) {
             [self.reactNativeFactoryDelegate setJsBundleSource:std::string([entryURL UTF8String])];
         }
 
@@ -460,6 +548,20 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
 {
     BOOL isUI = [mode isEqualToString:@"ui"];
     BOOL isAll = [mode isEqualToString:@"all"];
+    BOOL isBackgroundHMR = [mode isEqualToString:@"background"];
+
+    if (isBackgroundHMR) {
+#if DEBUG
+        [self restartBackgroundForHMRReason:reason completion:completion];
+#else
+        NSError *error = [NSError errorWithDomain:@"BackgroundThread"
+                                             code:12
+                                         userInfo:@{NSLocalizedDescriptionKey:
+                                                        @"Background HMR restart is unavailable in release builds"}];
+        if (completion) completion(error);
+#endif
+        return;
+    }
 
     if (!isUI && !isAll) {
         NSError *error = [NSError errorWithDomain:@"BackgroundThread"
@@ -536,6 +638,59 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
     }
 }
 
+- (void)restartBackgroundForHMRReason:(NSString *)reason
+                           completion:(void (^)(NSError * _Nullable error))completion
+{
+    dispatch_async(dispatch_get_main_queue(), ^{
+        if (![reason hasPrefix:BACKGROUND_HMR_REASON_PREFIX]) {
+            NSError *error = [NSError errorWithDomain:@"BackgroundThread"
+                                                 code:13
+                                             userInfo:@{NSLocalizedDescriptionKey:
+                                                            @"Background HMR restart is missing its runtime generation"}];
+            if (completion) completion(error);
+            return;
+        }
+        NSString *generationAndReason = [reason substringFromIndex:BACKGROUND_HMR_REASON_PREFIX.length];
+        NSRange separator = [generationAndReason rangeOfString:@":"];
+        NSString *generationText = separator.location == NSNotFound
+            ? generationAndReason
+            : [generationAndReason substringToIndex:separator.location];
+        NSScanner *scanner = [NSScanner scannerWithString:generationText];
+        unsigned long long generation = 0;
+        if (![scanner scanUnsignedLongLong:&generation] || !scanner.isAtEnd ||
+            generation != self.backgroundRuntimeGeneration) {
+            [BTLogger info:[NSString stringWithFormat:
+                @"[BackgroundHMR] ignored stale restart requested=%@ active=%lu",
+                generationText,
+                (unsigned long)self.backgroundRuntimeGeneration]];
+            if (completion) completion(nil);
+            return;
+        }
+        NSDictionary<NSString *, NSString *> *config = self.lastDevVendorConfig;
+        if (![config[DEV_VENDOR_BACKGROUND_HMR_KEY] isEqualToString:@"true"] ||
+            self.backgroundHMRRestartInFlight) {
+            [BTLogger info:@"[BackgroundHMR] restart coalesced or disabled"];
+            if (completion) completion(nil);
+            return;
+        }
+
+        self.backgroundHMRRestartInFlight = YES;
+        ++self.backgroundRuntimeGeneration;
+        SharedRPC::invalidate("background");
+        self.reactNativeFactory = nil;
+        self.reactNativeFactoryDelegate = nil;
+        self.isStarted = NO;
+        if (completion) completion(nil);
+
+        // Leave the outgoing TurboModule callback before creating its replacement.
+        dispatch_async(dispatch_get_main_queue(), ^{
+            [BTLogger info:@"[BackgroundHMR] starting replacement background runtime"];
+            [self startBackgroundRunnerWithDevVendorConfig:config];
+            self.backgroundHMRRestartInFlight = NO;
+        });
+    });
+}
+
 #pragma mark - Restart Health Check
 
 // Two-stage post-reload health-check.
@@ -618,6 +773,7 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
 
         if (isAll && !strongSelf.isStarted) {
             NSString *cachedURL = strongSelf.lastEntryURL;
+            NSDictionary<NSString *, NSString *> *devVendorConfig = strongSelf.lastDevVendorConfig;
             // Treat the bundled default name as "no real cache" so the
             // OTA warn still fires for hosts that initially bootstrapped
             // with the default URL and haven't yet swapped to an OTA-
@@ -625,7 +781,12 @@ static NSString *const MODULE_DEBUG_URL = @"http://localhost:8082/apps/mobile/ba
             // lastEntryURL that distinguishes them.
             BOOL hasCustomCachedURL = cachedURL.length > 0
                 && ![cachedURL isEqualToString:@"background.bundle"];
-            if (hasCustomCachedURL) {
+            if (devVendorConfig) {
+                [BTLogger info:[NSString stringWithFormat:
+                    @"restart(%@): bg not respawned by host AppDelegate; replaying dev-vendor common + delta",
+                    mode]];
+                [strongSelf startBackgroundRunnerWithDevVendorConfig:devVendorConfig];
+            } else if (hasCustomCachedURL) {
                 // Preferred path: replay the host's last entry URL. On OTA
                 // devices this is the OTA-resolved bundle, which keeps the
                 // bg moduleId table aligned with the new main bundle and

package/package.json

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