@everframe/react-native 0.9.0

package/ios/Sources/EverframeModule.mm

@@ -0,0 +1,489 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 ScriptX
+//
+// ObjC++ TurboModule for @everframe/react-native (iOS). Conforms to the
+// codegen-generated `NativeEverframeSpec` protocol; all method bodies dispatch
+// to the Swift glue layer (`EverframeBridge` in `EverframeBridge.swift`).
+//
+// Threading (RESEARCH §2.5):
+//   • configure              — JS thread (synchronous; <5ms per sdk-ios contract)
+//   • captureNow             — main queue (UIKit reads, capture, accessibility walk)
+//   • registerSensitiveRect  — main queue (RCTUIManager view lookup)
+//   • submit                 — background OK (no UIKit reads); bridge runs it
+//                              on a detached Task internally
+//   • openAnnotationOverlay  — main queue (UI presentation)
+//
+// JS-side name binding: `RCT_EXPORT_MODULE(Everframe)` registers under the
+// name 'Everframe', matching `TurboModuleRegistry.getEnforcing<Spec>('Everframe')`
+// in `src/NativeEverframe.ts`.
+#import "EverframeModule.h"
+
+#import <React/RCTBridge.h>
+#import <React/RCTInvalidating.h>
+#import <React/RCTLog.h>
+#import <React/RCTUIManager.h>
+#import <React/RCTUtils.h>
+
+// `<RCTInvalidating>` is declared HERE, in the private class extension below,
+// not in EverframeModule.h — same reason `<NativeEverframeSpec>` is: the public
+// header is re-exported through the framework umbrella and we keep its import
+// surface minimal. RCTTurboModuleManager's `_invalidateModules` dispatches on
+// `respondsToSelector:@selector(invalidate)` and only then casts to
+// `id<RCTInvalidating>`, so a class-extension conformance (which is merged
+// into the class's protocol list at runtime) is exactly what it needs.
+
+// Codegen-generated `<NativeEverframeSpec>` protocol. Importing this header
+// requires ObjC++ (the file itself has `#error This file must be compiled
+// as Obj-C++`). It lives ONLY in this .mm — never in EverframeModule.h —
+// because the public header is re-exported through the framework umbrella
+// which is processed in plain-ObjC context (see EverframeModule.h header
+// comment for the full rationale).
+#if __has_include(<EverframeSpec/EverframeSpec.h>)
+#import <EverframeSpec/EverframeSpec.h>
+@interface EverframeModule () <NativeEverframeSpec, RCTInvalidating>
+@end
+#else
+@interface EverframeModule () <RCTInvalidating>
+@end
+#endif
+
+// Generated by Xcode from the Swift module name (set via podspec `s.name`).
+// We expose the Swift `EverframeBridge` class to ObjC++ via @objc public.
+// Module name is `EverframeRN` (NOT `Everframe`) — see EverframeRN.podspec
+// header comment for the rationale (collision with sdk-ios SwiftPM product).
+//
+// Use the framework form `<EverframeRN/EverframeRN-Swift.h>` when the pod is
+// built as a framework (use_frameworks! :linkage => :dynamic — our case),
+// and fall back to the same-module quoted form for static-lib builds. The
+// `__has_include` guard means a single source file works under either
+// linkage mode, mirroring react-native-screens' Swift-Bridging.h pattern.
+#if __has_include(<EverframeRN/EverframeRN-Swift.h>)
+#import <EverframeRN/EverframeRN-Swift.h>
+#else
+#import "EverframeRN-Swift.h"
+#endif
+
+@implementation EverframeModule {
+  // Strong ref to the bridge so we can look up RCTUIManager later.
+  __weak RCTBridge *_bridge;
+  // Session Vitals, owned PER MODULE INSTANCE (codex round-1, C4). It was a
+  // process-wide `static` registry on the Swift `EverframeBridge`; React Native
+  // does not guarantee one module instance, so that made two React instances
+  // share one token space (the second instance's `rp1` was silently refused)
+  // and let either one's `-invalidate` tear down the other's players. Android's
+  // module has always held its registry as an instance field; this matches it.
+  RemoteVitalsBridge *_vitals;
+  // D1 fix (stale-teardown identity guard, spec 2026-09-17 setExtra-resolver).
+  // Snapshot of `[EverframeBridge currentExtraResolveHookGeneration]` taken
+  // right after THIS instance's most recent `-configure:` call — see
+  // `EverframeBridge.resetExtraResolverForTeardown(_:)`'s doc comment for why
+  // `-invalidate` must hand this back rather than tearing down unconditionally.
+  // Zero-initialized by ObjC, matching `resetExtraResolverForTeardown(_:)`'s
+  // "0 = never installed" no-op case for an instance whose `-configure:` was
+  // never called (or never reached the install site) before `-invalidate`.
+  NSInteger _extraResolveHookGeneration;
+}
+
+RCT_EXPORT_MODULE(Everframe)
+
+- (instancetype)init {
+  if (self = [super init]) {
+    // Cheap: the registry allocates one lock and an empty map, nothing more —
+    // which is also why `+requiresMainQueueSetup` can stay NO.
+    _vitals = [RemoteVitalsBridge new];
+  }
+  return self;
+}
+
++ (BOOL)requiresMainQueueSetup {
+  // Module construction is cheap (Swift Bridge has no expensive init);
+  // returning NO keeps RN's TurboModule cold-start fast. The methods that
+  // need the main thread dispatch explicitly below.
+  return NO;
+}
+
+- (void)setBridge:(RCTBridge *)bridge {
+  _bridge = bridge;
+}
+
+// MARK: - configure(opts)
+
+// Signature MUST match the codegen-emitted protocol in EverframeSpec.h:
+//   - (void)configure:(JS::NativeEverframe::ConfigOpts &)opts;
+// Field accessors (.apiKey(), .sdkVersion(), .captureScreenshot(),
+// .networkBodiesDisabled()) are inline methods on the JS::NativeEverframe::
+// ConfigOpts struct, generated from the TS spec in src/NativeEverframe.ts.
+// The ingest URL is no longer JS-supplied — the native SDK bakes it at
+// compile time via IngestEndpoint.url.
+//
+// NOTE (pre-existing, out of scope here): `captureScreenshot` is populated
+// into ConfigOpts by extractBridgeConfig() but is never read below, so it is
+// silently dropped on iOS today. Task 9 (spec 2026-08-12) only wires
+// `networkBodiesDisabled` through; see task-9-report.md.
+- (void)configure:(JS::NativeEverframe::ConfigOpts &)opts {
+  NSString *appId = opts.apiKey() ?: @"";
+  BOOL networkBodiesDisabled = opts.networkBodiesDisabled().value_or(false);
+  // `installIdentifierDisabled` (MAI meter spec 2026-08-27) — `std::optional
+  // <bool>`, same shape as `networkBodiesDisabled()` above. Absent means the
+  // host said nothing, which is "send it": the SDK default is ON.
+  BOOL installIdentifierDisabled = opts.installIdentifierDisabled().value_or(false);
+  // `attachPinUi` (spec 2026-08-19) is a plain optional STRING field —
+  // `opts.attachPinUi()` returns a nullable NSString*, same shape as
+  // `opts.apiKey()` above, NOT the `std::optional<bool>` shape
+  // `networkBodiesDisabled()` uses. `EverframeBridge.configure` coerces a
+  // nil/unrecognised value to `.builtin`.
+  NSString *attachPinUi = opts.attachPinUi();
+  // `companionDeviceId` (naming spec 2026-08-24) is a plain optional STRING
+  // field — same nullable-NSString* shape as `attachPinUi` above, not the
+  // `std::optional<bool>` shape `networkBodiesDisabled()` uses.
+  NSString *companionDeviceId = opts.companionDeviceId();
+  // `companionBadgeEnabled`/`companionBadgePosition` (naming spec
+  // 2026-08-24, controller ruling / Task 6b) — flat fields on ConfigOpts;
+  // RN codegen cannot express the nested `{enabled, position}` shape the JS
+  // facade's `RuntimeConfig.companionBadge` uses, so `extractBridgeConfig`
+  // flattens it before it crosses. `companionBadgeEnabled()` is
+  // `std::optional<bool>`, same shape as `networkBodiesDisabled()` above;
+  // absent defaults to `true` (badge shown), matching
+  // `CompanionBadgeOptions.enabled`'s own default. `companionBadgePosition()`
+  // is a nullable NSString*, same shape as `attachPinUi`/`companionDeviceId`
+  // above; `EverframeBridge` coerces nil/unrecognised to `.bottomRight`.
+  BOOL companionBadgeEnabled = opts.companionBadgeEnabled().value_or(true);
+  BOOL shakeToReportEnabled = opts.shakeToReportEnabled().value_or(true);
+  NSString *companionBadgePosition = opts.companionBadgePosition();
+  // Inline reporter theme (reporter branding spec 2026-08-25, RN slice) —
+  // 8 flat optional STRING fields on ConfigOpts (RN codegen cannot express
+  // the nested `theme: { … }` shape the JS facade's `RuntimeConfig.theme`
+  // uses; `extractBridgeConfig` flattens it before it crosses). Collapsed
+  // here into ONE role-keyed dictionary so the Swift seam gains a single
+  // `theme:` parameter instead of eight — nil when the host set no theme,
+  // preserving "host did nothing" through to `EverframeConfig.theme`.
+  // Values cross unvalidated; the sdk-ios ThemeResolver revalidates hex
+  // per-field at presentation time.
+  NSMutableDictionary<NSString *, NSString *> *theme = [NSMutableDictionary new];
+  if (opts.themeBackground()) theme[@"background"] = opts.themeBackground();
+  if (opts.themeSurface()) theme[@"surface"] = opts.themeSurface();
+  if (opts.themeBorder()) theme[@"border"] = opts.themeBorder();
+  if (opts.themeText()) theme[@"text"] = opts.themeText();
+  if (opts.themeTextMuted()) theme[@"textMuted"] = opts.themeTextMuted();
+  if (opts.themeAccent()) theme[@"accent"] = opts.themeAccent();
+  if (opts.themeAccentForeground()) theme[@"accentForeground"] = opts.themeAccentForeground();
+  if (opts.themeDestructive()) theme[@"destructive"] = opts.themeDestructive();
+  // Session Vitals (spec 2026-09-06) — three flat optional fields on
+  // ConfigOpts (RN codegen cannot express the nested `vitals` object the JS
+  // facade uses; `extractBridgeConfig` flattens it before it crosses).
+  // `std::optional<bool>` / `std::optional<double>` shapes, same as
+  // `networkBodiesDisabled()` above — but forwarded as NSNumber* (nil =
+  // absent) rather than collapsed with `.value_or(...)`, because the Swift
+  // seam MUST be able to tell "absent" from "false": absent `vitalsEnabled`
+  // means "follow the dashboard toggle", while `false` is a local opt-out.
+  NSNumber *vitalsEnabled = opts.vitalsEnabled().has_value() ? @(opts.vitalsEnabled().value()) : nil;
+  NSNumber *vitalsSampleRate = opts.vitalsSampleRate().has_value() ? @(opts.vitalsSampleRate().value()) : nil;
+  NSNumber *vitalsCaptureSourceQuery = opts.vitalsCaptureSourceQuery().has_value() ? @(opts.vitalsCaptureSourceQuery().value()) : nil;
+  NSError *err = nil;
+  [EverframeBridge configureWithAppId:appId
+                            endpoint:@""
+               networkBodiesDisabled:networkBodiesDisabled
+           installIdentifierDisabled:installIdentifierDisabled
+                         attachPinUi:attachPinUi
+                   companionDeviceId:companionDeviceId
+               companionBadgeEnabled:companionBadgeEnabled
+                  shakeToReportEnabled:shakeToReportEnabled
+              companionBadgePosition:companionBadgePosition
+                               theme:(theme.count > 0 ? theme : nil)
+                       vitalsEnabled:vitalsEnabled
+                    vitalsSampleRate:vitalsSampleRate
+            vitalsCaptureSourceQuery:vitalsCaptureSourceQuery
+                               error:&err];
+  if (err != nil) {
+    // Configure is void-typed at the spec; we can't reject a promise here.
+    RCTLogWarn(@"[everframe] configure failed: %@", err.localizedDescription);
+  }
+  // D1 fix (stale-teardown identity guard, spec 2026-09-17 setExtra-resolver).
+  // Capture whichever installation is live right now — regardless of whether
+  // `err` fired above — and stash it on this instance for `-invalidate` to
+  // hand back to `resetExtraResolverForTeardown:`. See that method's doc
+  // comment on EverframeBridge.swift for the race this closes.
+  _extraResolveHookGeneration = [EverframeBridge currentExtraResolveHookGeneration];
+  // Codex round-5 — nothing re-registers the live players here any more. `renewAll()` raced
+  // the runtime's deferred-registration drain (it could detach the replacement it had just
+  // installed) and only ever reached THIS module instance's registry. The replacement is two
+  // parts, neither of them native: `EverframeBridge.configure` SKIPS the restart entirely when
+  // the effective options are unchanged and the SDK is already started, and when it does
+  // restart, the JS `configureEpoch` bump re-runs every vitals hook effect — each one
+  // detaching its old token and tracking a fresh one against the SDK that is now current.
+}
+
+// Additive synchronous startup entry. The legacy void selector above stays
+// ABI-compatible for already-compiled callers; current JS uses this boolean
+// method so its first synchronous capture cannot overtake configure dispatch.
+- (NSNumber *)configureSync:(JS::NativeEverframe::ConfigOpts &)opts {
+  [self configure:opts];
+  return @YES;
+}
+
+// MARK: - openReporter() -> Promise<object>
+
+// Opens the native TXReporterPresenter modal. Resolves with
+//   { status: "submitted" | "queued" | "cancelled", reportId?: <uuid> }
+- (void)openReporter:(RCTPromiseResolveBlock)resolve
+              reject:(RCTPromiseRejectBlock)reject {
+  [EverframeBridge openReporterWithCompletion:^(NSDictionary *result, NSError *err) {
+    if (err) {
+      reject(@"open_reporter_failed", err.localizedDescription, err);
+    } else {
+      resolve(result ?: @{});
+    }
+  }];
+}
+
+// MARK: - registerSensitiveRect(viewTag, rect)
+
+// `viewTag` is `double` per RN codegen rules (numbers cross as double).
+// `rect` is the codegen-typed JS::NativeEverframe::Rect — informational only;
+// the native registry resolves the view's actual frame at capture time.
+// We intentionally don't read .x()/.y()/.width()/.height() here — they're
+// available if a future iteration needs hint-based registration.
+- (void)registerSensitiveRect:(double)viewTag
+                         rect:(JS::NativeEverframe::Rect &)rect {
+  __weak RCTBridge *weakBridge = _bridge;
+  NSNumber *tag = @((NSInteger)viewTag);
+  dispatch_async(dispatch_get_main_queue(), ^{
+    RCTBridge *strongBridge = weakBridge;
+    UIView *view = nil;
+    if (strongBridge != nil) {
+      view = [strongBridge.uiManager viewForReactTag:tag];
+    }
+    // Bridge does a nil-check + warn-once (Pitfall P5 / T-06-02-03).
+    [EverframeBridge markSensitiveViewOrWarn:view];
+  });
+}
+
+// MARK: - setExtra(map)
+
+- (void)setExtra:(NSString *)value {
+  [EverframeBridge setExtra:(value ?: @"")];
+}
+
+// MARK: - setExtraResolverActive / signalExtraResolverReady (spec 2026-09-17 setExtra-resolver)
+
+// `active` is a REQUIRED boolean at the spec (not `active?: boolean`) —
+// codegen maps that to a plain `BOOL` parameter, same shape as
+// `recordPlayerEvent`'s required `t: number` → `double t` below. See
+// `NativeEverframe.ts`'s `Spec.setExtraResolverActive` doc comment for the
+// full contract: a presence bit only, never the resolved value itself.
+- (void)setExtraResolverActive:(BOOL)active {
+  [EverframeBridge setExtraResolverActive:active];
+}
+
+// JS handshake ack — mirrors `signalCompanionReportRequestReady` below
+// exactly. Releases `EverframeBridge.awaitJsExtraResolve`'s bounded wait for
+// this correlation id.
+- (void)signalExtraResolverReady:(NSString *)correlationId {
+  [EverframeBridge signalExtraResolverReady:(correlationId ?: @"")];
+}
+
+// MARK: - addBreadcrumb(message, kind?, level?, data?) — Plan 4 / Task 14
+
+// `kind`/`level`/`data` are the codegen-optional (`?`) params — nullable at
+// the ObjC boundary, forwarded as-is (no coercion here; EverframeBridge
+// forwards straight to Everframe.shared.addBreadcrumb, which owns all
+// coercion — Task 5). `data` is the codegen `UnsafeObject` freeform-object
+// escape hatch, crossing as `id`.
+- (void)addBreadcrumb:(NSString *)message
+                  kind:(NSString *)kind
+                 level:(NSString *)level
+                  data:(id)data {
+  NSDictionary *dataDict = [data isKindOfClass:[NSDictionary class]] ? (NSDictionary *)data : nil;
+  [EverframeBridge addBreadcrumb:(message ?: @"")
+                            kind:kind
+                           level:level
+                            data:dataDict];
+}
+
+// MARK: - recordScreen(name, data?) — screen markers (spec 2026-07-14)
+
+// Navigation screen marker. Forwarded as-is; EverframeBridge → Everframe
+// .shared.recordScreen owns from→to derivation (global chain shared with
+// the viewDidAppear auto-capture), gating, and coercion. `data` is the
+// codegen `UnsafeObject` escape hatch, crossing as `id`.
+- (void)recordScreen:(NSString *)name data:(id)data {
+  NSDictionary *dataDict = [data isKindOfClass:[NSDictionary class]] ? (NSDictionary *)data : nil;
+  [EverframeBridge recordScreen:(name ?: @"") data:dataDict];
+}
+
+// MARK: - Session Vitals (spec 2026-09-06) — five void, fire-and-forget methods
+
+// Pure forwarding, no validation: `_vitals`'s `RemotePlayerRegistry` (one per
+// module instance since codex round-1 C4) owns the token map, the 32-token cap and the epoch-ms sanity check, and
+// every one of its methods is a silent no-op for an unknown token — a bridge
+// must never throw into a host. `data`/`stats` are the spec's `UnsafeObject`
+// escape hatch; codegen declares them `NSDictionary *`, but we take `id` and
+// class-check — exactly what `addBreadcrumb`/`recordScreen` above do, since
+// nothing enforces the declared type at the JSI boundary and a non-dictionary
+// payload must be treated as absent rather than crash on a bad selector. `t`
+// is a REQUIRED double (the spec types it `t: number`, not `t?: number` — an
+// event with no timestamp is unorderable, so JS always supplies one).
+
+- (void)trackPlayer:(NSString *)token
+            library:(NSString *)library
+               name:(NSString *)name
+     libraryVersion:(NSString *)libraryVersion {
+  [_vitals trackPlayer:(token ?: @"")
+               library:(library ?: @"")
+                  name:name
+        libraryVersion:libraryVersion];
+}
+
+- (void)detachPlayer:(NSString *)token {
+  [_vitals detachPlayer:(token ?: @"")];
+}
+
+- (void)recordPlayerEvent:(NSString *)token
+                     type:(NSString *)type
+                        t:(double)t
+                     data:(id)data {
+  NSDictionary *dataDict = [data isKindOfClass:[NSDictionary class]] ? (NSDictionary *)data : nil;
+  [_vitals recordPlayerEvent:(token ?: @"") type:(type ?: @"") t:t data:dataDict];
+}
+
+// `stats` is REQUIRED at the spec (`stats: UnsafeObject`, no `?`), but the
+// class-check still matters: a non-dictionary value is DROPPED here rather
+// than passed on as an empty snapshot, which would clobber the player's live
+// stats with zeros.
+- (void)updatePlayerStats:(NSString *)token stats:(id)stats {
+  NSDictionary *statsDict = [stats isKindOfClass:[NSDictionary class]] ? (NSDictionary *)stats : nil;
+  if (statsDict == nil) return;
+  [_vitals updatePlayerStats:(token ?: @"") stats:statsDict];
+}
+
+// `dataJson` is a pre-serialised JSON STRING, not UnsafeObject — custom vitals
+// lines carry scalars and arrays that a codegen object type cannot express.
+// Unparseable JSON is recorded WITHOUT data by the registry, never dropped.
+- (void)trackVitals:(NSString *)name dataJson:(NSString *)dataJson token:(NSString *)token {
+  [_vitals trackVitals:(name ?: @"") dataJson:dataJson token:token];
+}
+
+// Module-instance teardown (RN tears the instance down on a Metro/OTA reload,
+// and on host shutdown). Detach every player registered through THIS INSTANCE
+// so their play/buffer spans close natively — since codex round-1 C1 the
+// integration's own `detach()` emits the closing `buffer_end`/`pause`, so the
+// spans really close instead of accruing to the end of the session — and so
+// the reloaded bundle's re-minted `rp1` is not shadowed by the dead one.
+//
+// LIFETIME (rewritten for C4): the registry is now PER MODULE INSTANCE, exactly
+// like Android's, so this teardown touches only the players this instance
+// registered. It no longer reaches a process-wide map, which is what let one
+// React instance detach another's players. The teardown is terminal — the
+// reload builds a NEW module instance with a NEW registry for the new bundle,
+// so nothing legitimate can still be calling the closed one.
+//
+// NOT done in `configure:`: a screen's `useTrackPlayer` effect runs BEFORE the
+// Provider's configure-on-mount, so clearing there would drop legitimate
+// registrations that had already landed.
+- (void)invalidate {
+  [_vitals reset];
+  // Review finding F4 (spec 2026-09-17 setExtra-resolver) — see
+  // `EverframeBridge.resetExtraResolverForTeardown`'s doc comment for why
+  // this must run here: without it, a JS-context teardown that skips
+  // `runtime.unmount()` leaves the extra-resolver presence flag stuck
+  // true, so every later report (including pure-native ones) pays the
+  // full 250ms ask-and-wait for an ack nobody will ever send.
+  //
+  // D1 fix: `_extraResolveHookGeneration` (captured at the end of
+  // `-configure:`) travels with this instance so the Swift side can tell a
+  // STALE instance's `-invalidate` — delivered late, on this module's
+  // method queue, after a reloaded bundle's fresh instance already
+  // reconfigured — from the CURRENT one, and no-op the former. See
+  // `EverframeBridge.resetExtraResolverForTeardown(_:)`'s doc comment for
+  // the full race this closes.
+  [EverframeBridge resetExtraResolverForTeardown:_extraResolveHookGeneration];
+}
+
+// MARK: - setUser(user?) — self-declared identity (spec 2026-08-12)
+
+// The spec types this bridge parameter `UnsafeObject`, NOT the named
+// `EverframeUserSpec` alias — codegen's ObjC generator ignores `?` optionality on a
+// named struct-alias param (TypeAliasTypeAnnotation) and always emits a
+// REQUIRED `JS::NativeEverframe::EverframeUserSpec &` reference, which would make
+// "no argument = clear" unrepresentable. `UnsafeObject` resolves to
+// GenericObjectTypeAnnotation, which DOES honour `?` and generates the
+// nullable `(NSDictionary *)user` protocol signature — verified against
+// this repo's installed `@react-native/codegen` (see NativeEverframe.ts's
+// file header for the full writeup). `(id)` here matches `addBreadcrumb`'s
+// `data` param below, which crosses the same GenericObjectTypeAnnotation
+// shape; `id` is compatible with the generated `NSDictionary *` protocol
+// type. `EverframeBridge` re-validates and pulls out id/email/displayName
+// defensively.
+- (void)setUser:(id)user {
+  NSDictionary *dict = [user isKindOfClass:[NSDictionary class]] ? (NSDictionary *)user : nil;
+  [EverframeBridge setUser:dict];
+}
+
+// MARK: - reportCrash(crashJson) — Task 13 (spec 2026-07-18)
+
+// Sync spec method: codegen emits a non-void, non-promise boolean-returning
+// signature as `NSNumber *` (RN's ObjC bridge convention for a boxed bool
+// return). The RN fatal path calls this synchronously before RN's default
+// handler aborts the process, so persistence must complete before returning.
+- (NSNumber *)reportCrash:(NSString *)crashJson {
+  return @([EverframeBridge reportCrash:(crashJson ?: @"")]);
+}
+
+- (NSNumber *)captureHandledException:(NSString *)crashJson {
+  return @([EverframeBridge captureHandledException:(crashJson ?: @"")]);
+}
+
+// MARK: - startCompanion / stopCompanion (Plan 06.2-11)
+
+// Opens a relay WS connection against the build-time-baked ingest URL
+// (sdk-ios IngestEndpoint.url) and starts forwarding `Everframe.shared
+// .companion` signals (state + pairUrl) to JS via the
+// `EverframeEventEmitter` RCTEventEmitter subclass.
+- (void)startCompanion {
+  [EverframeBridge startCompanion:@""];
+}
+
+- (void)stopCompanion {
+  [EverframeBridge stopCompanion];
+}
+
+// MARK: - signalCompanionReportRequestReady(correlationId)
+
+// Companion handshake: JS calls this when it is ready for capture to
+// proceed, releasing the native bridge's bounded wait
+// (CompanionCaptureBridge.awaitJsReactTreeAttach).
+- (void)signalCompanionReportRequestReady:(NSString *)correlationId {
+  [EverframeBridge signalCompanionReportRequestReady:(correlationId ?: @"")];
+}
+
+// MARK: - addListener / removeListeners (RN NativeEventEmitter contract)
+//
+// These are intentional no-ops on `EverframeModule` — the JS facade
+// (`src/companion.ts`) constructs `NativeEventEmitter(NativeModules
+// .EverframeEventEmitter)`, NOT NativeModules.Everframe, so the real
+// addListener/removeListeners traffic flows to the `EverframeEventEmitter`
+// subclass via RCTEventEmitter's built-in implementations. We still need
+// these stubs on `Everframe` because RN's TurboModule codegen requires every
+// declared spec method to have a backing implementation, and the JS facade
+// keeps `addListener`/`removeListeners` on the Spec so a future migration
+// to a single-module emitter (Android already does this) wouldn't require
+// a spec change.
+
+- (void)addListener:(NSString *)eventName {
+  // no-op — see comment above.
+}
+
+- (void)removeListeners:(double)count {
+  // no-op — see comment above.
+}
+
+#if __has_include(<EverframeSpec/EverframeSpec.h>)
+// TurboModule JSI factory — registers the C++ spec impl with the JS runtime.
+// Available only once codegen has materialized `EverframeSpec`.
+- (std::shared_ptr<facebook::react::TurboModule>)
+    getTurboModule:(const facebook::react::ObjCTurboModule::InitParams &)params {
+  return std::make_shared<facebook::react::NativeEverframeSpecJSI>(params);
+}
+#endif
+
+@end

