@granite-js/micro-frontend 2.0.0

package/ios/GraniteMicroFrontendRuntimeHost.mm

@@ -0,0 +1,485 @@
+#import "GraniteMicroFrontendRuntimeHost+Internal.h"
+#import <objc/runtime.h>
+#import <TargetConditionals.h>
+
+#if TARGET_OS_IOS || TARGET_OS_TV
+#import <UIKit/UIKit.h>
+#define GRANITE_MICRO_FRONTEND_HAS_UIKIT 1
+#else
+#define GRANITE_MICRO_FRONTEND_HAS_UIKIT 0
+#endif
+
+@class GraniteMicroFrontendSessionEntry;
+
+static NSRecursiveLock *runtimeLock;
+static NSMutableDictionary<NSString *, GraniteMicroFrontendSessionEntry *> *sessions;
+static NSMutableArray<NSDictionary *> *pendingEvents;
+static __weak id<GraniteMicroFrontendRuntimeEventSink> eventSink;
+static BOOL isDeliveringEvents;
+
+static void GraniteMicroFrontendRequireMainThread(void) {
+  if (!NSThread.isMainThread) {
+    @throw [NSException exceptionWithName:NSInternalInconsistencyException
+                                   reason:@"Session bindings must be used on the main thread"
+                                 userInfo:nil];
+  }
+}
+
+@interface GraniteMicroFrontendSessionEntry : NSObject
+@property(nonatomic, copy) NSString *token;
+@property(nonatomic, assign) BOOL opened;
+@property(nonatomic, assign) BOOL isVisible;
+@property(nonatomic, assign) BOOL closed;
+@end
+
+@implementation GraniteMicroFrontendSessionEntry
+@end
+
+@interface GraniteMicroFrontendSessionRegistration ()
+@property(nonatomic, copy) NSString *sessionId;
+@property(nonatomic, copy) NSString *token;
+@property(nonatomic, assign) BOOL invalidated;
+@end
+
+@class GraniteMicroFrontendSessionLifecycleObserverViewController;
+
+#if GRANITE_MICRO_FRONTEND_HAS_UIKIT
+@interface GraniteMicroFrontendViewControllerSessionBinding ()
+@property(nonatomic, weak) UIViewController *viewController;
+@property(nonatomic, strong) GraniteMicroFrontendSessionRegistration *registration;
+@property(nonatomic, strong) GraniteMicroFrontendSessionLifecycleObserverViewController *observer;
+@property(nonatomic, assign) BOOL viewAppeared;
+@property(nonatomic, assign) BOOL applicationForeground;
+@property(nonatomic, assign) BOOL invalidated;
+- (void)updateVisibility;
+@end
+#endif
+
+@interface GraniteMicroFrontendRuntimeHost ()
++ (void)drainEventsToSink:(id<GraniteMicroFrontendRuntimeEventSink>)sink;
+@end
+
+@implementation GraniteMicroFrontendSessionRegistration
+
+- (void)openAppWithAppName:(NSString *)appName scheme:(NSString *)scheme {
+  NSParameterAssert(appName.length > 0);
+  NSParameterAssert(scheme.length > 0);
+  BOOL shouldEmit = NO;
+  [runtimeLock lock];
+  @try {
+    GraniteMicroFrontendSessionEntry *entry = sessions[_sessionId];
+    if ([entry.token isEqualToString:_token] && !entry.opened && !entry.closed) {
+      entry.opened = YES;
+      shouldEmit = YES;
+    }
+  } @finally {
+    [runtimeLock unlock];
+  }
+  if (shouldEmit) {
+    [GraniteMicroFrontendRuntimeHost emitOpenApp:_sessionId appName:appName scheme:scheme];
+  }
+}
+
+- (BOOL)setVisible:(BOOL)isVisible {
+  BOOL shouldEmit = NO;
+  [runtimeLock lock];
+  @try {
+    GraniteMicroFrontendSessionEntry *entry = sessions[_sessionId];
+    if ([entry.token isEqualToString:_token] && entry.opened && !entry.closed &&
+        entry.isVisible != isVisible) {
+      entry.isVisible = isVisible;
+      shouldEmit = YES;
+    }
+  } @finally {
+    [runtimeLock unlock];
+  }
+  if (shouldEmit) {
+    [GraniteMicroFrontendRuntimeHost emitSessionVisibilityChanged:_sessionId
+                                                        isVisible:isVisible];
+  }
+  return shouldEmit;
+}
+
+- (BOOL)closeApp {
+  BOOL shouldEmit = NO;
+  [runtimeLock lock];
+  @try {
+    GraniteMicroFrontendSessionEntry *entry = sessions[_sessionId];
+    if ([entry.token isEqualToString:_token] && entry.opened && !entry.closed) {
+      entry.closed = YES;
+      shouldEmit = YES;
+    }
+  } @finally {
+    [runtimeLock unlock];
+  }
+  if (shouldEmit) {
+    [GraniteMicroFrontendRuntimeHost emitCloseApp:_sessionId];
+  }
+  return shouldEmit;
+}
+
+- (void)invalidate {
+  @synchronized(self) {
+    if (_invalidated) {
+      return;
+    }
+    _invalidated = YES;
+  }
+  [GraniteMicroFrontendRuntimeHost unregisterSession:_sessionId token:_token];
+}
+
+- (void)dealloc {
+  [self invalidate];
+}
+
+@end
+
+#if GRANITE_MICRO_FRONTEND_HAS_UIKIT
+
+@interface GraniteMicroFrontendSessionLifecycleObserverViewController : UIViewController
+@property(nonatomic, weak) GraniteMicroFrontendViewControllerSessionBinding *binding;
+@end
+
+@implementation GraniteMicroFrontendSessionLifecycleObserverViewController
+
+- (void)viewWillAppear:(BOOL)animated {
+  [super viewWillAppear:animated];
+  _binding.viewAppeared = YES;
+}
+
+- (void)viewWillDisappear:(BOOL)animated {
+  _binding.viewAppeared = NO;
+  [super viewWillDisappear:animated];
+}
+
+- (void)dealloc {
+  [_binding invalidate];
+}
+
+@end
+
+@implementation GraniteMicroFrontendViewControllerSessionBinding
+
+static char GraniteMicroFrontendViewControllerSessionBindingKey;
+
++ (nullable GraniteMicroFrontendViewControllerSessionBinding *)bindViewController:(UIViewController *)viewController
+                                                                        sessionId:(NSString *)sessionId
+                                                                          appName:(NSString *)appName
+                                                                           scheme:(NSString *)scheme {
+  GraniteMicroFrontendRequireMainThread();
+  NSParameterAssert(viewController != nil);
+  NSParameterAssert(sessionId.length > 0);
+  NSParameterAssert(appName.length > 0);
+  NSParameterAssert(scheme.length > 0);
+
+  GraniteMicroFrontendViewControllerSessionBinding *existingBinding =
+      objc_getAssociatedObject(viewController, &GraniteMicroFrontendViewControllerSessionBindingKey);
+  if (existingBinding != nil) {
+    return existingBinding;
+  }
+
+  GraniteMicroFrontendSessionRegistration *registration =
+      [GraniteMicroFrontendRuntimeHost registerSession:sessionId];
+  if (registration == nil) {
+    return nil;
+  }
+  GraniteMicroFrontendViewControllerSessionBinding *binding =
+      [[GraniteMicroFrontendViewControllerSessionBinding alloc] init];
+  GraniteMicroFrontendSessionLifecycleObserverViewController *observer =
+      [[GraniteMicroFrontendSessionLifecycleObserverViewController alloc] init];
+  observer.binding = binding;
+  binding.viewController = viewController;
+  binding.registration = registration;
+  binding.observer = observer;
+  binding.applicationForeground =
+      UIApplication.sharedApplication.applicationState != UIApplicationStateBackground;
+
+  [NSNotificationCenter.defaultCenter addObserver:binding
+                                         selector:@selector(applicationWillEnterForeground)
+                                             name:UIApplicationWillEnterForegroundNotification
+                                           object:nil];
+  [NSNotificationCenter.defaultCenter addObserver:binding
+                                         selector:@selector(applicationDidEnterBackground)
+                                             name:UIApplicationDidEnterBackgroundNotification
+                                           object:nil];
+
+  [viewController addChildViewController:observer];
+  observer.view.hidden = YES;
+  observer.view.frame = CGRectZero;
+  observer.view.userInteractionEnabled = NO;
+  [viewController.view addSubview:observer.view];
+  [observer didMoveToParentViewController:viewController];
+
+  objc_setAssociatedObject(
+      viewController,
+      &GraniteMicroFrontendViewControllerSessionBindingKey,
+      binding,
+      OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+  [registration openAppWithAppName:appName scheme:scheme];
+  [binding updateVisibility];
+  return binding;
+}
+
+- (void)setViewAppeared:(BOOL)viewAppeared {
+  if (_viewAppeared == viewAppeared) {
+    return;
+  }
+  _viewAppeared = viewAppeared;
+  [self updateVisibility];
+}
+
+- (void)setApplicationForeground:(BOOL)applicationForeground {
+  if (_applicationForeground == applicationForeground) {
+    return;
+  }
+  _applicationForeground = applicationForeground;
+  [self updateVisibility];
+}
+
+- (void)applicationWillEnterForeground {
+  self.applicationForeground = YES;
+}
+
+- (void)applicationDidEnterBackground {
+  self.applicationForeground = NO;
+}
+
+- (void)updateVisibility {
+  GraniteMicroFrontendRequireMainThread();
+  BOOL invalidated = NO;
+  @synchronized(self) {
+    invalidated = _invalidated;
+  }
+  if (invalidated) {
+    return;
+  }
+  [_registration setVisible:(_viewAppeared && _applicationForeground)];
+}
+
+- (void)invalidate {
+  GraniteMicroFrontendRequireMainThread();
+  @synchronized(self) {
+    if (_invalidated) {
+      return;
+    }
+    _invalidated = YES;
+  }
+
+  [NSNotificationCenter.defaultCenter removeObserver:self
+                                                name:UIApplicationWillEnterForegroundNotification
+                                              object:nil];
+  [NSNotificationCenter.defaultCenter removeObserver:self
+                                                name:UIApplicationDidEnterBackgroundNotification
+                                              object:nil];
+
+  UIViewController *viewController = _viewController;
+  _observer.binding = nil;
+  if (_observer.parentViewController != nil) {
+    [_observer willMoveToParentViewController:nil];
+    [_observer.view removeFromSuperview];
+    [_observer removeFromParentViewController];
+  }
+  [_registration closeApp];
+  [_registration invalidate];
+  if (viewController != nil &&
+      objc_getAssociatedObject(viewController, &GraniteMicroFrontendViewControllerSessionBindingKey) == self) {
+    objc_setAssociatedObject(
+        viewController,
+        &GraniteMicroFrontendViewControllerSessionBindingKey,
+        nil,
+        OBJC_ASSOCIATION_ASSIGN);
+  }
+}
+
+- (void)dealloc {
+  [self invalidate];
+}
+
+@end
+
+#else
+
+@implementation GraniteMicroFrontendViewControllerSessionBinding
+
++ (nullable GraniteMicroFrontendViewControllerSessionBinding *)bindViewController:(UIViewController *)viewController
+                                                                        sessionId:(NSString *)sessionId
+                                                                          appName:(NSString *)appName
+                                                                           scheme:(NSString *)scheme {
+  NSParameterAssert(NO);
+  return nil;
+}
+
+- (void)invalidate {
+}
+
+@end
+
+#endif
+
+@implementation GraniteMicroFrontendRuntimeHost
+
++ (void)initialize {
+  if (self != GraniteMicroFrontendRuntimeHost.class) {
+    return;
+  }
+  runtimeLock = [[NSRecursiveLock alloc] init];
+  sessions = [[NSMutableDictionary alloc] init];
+  pendingEvents = [[NSMutableArray alloc] init];
+}
+
++ (nullable GraniteMicroFrontendSessionRegistration *)registerSession:(NSString *)sessionId {
+  NSParameterAssert(sessionId.length > 0);
+
+  NSString *token = NSUUID.UUID.UUIDString;
+  GraniteMicroFrontendSessionEntry *entry = [[GraniteMicroFrontendSessionEntry alloc] init];
+  entry.token = token;
+
+  [runtimeLock lock];
+  if (sessions[sessionId] != nil) {
+    [runtimeLock unlock];
+    // Do not throw: Swift cannot catch NSException and a reuse race during
+    // VC teardown would crash the host. Callers must use unique sessionIds and
+    // invalidate the previous registration before reusing an id.
+    return nil;
+  }
+  sessions[sessionId] = entry;
+  [runtimeLock unlock];
+
+  GraniteMicroFrontendSessionRegistration *registration =
+      [[GraniteMicroFrontendSessionRegistration alloc] init];
+  registration.sessionId = sessionId;
+  registration.token = token;
+  return registration;
+}
+
++ (void)emitPreloadApp:(NSString *)appName {
+  [self emitEvent:@{ @"name" : @"preloadApp", @"params" : @{ @"appName" : appName } }];
+}
+
++ (void)emitOpenApp:(NSString *)sessionId
+             appName:(NSString *)appName
+              scheme:(NSString *)scheme {
+  [self emitEvent:@{
+    @"name" : @"openApp",
+    @"params" : @{
+      @"sessionId" : sessionId,
+      @"appName" : appName,
+      @"scheme" : scheme,
+    },
+  }];
+}
+
++ (void)emitCloseApp:(NSString *)sessionId {
+  [self emitEvent:@{ @"name" : @"closeApp", @"params" : @{ @"sessionId" : sessionId } }];
+}
+
++ (void)emitSessionVisibilityChanged:(NSString *)sessionId
+                           isVisible:(BOOL)isVisible {
+  [self emitEvent:@{
+    @"name" : @"sessionVisibilityChanged",
+    @"params" : @{
+      @"sessionId" : sessionId,
+      @"isVisible" : @(isVisible),
+    },
+  }];
+}
+
++ (void)emitEvent:(NSDictionary *)event {
+  [runtimeLock lock];
+  [pendingEvents addObject:event];
+  id<GraniteMicroFrontendRuntimeEventSink> sink = eventSink;
+  BOOL shouldDrain = sink != nil && !isDeliveringEvents;
+  if (shouldDrain) {
+    isDeliveringEvents = YES;
+  }
+  [runtimeLock unlock];
+  if (shouldDrain) {
+    [self drainEventsToSink:sink];
+  }
+}
+
++ (void)startEventDeliveryToEventSink:(id<GraniteMicroFrontendRuntimeEventSink>)sink {
+  [runtimeLock lock];
+  if (eventSink != nil && eventSink != sink) {
+    [runtimeLock unlock];
+    return;
+  }
+  eventSink = sink;
+  BOOL shouldDrain = !isDeliveringEvents && pendingEvents.count > 0;
+  if (shouldDrain) {
+    isDeliveringEvents = YES;
+  }
+  [runtimeLock unlock];
+  if (shouldDrain) {
+    [self drainEventsToSink:sink];
+  }
+}
+
++ (void)drainEventsToSink:(id<GraniteMicroFrontendRuntimeEventSink>)sink {
+  id<GraniteMicroFrontendRuntimeEventSink> currentSink = sink;
+  while (YES) {
+    [runtimeLock lock];
+    id<GraniteMicroFrontendRuntimeEventSink> activeSink = eventSink;
+    if (activeSink == nil || pendingEvents.count == 0) {
+      isDeliveringEvents = NO;
+      [runtimeLock unlock];
+      return;
+    }
+    currentSink = activeSink;
+    NSDictionary *event = pendingEvents.firstObject;
+    [runtimeLock unlock];
+
+    @try {
+      if (![currentSink enqueueRuntimeEvent:event]) {
+        [runtimeLock lock];
+        isDeliveringEvents = NO;
+        id<GraniteMicroFrontendRuntimeEventSink> replacementSink = eventSink;
+        BOOL shouldResumeWithReplacement =
+            replacementSink != nil && replacementSink != currentSink && pendingEvents.count > 0;
+        if (shouldResumeWithReplacement) {
+          isDeliveringEvents = YES;
+        }
+        [runtimeLock unlock];
+        if (shouldResumeWithReplacement) {
+          [self drainEventsToSink:replacementSink];
+        }
+        return;
+      }
+      [runtimeLock lock];
+      [pendingEvents removeObjectAtIndex:0];
+      [runtimeLock unlock];
+    } @catch (NSException *exception) {
+      [runtimeLock lock];
+      isDeliveringEvents = NO;
+      id<GraniteMicroFrontendRuntimeEventSink> replacementSink = eventSink;
+      BOOL shouldResumeWithReplacement =
+          replacementSink != nil && replacementSink != currentSink && pendingEvents.count > 0;
+      if (shouldResumeWithReplacement) {
+        isDeliveringEvents = YES;
+      }
+      [runtimeLock unlock];
+      if (shouldResumeWithReplacement) {
+        [self drainEventsToSink:replacementSink];
+      }
+      @throw exception;
+    }
+  }
+}
+
++ (void)detachEventSink:(id<GraniteMicroFrontendRuntimeEventSink>)sink {
+  [runtimeLock lock];
+  if (eventSink == sink) {
+    eventSink = nil;
+  }
+  [runtimeLock unlock];
+}
+
++ (void)unregisterSession:(NSString *)sessionId token:(NSString *)token {
+  [runtimeLock lock];
+  if ([sessions[sessionId].token isEqualToString:token]) {
+    [sessions removeObjectForKey:sessionId];
+  }
+  [runtimeLock unlock];
+}
+
+@end

package/ios/GraniteMicroFrontendRuntimeModule.h

@@ -0,0 +1,6 @@
+#import <GraniteMicroFrontendRuntimeSpec/GraniteMicroFrontendRuntimeSpec.h>
+#import <React/RCTBridgeModule.h>
+
+@interface GraniteMicroFrontendRuntimeModule
+    : NativeGraniteMicroFrontendRuntimeSpecBase <NativeGraniteMicroFrontendRuntimeSpec>
+@end

package/ios/GraniteMicroFrontendRuntimeModule.mm

@@ -0,0 +1,138 @@
+#import "GraniteMicroFrontendRuntimeModule.h"
+
+#import "GraniteMicroFrontendRuntimeHost+Internal.h"
+#import <React/RCTBridge.h>
+#import <React/RCTBridgeProxy+Cxx.h>
+#import <React-callinvoker/ReactCommon/CallInvoker.h>
+#import <jsi/jsi.h>
+
+static NSString *const GraniteMicroFrontendRuntimeErrorDomain =
+    @"GraniteMicroFrontendRuntime";
+
+@interface RCTBridge (GraniteMicroFrontendRuntime)
+- (void *)runtime;
+- (std::shared_ptr<facebook::react::CallInvoker>)jsCallInvoker;
+@end
+
+@interface GraniteMicroFrontendRuntimeModule () <GraniteMicroFrontendRuntimeEventSink>
+@property(nonatomic, weak) RCTBridge *bridge;
+- (BOOL)scheduleRuntimeEvent:(NSDictionary *)event;
+@end
+
+@implementation GraniteMicroFrontendRuntimeModule
+
+RCT_EXPORT_MODULE(GraniteMicroFrontendRuntime)
+
++ (BOOL)requiresMainQueueSetup {
+  return NO;
+}
+
+- (void)dealloc {
+  [GraniteMicroFrontendRuntimeHost detachEventSink:self];
+}
+
+- (std::shared_ptr<facebook::react::CallInvoker>)jsCallInvokerIfAvailable {
+  RCTBridge *bridge = self.bridge;
+  if (bridge == nil) {
+    return nullptr;
+  }
+  // Prefer the public CallInvoker on RCTBridge / bridge proxy without casting
+  // to a concrete bridge subclass.
+  return bridge.jsCallInvoker;
+}
+
+- (facebook::jsi::Runtime *)jsRuntimeIfAvailable {
+  RCTBridge *bridge = self.bridge;
+  if (bridge == nil || ![bridge respondsToSelector:@selector(runtime)]) {
+    return nullptr;
+  }
+  return reinterpret_cast<facebook::jsi::Runtime *>(bridge.runtime);
+}
+
+- (void)evaluateScript:(JS::NativeGraniteMicroFrontendRuntime::EvaluateScriptRequest &)request
+               resolve:(RCTPromiseResolveBlock)resolve
+                reject:(RCTPromiseRejectBlock)reject {
+  NSString *filePath = request.filePath();
+  if (![filePath isAbsolutePath]) {
+    reject(@"INVALID_BUNDLE_PATH", @"Bundle path must be absolute", nil);
+    return;
+  }
+
+  __weak GraniteMicroFrontendRuntimeModule *weakSelf = self;
+  dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+    NSError *readError = nil;
+    NSData *scriptData = [NSData dataWithContentsOfFile:filePath
+                                               options:NSDataReadingMappedIfSafe
+                                                 error:&readError];
+    if (scriptData == nil) {
+      reject(@"BUNDLE_READ_FAILED", readError.localizedDescription, readError);
+      return;
+    }
+
+    std::string source{static_cast<const char *>(scriptData.bytes), scriptData.length};
+    std::string sourceUrl{[NSURL fileURLWithPath:filePath].absoluteString.UTF8String};
+    GraniteMicroFrontendRuntimeModule *strongSelf = weakSelf;
+    if (strongSelf == nil) {
+      reject(@"RUNTIME_UNAVAILABLE", @"JavaScript runtime is unavailable", nil);
+      return;
+    }
+
+    std::shared_ptr<facebook::react::CallInvoker> callInvoker =
+        [strongSelf jsCallInvokerIfAvailable];
+    if (callInvoker == nullptr) {
+      reject(@"RUNTIME_UNAVAILABLE", @"JavaScript runtime is unavailable", nil);
+      return;
+    }
+
+    // Read the JSI runtime only on the JS queue owned by callInvoker.
+    callInvoker->invokeAsync([strongSelf,
+                              source = std::move(source),
+                              sourceUrl = std::move(sourceUrl),
+                              resolve,
+                              reject]() mutable {
+      facebook::jsi::Runtime *runtime = [strongSelf jsRuntimeIfAvailable];
+      if (runtime == nullptr) {
+        reject(@"RUNTIME_UNAVAILABLE", @"JavaScript runtime is unavailable", nil);
+        return;
+      }
+      try {
+        runtime->evaluateJavaScript(
+            std::make_unique<facebook::jsi::StringBuffer>(std::move(source)),
+            sourceUrl);
+        resolve(nil);
+      } catch (const std::exception &exception) {
+        NSString *message = [NSString stringWithUTF8String:exception.what()];
+        NSError *error = [NSError errorWithDomain:GraniteMicroFrontendRuntimeErrorDomain
+                                             code:500
+                                         userInfo:@{ NSLocalizedDescriptionKey : message }];
+        reject(@"EVALUATE_SCRIPT_FAILED", message, error);
+      }
+    });
+  });
+}
+
+- (void)startEventDelivery {
+  [GraniteMicroFrontendRuntimeHost startEventDeliveryToEventSink:self];
+}
+
+- (BOOL)enqueueRuntimeEvent:(NSDictionary *)event {
+  return [self scheduleRuntimeEvent:event];
+}
+
+- (BOOL)scheduleRuntimeEvent:(NSDictionary *)event {
+  std::shared_ptr<facebook::react::CallInvoker> callInvoker = [self jsCallInvokerIfAvailable];
+  if (callInvoker == nullptr) {
+    return NO;
+  }
+  callInvoker->invokeAsync([self, event] {
+    [self emitOnEvent:event];
+  });
+  return YES;
+}
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params {
+  return std::make_shared<facebook::react::NativeGraniteMicroFrontendRuntimeSpecJSI>(params);
+}
+
+@end

