@scalebun/react-native 1.10.7 → 1.11.1

package/lib/module/public/ScaleBunFacade.js

@@ -253,6 +253,11 @@ class ScaleBunFacade {
           logger.warn('[ScaleBun] A signing key is pinned but no signature verifier is available. ' + 'Signature checking is fail-closed: updates will be REJECTED until one exists. ' + 'Install the optional peers `@noble/ed25519` + `@noble/hashes` (no further ' + 'code needed), or supply `ota.verifySignature`.');
         }
       }
+      // `healthyAfterMs` is the field BootGuardConfig actually declares.
+      // This passed `healthyTimeoutMs`, which nothing reads, so a host that
+      // tuned the boot-guard window silently got the 10s default instead.
+      // Both spellings are accepted so the older one keeps working.
+      const healthyAfterMs = typeof ota.healthyAfterMs === 'number' ? ota.healthyAfterMs : typeof ota.healthyTimeoutMs === 'number' ? ota.healthyTimeoutMs : undefined;
       otaOrchestrator.init({
         ...(signingRequested ? {
           signature: {
@@ -262,15 +267,123 @@ class ScaleBunFacade {
             verifier
           }
         } : {}),
-        ...(typeof ota.healthyTimeoutMs === 'number' ? {
-          healthyTimeoutMs: ota.healthyTimeoutMs
+        ...(healthyAfterMs !== undefined ? {
+          healthyAfterMs
         } : {})
       });
       logger.info('[ScaleBun] OTA enabled from init config.');
+
+      // Run the checks the config asked for. Until this existed, `ota.enabled`
+      // initialised the orchestrator and then never checked anything: the
+      // documented `checkOnForeground` and `channelOverride` options were read
+      // by no code at all, and an app following the documented config received
+      // updates only if it ALSO drove `useOtaUpdate` or the CodePush shim by
+      // hand. Nothing logged, because "no update available" and "never asked"
+      // look identical from the outside.
+      this._startOtaChecks(ota);
     } catch (err) {
       logger.warn(`[ScaleBun] OTA init failed: ${err?.message ?? err}`);
     }
   }
+
+  /** Guards against overlapping config-driven OTA checks. */
+  _otaCheckInFlight = false;
+  /** Wall clock of the last config-driven check, for the foreground floor. */
+  _otaLastCheckAt = 0;
+  _otaForegroundListener = null;
+
+  /**
+   * Minimum gap between config-driven checks.
+   *
+   * A foreground transition is cheap to trigger — app switchers, permission
+   * dialogs and share sheets all produce one — so an unthrottled check would
+   * put a request on the hot path every time the user glanced away. Ten
+   * minutes is well below any realistic release cadence and well above that
+   * noise. A host that wants a check on demand calls `useOtaUpdate().sync()`,
+   * which is never throttled.
+   */
+  static OTA_MIN_CHECK_INTERVAL_MS = 10 * 60 * 1000;
+
+  /**
+   * Drive OTA checks from init config: once at startup, then on each
+   * foreground when `checkOnForeground` is on (the schema default).
+   *
+   * `appVersion` is resolved from the native bridge rather than asked of the
+   * integrator, because it gates the server's `targetAppVersion` semver check
+   * — sending a wrong or invented value is worse than sending none, and there
+   * is no honest default. If it cannot be resolved, the check is skipped with
+   * a warning instead of guessing.
+   */
+  _startOtaChecks(ota) {
+    // Never in a debug build. `ScaleBunOtaModule.getJSBundleFile()` returns null
+    // there on purpose so Metro keeps ownership of the bundle — so a bundle
+    // downloaded in dev is installed into a slot that will never be loaded, and
+    // the identity check on the next launch then correctly observes that the
+    // running code is not what was installed and reports APPLY_FAILED. Checking
+    // at all in dev buys nothing and manufactures that false alarm. A developer
+    // testing the OTA path drives `useOtaUpdate().sync()` explicitly.
+    if (__DEV__) {
+      logger.info('[ScaleBun] OTA checks are skipped in debug builds (Metro owns the bundle).');
+      return;
+    }
+    const runCheck = async trigger => {
+      if (this._otaCheckInFlight) return;
+      if (trigger === 'foreground' && Date.now() - this._otaLastCheckAt < ScaleBunFacade.OTA_MIN_CHECK_INTERVAL_MS) {
+        return;
+      }
+      const clientKey = this._clientKey;
+      const apiUrl = this._apiBaseUrl;
+      if (!clientKey || !apiUrl) return;
+      this._otaCheckInFlight = true;
+      try {
+        const info = await bridgeAdapter.getDeviceInfo();
+        const appVersion = info?.appVersion;
+        if (!appVersion) {
+          logger.warn('[ScaleBun] OTA check skipped — the app version could not be read from the ' + 'native bridge. Rebuild the native app, or drive checks yourself with ' + 'useOtaUpdate({ appVersion }).');
+          return;
+        }
+        this._otaLastCheckAt = Date.now();
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const {
+          otaOrchestrator
+        } = require('../features/ota/OtaOrchestrator');
+        await otaOrchestrator.sync({
+          apiUrl,
+          clientKey,
+          appVersion,
+          // The documented option, finally connected. Omitted means the
+          // server's `default` channel, exactly as before.
+          channelName: typeof ota.channelOverride === 'string' ? ota.channelOverride : undefined
+          // Never forced from config: the release's own installMode
+          // decides when the app restarts, and yanking the screen out
+          // from under a user is not a decision this switch should make.
+        });
+      } catch (err) {
+        logger.warn(`[ScaleBun] OTA check failed: ${err?.message ?? err}`);
+      } finally {
+        this._otaCheckInFlight = false;
+      }
+    };
+    void runCheck('startup');
+    if (ota.checkOnForeground === false) return;
+    if (this._otaForegroundListener) return; // idempotent across repeated init()
+    try {
+      // Through `appLifecycle`, not a second AppState subscription: the SDK
+      // already owns one and fanning out from it keeps every consumer on the
+      // same transition sequence.
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const {
+        appLifecycle
+      } = require('../core/lifecycle/appLifecycle');
+      this._otaForegroundListener = state => {
+        if (state === 'active') void runCheck('foreground');
+      };
+      appLifecycle.addListener(this._otaForegroundListener);
+    } catch {
+      // Lifecycle unavailable (tests, exotic hosts) — the startup check stands.
+      this._otaForegroundListener = null;
+    }
+  }
   _autoEnableDebug(debugConfig) {
     try {
       const dbgConfig = buildDebugConfigFromInitConfig(debugConfig);

package/lib/typescript/analytics/EventTracker.d.ts

@@ -125,7 +125,7 @@ export declare class EventTracker {
      * Persisted so it survives the click→install→open gap. Call BEFORE start() ideally.
      */
     setAttributionClickId(clickId: string): void;
-    track(eventName: string, properties?: Record<string, any>): void;
+    track(eventName: string, properties?: Record<string, any>, timestamp?: number): void;
     trackPurchase(input: {
         revenue: number;
         currency: string;

package/lib/typescript/analytics/automaticEvents.d.ts

@@ -18,9 +18,11 @@ export type AutomaticEventName = 'app_foregrounded' | 'app_backgrounded' | 'scre
 export interface AutomaticEvent {
     name: AutomaticEventName;
     properties: Record<string, unknown>;
+    /** Original observation time. Delivery can be delayed while native coordinates resolve. */
+    timestamp?: number;
 }
 type AutomaticEventListener = (event: AutomaticEvent) => void;
-export declare function emitAutomaticEvent(name: AutomaticEventName, properties?: Record<string, unknown>): void;
+export declare function emitAutomaticEvent(name: AutomaticEventName, properties?: Record<string, unknown>, timestamp?: number): void;
 export declare function subscribeAutomaticEvents(listener: AutomaticEventListener): () => void;
 /** Test-only reset; intentionally not exported from the package entry point. */
 export declare function resetAutomaticEventsForTests(): void;

package/lib/typescript/core/constants/version.d.ts

@@ -1,7 +1,12 @@
 /**
  * ScaleBun SDK version. Sent with the session-start envelope so the dashboard
  * can attribute telemetry to the SDK build that produced it.
- * Keep in sync with package.json "version".
+ * Keep in sync with package.json "version" — `version.test.ts` fails when they drift.
+ *
+ * Why the test matters: the 1.11.0 bump missed this line, so the build would have reported itself as
+ * 1.10.6. Every "is the release live, and on what share of traffic" question is answered from this
+ * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
+ * version was introduced to solve.
  */
-export declare const SDK_VERSION = "1.10.7";
+export declare const SDK_VERSION = "1.11.1";
 //# sourceMappingURL=version.d.ts.map

package/lib/typescript/features/journey/interactionProtocol.d.ts

@@ -0,0 +1,21 @@
+/** One physical interaction, shared by replay and analytics projections. */
+export declare const INTERACTION_PROTOCOL_VERSION = 1;
+export type InteractionStateStatus = 'captured_empty' | 'captured_nonempty' | 'not_captured' | 'not_instrumented';
+export interface InteractionStartContext {
+    interactionId: string;
+    occurredAt: number;
+    x: number;
+    y: number;
+    target?: string;
+    targetId?: string;
+    screenName?: string;
+    ui?: string;
+    stateStatus: InteractionStateStatus;
+    emitAutomaticAnalytics: boolean;
+}
+export declare function generateInteractionId(): string;
+/** Match a native bridge event to the JS evidence sampled at the same finger-down. */
+export declare function nearestInteractionStart<T extends InteractionStartContext>(starts: readonly T[], occurredAt: number, toleranceMs?: number): T | undefined;
+/** Analytics is a projection of the same evidence; no second click is invented. */
+export declare function automaticInteractionProperties(payload: Record<string, unknown>, screenName: string | undefined, canonicalMirror: boolean): Record<string, unknown>;
+//# sourceMappingURL=interactionProtocol.d.ts.map

package/lib/typescript/features/ota/OtaEventEmitter.d.ts

@@ -5,10 +5,24 @@
  *
  * Sprint 5 deliverable (S5-NAT-2, S5-NAT-3).
  */
-export type OtaEventType = 'CHECK' | 'DOWNLOAD_STARTED' | 'DOWNLOAD_PROGRESS' | 'DOWNLOAD_COMPLETE' | 'INSTALLED' | 'APPLY_FAILED' | 'AUTO_ROLLBACK' | 'MANUAL_ROLLBACK';
+export type OtaEventType = 
+/** A check was made against the server. The denominator of the funnel. */
+'CHECK'
+/** The server answered with a bundle for this device — the offer, before any bytes move. */
+ | 'OFFERED' | 'DOWNLOAD_STARTED' | 'DOWNLOAD_PROGRESS' | 'DOWNLOAD_COMPLETE'
+/** Staged and swapped. Emitted optimistically, BEFORE the bundle has booted. */
+ | 'INSTALLED'
+/** The bundle booted and survived to the healthy mark — the honest activation signal. */
+ | 'BOOT_SUCCESS' | 'APPLY_FAILED' | 'AUTO_ROLLBACK' | 'MANUAL_ROLLBACK';
 export interface OtaEvent {
     type: OtaEventType;
     bundleId: string;
+    /**
+     * The release this bundle was served as. Optional because a bundle installed
+     * by an older SDK has no recorded release; present on everything emitted by a
+     * current one, so the delivery funnel can key by release rather than bundle.
+     */
+    releaseId?: string;
     version?: number;
     /** 0–100 for DOWNLOAD_PROGRESS */
     progress?: number;

package/lib/typescript/features/ota/OtaOrchestrator.d.ts

@@ -15,8 +15,13 @@ export interface BootGuardConfig {
      */
     healthyAfterMs?: number;
     /**
-     * Maximum consecutive boot-guard reverts before the SDK stops trying
-     * OTA bundles and pins to the factory bundle. Default: 2.
+     * @deprecated Not honoured, and never was — nothing in JS reads this field.
+     *
+     * The boot-attempt limit lives in native code, where the counter it bounds is
+     * incremented (`MAX_BOOT_ATTEMPTS` in `SlotManager.kt` / `OtaSlotManager.swift`,
+     * both 2). Setting it here has no effect; the field is kept only so existing
+     * call sites keep compiling. Change the limit natively, or file a request for
+     * it to be plumbed through `initOutbox`-style native config.
      */
     maxRevertAttempts?: number;
 }
@@ -51,6 +56,11 @@ export declare class OtaOrchestrator {
      * Read the active slot back into `currentBundle` so the next check reports
      * what this device is genuinely running.
      */
+    /**
+     * Parse the native slot state once. Returns null when the module is absent or
+     * the payload is unreadable — every caller treats that as "factory bundle".
+     */
+    private readSlotState;
     private hydrateCurrentBundleFromSlots;
     /**
      * Compare the bundle the slot manager believes is active against the identity
@@ -71,7 +81,16 @@ export declare class OtaOrchestrator {
     private static readonly INSTALL_EXPECTATION_KEY;
     private recordInstallExpectation;
     private readInstallRecord;
-    private readInstallExpectation;
+    /**
+     * Drop the identity token once the install has been proven, keeping the rest
+     * of the record.
+     *
+     * The record does two jobs: it proves an install took effect (once), and it
+     * maps the native slot's sha256 back to a bundle id (for the life of that
+     * bundle). Only the first job is finished after a successful verification, so
+     * only the token is retired.
+     */
+    private retireIdentityToken;
     private clearInstallExpectation;
     private storage;
     /**

package/lib/typescript/features/ota/OtaTypes.d.ts

@@ -7,42 +7,38 @@
  */
 /**
  * ═══════════════════════════════════════════════════════════════════════════
- * OTA-TELEMETRY-SPEC — remaining telemetry fixes (from the 2026-08 audit)
+ * OTA-TELEMETRY-SPEC — status (spec §84-86)
  * ═══════════════════════════════════════════════════════════════════════════
- * These close the SDK half of spec §84-86. All are ADDITIVE + backward-compatible
- * (new optional fields, new enum members, new no-throw emit calls); old installed
- * clients omit them and the backend ingests nullable/unknown fields. Each ALTERS
- * DEVICE RUNTIME BEHAVIOR, so land them behind a real RN build + device/kill-test
- * (Metro cannot exercise the boot-guard) — this file only carries the contract
- * types + this spec, not the runtime wiring.
+ * Items 1-3 are DONE. All were additive and backward-compatible: old installed
+ * clients simply omit the new fields and never emit the new types, and the
+ * backend ingests nullable columns. Because they alter device runtime behaviour,
+ * verify against a real RN build + device kill-test before release — Metro
+ * cannot exercise the boot guard.
  *
- * 1. releaseId end-to-end  (CRITICAL — root of the dashboard funnel mismatch)
- *    Backend already serves it: OtaBundlePayload.releaseId (done, this file +
- *    ota-check.service.ts). SDK TODO:
- *      - store payload.releaseId on the downloaded/installed bundle state, and
- *      - set `releaseId: bundle.releaseId` in the delivery mapper
- *        OtaOrchestrator.ts deliverOtaEvents (~:105) — currently only bundleId.
- *      Then ota_events carry releaseId and the funnel keys by release.
+ * 1. releaseId end-to-end — DONE. `recordInstallExpectation` persists the
+ *    release id (so a rollback reported launches later can still name it),
+ *    `hydrateCurrentBundleFromSlots` restores it, every emit site passes it, and
+ *    `deliverOtaEvents` maps it onto the wire item.
  *
- * 2. Emit CHECK + OFFERED  (funnel top is currently unmeasurable)
- *    - CHECK: emit at the start of checkForUpdate (OtaOrchestrator.ts ~:480),
- *      before the fetch. ('CHECK' type already exists — no emit site today.)
- *    - OFFERED: add 'OFFERED' to OtaEventType, emit when checkRes.action ===
- *      'DOWNLOAD' (~:619) before download begins.
+ * 2. CHECK + OFFERED — DONE. CHECK is emitted at the top of `sync()` for devices
+ *    already on an OTA bundle (a device on the factory bundle has no owned
+ *    bundle id to name, and the server drops rows it cannot resolve — those are
+ *    counted server-side instead). OFFERED is emitted on `action === 'DOWNLOAD'`
+ *    before any bytes move.
  *
- * 3. Emit BOOT_SUCCESS  (honest activation signal)
- *    Add 'BOOT_SUCCESS' to OtaEventType and emit it from the boot-guard
- *    markHealthy path (OtaOrchestrator.ts ~:863). INSTALLED (~:794) is emitted
- *    optimistically BEFORE the bundle boots; keep it (it means "staged+swapped")
- *    but let the dashboard measure real activation on BOOT_SUCCESS. Optionally
- *    add 'VERIFIED' after signature check (~:635).
+ * 3. BOOT_SUCCESS — DONE. Emitted from the boot-guard heartbeat once the bundle
+ *    has actually booted and survived to `healthyAfterMs`. INSTALLED is kept and
+ *    still means "staged + swapped", but activation should be measured on
+ *    BOOT_SUCCESS: INSTALLED fires before the bundle has run, so it credits
+ *    bundles that installed and then crash-reverted.
  *
- * 4. Stamp the running OTA bundle onto session/crash telemetry
- *    SessionMetadata.bundleId is the NATIVE app package id, not the OTA bundle.
- *    Add optional otaBundleId?/otaBundleVersion? (distinct fields — do NOT
- *    overload bundleId) sourced from otaOrchestrator.getCurrentBundle() at
- *    session start (SessionManager.ts ~:451), so crashes attribute to the
- *    running bundle/version (release-health crash impact).
+ * 4. Stamp the running OTA bundle onto session/crash telemetry — NOT DONE.
+ *    `SessionMetadata.bundleId` is the NATIVE app package id, not the OTA bundle,
+ *    so crashes cannot currently be attributed to the bundle that produced them
+ *    (release-health crash impact). Needs optional otaBundleId?/otaBundleVersion?
+ *    (distinct fields — do NOT overload bundleId) sourced from
+ *    `otaOrchestrator.getCurrentBundle()` at session start, plus the matching
+ *    backend columns and a Prisma migration.
  *
  * Do NOT repurpose errorCode (it already collapses failure-error vs rollback-
  * reason); add a new optional field if the two must be distinguished.
@@ -126,7 +122,8 @@ export interface OtaPatchPayload {
     sha256: string;
     baseBundleId: string;
 }
-export type OtaEventType = 'CHECK' | 'DOWNLOAD_STARTED' | 'DOWNLOAD_COMPLETE' | 'INSTALLED' | 'APPLY_FAILED' | 'AUTO_ROLLBACK' | 'MANUAL_ROLLBACK';
+import type { OtaEventType as EmittedOtaEventType } from './OtaEventEmitter';
+export type OtaEventType = Exclude<EmittedOtaEventType, 'DOWNLOAD_PROGRESS'>;
 export interface OtaEventItem {
     kind: 'ota_event';
     bundleId: string;

package/lib/typescript/features/session/JourneyEventPipeline.d.ts

@@ -50,6 +50,7 @@ export declare class JourneyEventPipeline {
         journeyId?: string;
         /** Frame that was on screen when this happened. Resolved by the caller; see sessionTypes. */
         frameId?: string;
+        timestamp?: number;
     }): JourneyEvent | null;
     /**
      * Anchor a crash event — protect nearby events from eviction.

package/lib/typescript/features/session/SessionManager.d.ts

@@ -17,6 +17,7 @@ import type { DebugTransport } from '../../debug/transport';
 import type { SessionMetadata, SessionReplayConfig, JourneyEventType, JourneyEventSeverity, JourneyEventSource, CrashAnchor, NativeSyncMetadata, SyncDecisionCallback } from './sessionTypes';
 import { type NativeCaptureFn } from './ReplayCaptureManager';
 import type { BackendSessionAdapter } from './BackendSessionAdapter';
+import { type InteractionStateStatus } from '../journey/interactionProtocol';
 export interface SessionManagerConfig {
     sessionReplay?: Partial<SessionReplayConfig>;
     syncPolicy?: SyncDecisionCallback;
@@ -43,15 +44,6 @@ export declare class SessionManager {
      * lane even when no replay recording is active. Additive, opt-in (default off).
      */
     private _captureInteractionHeatmap;
-    /**
-     * Sampling cap for the analytics-lane heatmap emission. Now that capture is
-     * ON by default, an unbounded one-event-per-gesture stream could materially
-     * inflate ingest volume. We cap emitted interactions per analytics-session
-     * window (finalize-scoped per foreground): the first N gestures define the
-     * hotspot shape; the long tail is dropped. Resets when the window changes.
-     */
-    private _heatmapWindowSessionId;
-    private _heatmapWindowCount;
     private session;
     private active;
     private timeoutTimer;
@@ -207,6 +199,8 @@ export declare class SessionManager {
         traceId?: string;
         source?: JourneyEventSource;
         journeyId?: string;
+        /** Original observation time; interaction capture may resolve asynchronously. */
+        timestamp?: number;
     }): void;
     /**
      * Anchor a crash in the session context.
@@ -223,7 +217,10 @@ export declare class SessionManager {
      * Notify of a user interaction. Called by ScaleBunDebugRoot touch handlers.
      * Also triggers frame capture for desktop-initiated recordings.
      */
-    onUserAction(subtype: string, payload?: Record<string, unknown>): void;
+    onUserAction(subtype: string, payload?: Record<string, unknown>, context?: {
+        screen?: string;
+        timestamp?: number;
+    }): void;
     /**
      * Detailed gesture detection — called by ScaleBunDebugRoot touch handlers.
      * Emits a USER_ACTION event with gesture-specific subtype and payload.
@@ -263,6 +260,14 @@ export declare class SessionManager {
         screenWidth?: number;
         screenHeight?: number;
         platform?: string;
+        interactionId?: string;
+        interactionProtocol?: number;
+        occurredAt?: number;
+        ui?: string;
+        stateStatus?: InteractionStateStatus;
+        targetId?: string;
+        screenName?: string;
+        emitAutomaticAnalytics?: boolean;
     }): void;
     /**
      * Manual frame capture — triggered by Desktop "Capture Step" button.

package/lib/typescript/public/ScaleBunFacade.d.ts

@@ -82,6 +82,33 @@ declare class ScaleBunFacade {
      * than letting the app discover it as a silent no-update condition.
      */
     private _maybeStartOta;
+    /** Guards against overlapping config-driven OTA checks. */
+    private _otaCheckInFlight;
+    /** Wall clock of the last config-driven check, for the foreground floor. */
+    private _otaLastCheckAt;
+    private _otaForegroundListener;
+    /**
+     * Minimum gap between config-driven checks.
+     *
+     * A foreground transition is cheap to trigger — app switchers, permission
+     * dialogs and share sheets all produce one — so an unthrottled check would
+     * put a request on the hot path every time the user glanced away. Ten
+     * minutes is well below any realistic release cadence and well above that
+     * noise. A host that wants a check on demand calls `useOtaUpdate().sync()`,
+     * which is never throttled.
+     */
+    private static readonly OTA_MIN_CHECK_INTERVAL_MS;
+    /**
+     * Drive OTA checks from init config: once at startup, then on each
+     * foreground when `checkOnForeground` is on (the schema default).
+     *
+     * `appVersion` is resolved from the native bridge rather than asked of the
+     * integrator, because it gates the server's `targetAppVersion` semver check
+     * — sending a wrong or invented value is worse than sending none, and there
+     * is no honest default. If it cannot be resolved, the check is skipped with
+     * a warning instead of guessing.
+     */
+    private _startOtaChecks;
     private _autoEnableDebug;
     /** Boot the Phase 1 envelope tracking lane if an appId is configured. */
     private _maybeStartEventTracker;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalebun/react-native",
-  "version": "1.10.7",
+  "version": "1.11.1",
   "description": "React Native SDK for ScaleBun",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -121,7 +121,7 @@
     "@babel/runtime": "^7.25.0",
     "@jridgewell/sourcemap-codec": "1.5.5",
     "@jridgewell/trace-mapping": "0.3.31",
-    "@scalebun/cli": "^1.10.2"
+    "@scalebun/cli": "^1.11.0"
   },
   "codegenConfig": {
     "name": "ScaleBunSpec",
@@ -154,6 +154,7 @@
     "watch": "bob build --watch",
     "test:screens": "node --experimental-transform-types --import ./scripts/rn-globals.mjs --import ./scripts/register-ts-ext.mjs --test scripts/screen-detection.test.ts",
     "test:uistate": "node --experimental-transform-types --import ./scripts/rn-globals.mjs --import ./scripts/register-ts-ext.mjs --test scripts/ui-state.test.ts",
-    "typecheck:scripts": "tsc --noEmit -p tsconfig.scripts.json"
+    "typecheck:scripts": "tsc --noEmit -p tsconfig.scripts.json",
+    "test:protocol": "node --experimental-transform-types --import ./scripts/rn-globals.mjs --import ./scripts/register-ts-ext.mjs --test scripts/interaction-protocol.test.ts"
   }
 }

package/src/analytics/EventTracker.ts

@@ -172,7 +172,7 @@ export class EventTracker {
         this.started = true;
         if (this.cfg.automaticEventTracking) {
             this.automaticEventsUnsubscribe = subscribeAutomaticEvents((event) => {
-                this.track(event.name, event.properties);
+                this.track(event.name, event.properties, event.timestamp);
             });
         }
         if (this.cfg.autoLifecycleEvents) {
@@ -284,9 +284,9 @@ export class EventTracker {
 
     // ─── tracking ────────────────────────────────────────────────────────────
 
-    track(eventName: string, properties?: Record<string, any>): void {
+    track(eventName: string, properties?: Record<string, any>, timestamp?: number): void {
         try {
-            this.enqueue(this.buildEnvelope(eventName, properties));
+            this.enqueue(this.buildEnvelope(eventName, properties, timestamp));
             try { this.cfg.onEvent?.(eventName); } catch { /* no-throw */ }
         } catch (err) {
             logger.warn(`[ScaleBun.events] track failed: ${(err as Error)?.message}`);
@@ -408,7 +408,7 @@ export class EventTracker {
 
     // ─── internals ─────────────────────────────────────────────────────────────
 
-    private buildEnvelope(eventName: string, properties?: Record<string, any>): Envelope {
+    private buildEnvelope(eventName: string, properties?: Record<string, any>, timestamp?: number): Envelope {
         const ctx = this.cfg.context ?? {};
         let canonicalSessionId: string | null | undefined;
         try {
@@ -419,7 +419,7 @@ export class EventTracker {
         const env: Envelope = {
             event_id: uuid(),
             event_name: eventName,
-            event_time: Date.now(),
+            event_time: timestamp ?? Date.now(),
             app_id: this.cfg.appId,
             platform: this.cfg.platform ?? resolveEventPlatform(),
             installation_id: this.installationId,

package/src/analytics/automaticEvents.ts

@@ -39,6 +39,8 @@ export type AutomaticEventName =
 export interface AutomaticEvent {
     name: AutomaticEventName;
     properties: Record<string, unknown>;
+    /** Original observation time. Delivery can be delayed while native coordinates resolve. */
+    timestamp?: number;
 }
 
 type AutomaticEventListener = (event: AutomaticEvent) => void;
@@ -60,10 +62,12 @@ function compactProperties(
 export function emitAutomaticEvent(
     name: AutomaticEventName,
     properties?: Record<string, unknown>,
+    timestamp?: number,
 ): void {
     const event: AutomaticEvent = {
         name,
         properties: compactProperties(properties),
+        timestamp,
     };
     if (listeners.size === 0) {
         pending.push(event);

package/src/core/constants/version.ts

@@ -1,6 +1,11 @@
 /**
  * ScaleBun SDK version. Sent with the session-start envelope so the dashboard
  * can attribute telemetry to the SDK build that produced it.
- * Keep in sync with package.json "version".
+ * Keep in sync with package.json "version" — `version.test.ts` fails when they drift.
+ *
+ * Why the test matters: the 1.11.0 bump missed this line, so the build would have reported itself as
+ * 1.10.6. Every "is the release live, and on what share of traffic" question is answered from this
+ * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
+ * version was introduced to solve.
  */
-export const SDK_VERSION = '1.10.7';
+export const SDK_VERSION = '1.11.1';