package/ios/Sources/RemoteVitalsBridge.swift

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 ScriptX
+//
+// Per-module-instance Session Vitals bridge (spec 2026-09-06; codex round-1, C4).
+//
+// WHY THIS EXISTS. The five vitals shims used to hang off `EverframeBridge` as
+// `static` funcs over a `private static let remotePlayers` registry — one map
+// for the whole PROCESS. React Native does not guarantee one module instance:
+// a host can run several React instances (a brownfield app embedding two
+// surfaces, and RN's own reload path, which builds the new instance BEFORE it
+// invalidates the old one). With a process-wide registry those instances share
+// one token space, so instance B's `rp1` collides with instance A's still-live
+// `rp1` (the second `trackPlayer` is silently refused, and that player's whole
+// session goes unmeasured), and — worse — B's `invalidate` runs `detachAll()`
+// over A's registrations, tearing down players A is still using.
+//
+// The Android module has never had this problem: its registry is a plain
+// instance field on the module (`private val remotePlayers`), so each instance
+// owns its own token space and its own teardown. This is the same shape.
+//
+// LIFETIME: one `RemoteVitalsBridge` per `EverframeModule` instance, created at
+// module init and released with it. `reset()` runs from `-[EverframeModule
+// invalidate]`, i.e. on module-instance teardown, which is exactly what a
+// Metro/OTA reload does; it detaches ONLY this instance's players. That
+// teardown is terminal — see `RemotePlayerRegistry.detachAll()` — because the
+// reload constructs a NEW module instance with a NEW registry for the new
+// bundle. A bare `Everframe.shared` restart does NOT reach here: the module
+// instance survives it, and the JS hooks still own detach for every player
+// they registered.
+//
+// This class is GLUE — no validation lives here: unknown tokens, out-of-range
+// timestamps and the 32-token cap are all the registry's business, and every
+// one of its methods is a silent no-op rather than a throw.
+import Foundation
+import EverframeKit
+
+@objc public final class RemoteVitalsBridge: NSObject {
+
+    /// `captureSourceQuery` is a PROVIDER closure resolved at attach time (I13), never a
+    /// value read once at `configure()` — a host that reconfigures mid-session must get the
+    /// new answer for players attached afterwards.
+    private let remotePlayers = RemotePlayerRegistry(
+        register: { integration, name in Everframe.shared.trackPlayer(integration, name: name) },
+        sessionTrack: { name, data in Everframe.shared.trackVitals(name, data: data, player: nil) },
+        captureSourceQuery: { Everframe.shared.currentConfig?.vitals.captureSourceQuery ?? false })
+
+    @objc public func trackPlayer(
+        _ token: NSString,
+        library: NSString,
+        name: NSString?,
+        libraryVersion: NSString?
+    ) {
+        remotePlayers.track(
+            token: token as String,
+            library: library as String,
+            name: name as String?,
+            libraryVersion: libraryVersion as String?
+        )
+    }
+
+    @objc public func detachPlayer(_ token: NSString) {
+        remotePlayers.detach(token: token as String)
+    }
+
+    @objc public func recordPlayerEvent(
+        _ token: NSString,
+        type: NSString,
+        t: Double,
+        data: NSDictionary?
+    ) {
+        remotePlayers.record(
+            token: token as String,
+            type: type as String,
+            t: t,
+            data: data as? [String: Any]
+        )
+    }
+
+    @objc public func updatePlayerStats(_ token: NSString, stats: NSDictionary) {
+        remotePlayers.updateStats(
+            token: token as String,
+            stats: (stats as? [String: Any]) ?? [:]
+        )
+    }
+
+    @objc public func trackVitals(_ name: NSString, dataJson: NSString?, token: NSString?) {
+        remotePlayers.trackVitals(
+            name: name as String,
+            dataJson: dataJson as String?,
+            token: token as String?
+        )
+    }
+
+    /// Detach every player registered through THIS module instance and close the registry.
+    /// Called from `-[EverframeModule invalidate]`. Idempotent.
+    @objc public func reset() {
+        remotePlayers.detachAll()
+    }
+}