package/ios/PortalHostContainerView.h

@@ -0,0 +1,56 @@
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// UIKit-owned container for hosting teleported portal content outside the
+/// React tree. This header intentionally imports UIKit only, so native
+/// integrations can include it in build configurations where the React
+/// renderer headers are unavailable (e.g. prebuilt React distributions).
+@interface PortalHostContainerView : UIView
+
+/// Creates a container that activates immediately (see `-activateIfNeeded`).
+- (instancetype)initWithFrame:(CGRect)frame;
+
+/// Creates a container that postpones creating the underlying Fabric host
+/// view until `-activateIfNeeded` is called.
+///
+/// Deferred activation exists because constructing the host view runs
+/// `RCTViewComponentView` initialization, which reads ReactNativeFeatureFlags.
+/// React only allows overriding those flags before their first read, so a
+/// container created before the app's React factory has booted (a parked
+/// native destination, for example) would otherwise make the boot-time
+/// override throw. Defer activation and call `-activateIfNeeded` once the
+/// runtime is up — typically right before asking React to mount content.
+- (instancetype)initWithFrame:(CGRect)frame deferredActivation:(BOOL)deferredActivation;
+
+/// Registers the container under `name` so `<Portal hostName={name}>` content
+/// teleports into it. Safe to call before activation; the name is applied
+/// when the host view is created. Pass nil to unregister.
+- (void)setName:(nullable NSString *)name;
+
+/// Creates the underlying Fabric host view, attaches the touch handler, and
+/// applies any pending name. No-op when already activated. Must be called on
+/// the main thread after the React runtime has booted.
+- (void)activateIfNeeded;
+
+/// Whether the underlying Fabric host view has been created.
+@property (nonatomic, readonly) BOOL isActivated;
+
+/// Whether any teleported content view is currently attached.
+@property (nonatomic, readonly) BOOL hasAttachedContent;
+
+/// Called on the main thread when the first content view attaches.
+@property (nonatomic, copy, nullable) void (^onContentDidAttach)(void);
+
+/// Called on the main thread when the last content view detaches. Transient
+/// remove-and-reinsert churn within one mount commit is re-checked on the
+/// next run loop before this fires.
+@property (nonatomic, copy, nullable) void (^onContentDidDetach)(void);
+
+/// Unregisters the host and clears lifecycle callbacks. Call when the owning
+/// screen is torn down; the container stops receiving teleported content.
+- (void)invalidate;
+
+@end
+
+NS_ASSUME_NONNULL_END