@scalebun/react-native 1.10.6 → 1.11.0

package/src/features/session/JourneyEventPipeline.ts

@@ -93,31 +93,33 @@ export class JourneyEventPipeline {
             journeyId?: string;
             /** Frame that was on screen when this happened. Resolved by the caller; see sessionTypes. */
             frameId?: string;
+            timestamp?: number;
         },
     ): JourneyEvent | null {
         try {
             const key = `${type}:${opts?.subtype ?? ''}`;
-            const now = Date.now();
-            if (key === this.lastEventKey && (now - this.lastEventTs) < this.config.dedupeWindowMs) {
+            const receivedAt = Date.now();
+            const occurredAt = opts?.timestamp ?? receivedAt;
+            if (key === this.lastEventKey && (receivedAt - this.lastEventTs) < this.config.dedupeWindowMs) {
                 // Within dedup window — allow high-confidence native events to
                 // REPLACE a prior low-confidence JS event for the same gesture.
                 // This prevents the race where JS fires first and the pipeline
                 // drops the native event that has more accurate coordinates.
                 const incomingConfidence = (opts?.payload as any)?.confidence;
                 if (incomingConfidence === 'high' && this.lastEventConfidence !== 'high') {
-                    this._replaceLastEvent(key, now, opts);
+                    this._replaceLastEvent(key, receivedAt, opts);
                 }
                 return null;
             }
             this.lastEventKey = key;
-            this.lastEventTs = now;
+            this.lastEventTs = receivedAt;
             this.lastEventConfidence = (opts?.payload as any)?.confidence ?? null;
 
             const event: JourneyEvent = {
                 eventId: generateEventId(),
                 sessionId: this.sessionId,
                 journeyId: opts?.journeyId,
-                ts: now,
+                ts: occurredAt,
                 type,
                 subtype: opts?.subtype,
                 severity: opts?.severity ?? inferSeverity(type),

package/src/features/session/SessionManager.ts

@@ -41,16 +41,16 @@ import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
 import { redactBody } from '../../debug/redaction';
 import { consumeCalibrationTarget } from '../journey/calibrationContext';
 import { resolvePlatformOS } from '../../core/context/device';
+import { emitAutomaticEvent } from '../../analytics/automaticEvents';
+import {
+    INTERACTION_PROTOCOL_VERSION,
+    automaticInteractionProperties,
+    generateInteractionId,
+    type InteractionStateStatus,
+} from '../journey/interactionProtocol';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
-/**
- * Max analytics-lane heatmap interactions emitted per foreground (analytics
- * session) window. Bounds ingest volume now that capture defaults ON; enough to
- * resolve hotspot density, the long tail is dropped (drop-newest beyond cap).
- */
-const HEATMAP_MAX_INTERACTIONS_PER_WINDOW = 200;
-
 export interface SessionManagerConfig {
     sessionReplay?: Partial<SessionReplayConfig>;
     syncPolicy?: SyncDecisionCallback;
@@ -84,16 +84,6 @@ export class SessionManager {
      * lane even when no replay recording is active. Additive, opt-in (default off).
      */
     private _captureInteractionHeatmap = false;
-    /**
-     * 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: string | null = null;
-    private _heatmapWindowCount = 0;
-
     private session: Session | null = null;
     private active = false;
     private timeoutTimer: ReturnType<typeof setTimeout> | null = null;
@@ -740,21 +730,16 @@ export class SessionManager {
      *     injected sensitive keys (e.g. a label) are stripped before transport.
      *   - Never throws.
      */
-    private _emitInteractionToAnalytics(gestureType: string, payload: Record<string, unknown>): void {
-        if (!this._captureInteractionHeatmap) return;
-        if (this.active) return; // recording lane already carries this tap
+    private _emitInteractionToAnalytics(
+        gestureType: string,
+        payload: Record<string, unknown>,
+        occurredAt: number,
+        screenName?: string,
+    ): boolean {
+        if (!this._captureInteractionHeatmap) return false;
+        if (this.active) return false; // recording lane already carries this tap
         const adapter = this._backendTransport;
-        if (!adapter) return;
-
-        // Per-foreground sampling cap. Reset the counter when the analytics
-        // session window rolls over, then drop anything past the cap.
-        const windowId = adapter.analyticsSessionId ?? '';
-        if (windowId !== this._heatmapWindowSessionId) {
-            this._heatmapWindowSessionId = windowId;
-            this._heatmapWindowCount = 0;
-        }
-        if (this._heatmapWindowCount >= HEATMAP_MAX_INTERACTIONS_PER_WINDOW) return;
-        this._heatmapWindowCount++;
+        if (!adapter) return false;
 
         try {
             // Normalize coords in place (same logic as the recording lane).
@@ -782,16 +767,18 @@ export class SessionManager {
                 eventId: generateEventId(),
                 // sessionId is (re)stamped by the analytics lane at flush time.
                 sessionId: adapter.analyticsSessionId ?? '',
-                ts: Date.now(),
+                ts: occurredAt,
                 type: 'USER_ACTION',
                 subtype: `gesture:${gestureType}`,
-                screen: this._lastKnownScreen ?? undefined,
+                screen: screenName ?? this._lastKnownScreen ?? undefined,
                 payload: safePayload,
                 source: 'user',
             };
             adapter.trackEvent(event);
+            return true;
         } catch (err) {
             logger.error('[SessionManager] heatmap analytics emit failed:', err);
+            return false;
         }
     }
 
@@ -810,6 +797,8 @@ export class SessionManager {
             traceId?: string;
             source?: JourneyEventSource;
             journeyId?: string;
+            /** Original observation time; interaction capture may resolve asynchronously. */
+            timestamp?: number;
         },
     ): void {
         if (!this.active) return;
@@ -1046,13 +1035,18 @@ export 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 {
         if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
         this.emitEvent('USER_ACTION', {
             subtype,
-            screen: this._lastKnownScreen ?? undefined,
+            screen: context?.screen ?? this._lastKnownScreen ?? undefined,
             payload,
             source: 'user',
+            timestamp: context?.timestamp,
         });
         // NOTE: Do NOT call captureManager.onInteraction() here.
         // emitEvent() already triggers onInteraction() for USER_ACTION events (line ~405).
@@ -1103,11 +1097,22 @@ export 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 {
         // Exact-duplicate suppression — see _lastGestureSig. Signature is the gesture type plus
         // raw coordinates verbatim; String() keeps undefined coords distinct from 0 (a payload
         // with no coords never collides with a real origin tap).
-        const dedupSig = `${gestureType}|${String(details?.x)}|${String(details?.y)}|${String(details?.endX)}|${String(details?.endY)}`;
+        const suppliedInteractionId = details?.interactionId;
+        const dedupSig = suppliedInteractionId
+            ? `id:${suppliedInteractionId}`
+            : `${gestureType}|${String(details?.x)}|${String(details?.y)}|${String(details?.endX)}|${String(details?.endY)}`;
         const nowTs = Date.now();
         if (
             dedupSig === this._lastGestureSig &&
@@ -1122,7 +1127,15 @@ export class SessionManager {
         // Build the canonical gesture payload ONCE so the recording lane and the
         // (additive) analytics lane carry byte-identical keys (normalizedX/Y,
         // gestureType, etc.). Same object shape that was previously inlined.
+        const interactionId = suppliedInteractionId ?? generateInteractionId();
+        const occurredAt = details?.occurredAt ?? Date.now();
+        const stateStatus = details?.stateStatus ?? (details?.ui ? 'captured_nonempty' : 'not_captured');
         const payload: Record<string, unknown> = {
+            interaction_id: interactionId,
+            interaction_protocol: details?.interactionProtocol ?? INTERACTION_PROTOCOL_VERSION,
+            state_status: stateStatus,
+            ui: details?.ui,
+            target_id: details?.targetId,
             gestureType,
             x: details?.x,
             y: details?.y,
@@ -1167,7 +1180,27 @@ export class SessionManager {
         // when the flag is OFF, no backend transport is attached, or recording is
         // active (the recording path below already carries this tap). Uses a fresh
         // payload clone so analytics normalization never mutates the recording one.
-        this._emitInteractionToAnalytics(gestureType, { ...payload });
+        const analyticsReplayCarrier = this._emitInteractionToAnalytics(
+            gestureType,
+            { ...payload },
+            occurredAt,
+            details?.screenName,
+        );
+        const replayCarrier = !!this._backendTransport && (this.active || analyticsReplayCarrier);
+        if (details?.emitAutomaticAnalytics) {
+            try {
+                const safePayload = redactBody(payload) as Record<string, unknown>;
+                emitAutomaticEvent(
+                    'element_interacted',
+                    automaticInteractionProperties(
+                        safePayload,
+                        details?.screenName ?? this._lastKnownScreen ?? undefined,
+                        replayCarrier,
+                    ),
+                    occurredAt,
+                );
+            } catch { /* automatic projection must never affect interaction capture */ }
+        }
 
         if (!this.active) return; // Defense-in-depth: no emission when recording is OFF
         // The subtype becomes `ReplayEvent.label`, which is what the Events explorer GROUPS BY. Naming
@@ -1178,7 +1211,11 @@ export class SessionManager {
         // ⚠️ `gestureType` also travels in the payload, and the backend's `resolveGesture` reads THAT
         // first — so enriching the label cannot change heatmap gesture classification.
         const target = typeof details?.target === 'string' ? details.target.trim() : '';
-        this.onUserAction(target ? `gesture:${gestureType} · ${target}` : `gesture:${gestureType}`, payload);
+        this.onUserAction(
+            target ? `gesture:${gestureType} · ${target}` : `gesture:${gestureType}`,
+            payload,
+            { screen: details?.screenName, timestamp: occurredAt },
+        );
     }
 
     /**

package/src/metro/serializerCompose.ts

@@ -106,6 +106,9 @@ export function discoverArtifacts(packageRoot: string): ArtifactMapping[] {
     return out;
 }
 
+/** One-shot guard so an Expo build does not print the pass-through notice per bundle. */
+let warnedUnknownShape = false;
+
 /**
  * Build the composing serializer. `hostSerializer` is the app's own customSerializer, if any.
  */
@@ -122,10 +125,43 @@ export function createComposingSerializer(
             const hostResult = await hostSerializer(entryPoint, preModules, graph, options);
             if (typeof hostResult === 'string') {
                 code = hostResult;
+            } else if (hostResult && typeof (hostResult as any).code !== 'string') {
+                /**
+                 * A shape this wrapper does not understand — pass it back UNTOUCHED.
+                 *
+                 * Expo is the case that matters. `expo/metro-config` installs a
+                 * serializer returning `{ artifacts: [...] }`, a multi-artifact
+                 * shape with no top-level `code`. Reading `.code` off it yielded
+                 * undefined, and returning `{ code: undefined, map }` made every
+                 * `expo export:embed` die with:
+                 *
+                 *   Serializer did not return expected format. The project copy
+                 *   of `expo/metro-config` may be out of date.
+                 *
+                 * — a message that sends you to upgrade Expo, which is not the
+                 * problem. The result: `withScaleBun` broke PRODUCTION BUNDLING
+                 * FOR EVERY EXPO APP, and the SDK's own marketing test app could
+                 * not build. Found by bundling it.
+                 *
+                 * Passing it through costs ScaleBun's source-map composition on
+                 * Expo (OTA stack traces stay mapped to the bundle rather than to
+                 * original sources). That is a real loss and strictly better than
+                 * a build that cannot run at all. Composing INTO an artifact
+                 * array is the follow-up; it must not be guessed at here.
+                 */
+                if (!warnedUnknownShape) {
+                    warnedUnknownShape = true;
+                    console.warn(
+                        '[ScaleBun/metro] The host serializer returned a shape this SDK does not ' +
+                            'compose (Expo returns { artifacts }). Passing it through unchanged — ' +
+                            'the build is correct, but ScaleBun source-map composition is skipped.',
+                    );
+                }
+                return hostResult as never;
             } else {
-                code = hostResult.code;
+                code = (hostResult as { code: string; map: string }).code;
                 try {
-                    mapObj = JSON.parse(hostResult.map);
+                    mapObj = JSON.parse((hostResult as { code: string; map: string }).map);
                 } catch {
                     // Host emitted an unparsable map; fall through and rebuild from the graph so
                     // the build still succeeds with a correct map rather than failing here.

package/src/public/ScaleBunFacade.ts

@@ -275,12 +275,17 @@ class ScaleBunFacade {
     /**
      * Boot the OTA orchestrator when the init config asks for it.
      *
-     * `publicSigningKey` is honoured here so signature enforcement is reachable
-     * from configuration alone. The SDK ships no ed25519 implementation, so a
-     * host that pins a key must also supply `ota.verifySignature`; pinning a key
-     * without a verifier is fail-CLOSED by design (signature.ts) — an update
-     * that cannot be verified is not installed. We say that out loud rather than
-     * letting the app discover it as a silent no-update condition.
+     * `publicSigningKey` / `publicSigningKeys` are honoured here so signature
+     * enforcement is reachable from configuration alone. The list form exists
+     * for key ROTATION: a build pinning [old, new] keeps verifying while the
+     * server moves to the new key, so replacing a key never needs an emergency
+     * store release. Both fields merge (deduplicated) into one pinned set.
+     *
+     * Verification comes from `ota.verifySignature` when supplied, else the
+     * built-in @noble-based verifier (optional peers). Pinning keys with
+     * NEITHER available is fail-CLOSED by design (signature.ts) — an update
+     * that cannot be verified is not installed. We say that out loud rather
+     * than letting the app discover it as a silent no-update condition.
      */
     private _maybeStartOta(rawConfig: any): void {
         const ota = rawConfig?.ota;
@@ -290,16 +295,49 @@ class ScaleBunFacade {
             // module (or touch the native spec) at import time.
             // eslint-disable-next-line @typescript-eslint/no-var-requires
             const { otaOrchestrator } = require('../features/ota/OtaOrchestrator');
-            const publicKey = ota.publicSigningKey;
+            const rawSingle = ota.publicSigningKey;
+            const rawList = ota.publicSigningKeys;
+            const publicKeys = Array.from(
+                new Set(
+                    [
+                        ...(typeof rawSingle === 'string' && rawSingle ? [rawSingle] : []),
+                        ...(Array.isArray(rawList) ? rawList : []),
+                    ].filter((k: unknown): k is string => typeof k === 'string' && k.trim().length > 0),
+                ),
+            );
+            // Signing was REQUESTED if a usable key exists, or the host passed a
+            // keys array at all — an empty one included. `publicSigningKeys: []`
+            // is a broken attempt to enable signing, and it must flow through to
+            // signature.ts's fail-closed handling, not silently disable signing.
+            const signingRequested = publicKeys.length > 0 || Array.isArray(rawList);
             const verifier = ota.verifySignature;
-            if (publicKey && typeof verifier !== 'function') {
-                logger.warn(
-                    '[ScaleBun] ota.publicSigningKey is set but ota.verifySignature is not a function. ' +
-                        'Signature checking is fail-closed: updates will be REJECTED until a verifier is supplied.',
-                );
+            if (signingRequested && typeof verifier !== 'function') {
+                // A host verifier is optional since the built-in one landed — the
+                // old unconditional warning here told every correctly-configured
+                // app that its updates would be rejected. Warn only when neither
+                // verifier can actually be resolved.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { getBuiltinVerifier } = require('../features/ota/crypto/builtinVerifier');
+                if (!getBuiltinVerifier()) {
+                    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`.',
+                    );
+                }
             }
             otaOrchestrator.init({
-                ...(publicKey ? { signature: { publicKey, verifier } } : {}),
+                ...(signingRequested
+                    ? {
+                          signature: {
+                              // Single key stays a plain string — the shape every
+                              // existing consumer and test already handles.
+                              publicKey: publicKeys.length === 1 ? publicKeys[0] : publicKeys,
+                              verifier,
+                          },
+                      }
+                    : {}),
                 ...(typeof ota.healthyTimeoutMs === 'number'
                     ? { healthyTimeoutMs: ota.healthyTimeoutMs }
                     : {}),
@@ -526,6 +564,42 @@ class ScaleBunFacade {
     }
 
     /** Convenience: emit a Phase 1 purchase event (revenue + currency + transaction_id). */
+    /**
+     * Declare which UI state the user is looking at, so taps are attributed to the surface they
+     * happened on rather than averaged across every variant of the screen.
+     *
+     *     ScaleBun.setUiState('filter-sheet', 'open');
+     *     ScaleBun.setUiState('checkout-step', 'payment');
+     *
+     * Call it when the state CHANGES — the value is read at tap time, so it only has to be right by
+     * the time the next tap lands. On React Native this is the ONLY source of UI state: unlike the web,
+     * there is no queryable accessibility tree that says a sheet is up, and guessing would produce a
+     * state key that is right on some apps and silently wrong on others.
+     *
+     * Names and values are identifiers, not content: they become query keys in the dashboard, so a
+     * person's name or a cart total does not belong in one. `;`, `:` and `|` are stripped and both
+     * halves are capped at 32 characters.
+     */
+    public setUiState(name: string, value: string): void {
+        try {
+            const { setUiState } = require('../features/journey/uiState');
+            setUiState(name, value);
+        } catch { /* no-throw: a state declaration must never break the host */ }
+    }
+
+    /**
+     * Stop reporting a UI state dimension — or, with no argument, all of them.
+     *
+     * Clear on screen unmount. A declaration left behind follows the user onto a surface where it means
+     * nothing, and every tap there is filed under a state that was not on screen.
+     */
+    public clearUiState(name?: string): void {
+        try {
+            const { clearUiState } = require('../features/journey/uiState');
+            clearUiState(name);
+        } catch { /* no-throw */ }
+    }
+
     public trackPurchase(input: { revenue: number; currency: string; transactionId: string; [k: string]: any }): void {
         noThrow(() => this._eventTracker?.trackPurchase(input));
     }

package/src/specs/NativeScaleBunOta.ts

@@ -85,6 +85,30 @@ export interface Spec extends TurboModule {
    * `recreateReactContextInBackground()` (bridge). iOS: RCTReloadCommand.
    */
   restartApp(): void;
+
+  /**
+   * Verify a detached ed25519 signature in NATIVE code.
+   *
+   * Exists because the JS verifier runs inside the very bundle it protects —
+   * an attacker who lands one malicious bundle can neuter a JS check for every
+   * update after it. Platform crypto is outside the bundle's reach, and it also
+   * removes the runtime dependency on the optional @noble peers wherever the OS
+   * provides ed25519 (iOS 13+ CryptoKit everywhere; Android API 33+).
+   *
+   * All three arguments are lowercase hex, pre-validated by the JS caller:
+   * the 32-byte bundle SHA-256 (the signature is over its RAW BYTES, matching
+   * the CLI's signing contract), the 64-byte signature, the 32-byte public key.
+   *
+   * Resolves a verdict STRING, not a boolean, because "the signature is wrong"
+   * and "this OS cannot check" must never collapse into one value:
+   *   'valid'       — signature verifies under the key
+   *   'invalid'     — it does not; the caller must refuse the bundle
+   *   'unavailable' — this OS level has no ed25519 (Android < 33); the caller
+   *                   falls back to the JS verifier
+   * A rejected promise is machinery failure and the caller treats it as
+   * 'unavailable' — never as 'valid'.
+   */
+  verifyEd25519(messageHex: string, signatureHex: string, publicKeyHex: string): Promise<string>;
 }
 
 /**