@scalebun/react-native 1.0.3 → 1.0.4

package/src/features/ota/geoCountry.ts

@@ -0,0 +1,85 @@
+import { createStorageBackend } from '../../storage/StorageBackend';
+import { logger } from '../../core/logger/internalLogger';
+
+/**
+ * Device country via an edge Worker — the workaround for an API that is not
+ * behind a geo-stamping CDN.
+ *
+ * The clean architecture is the API itself resolving `cf-ipcountry` at its own
+ * edge (see backend `resolveCountry`) — the device can't forge it and every
+ * request carries it. When the API record isn't proxied, that header never
+ * exists, so this module asks a Cloudflare Worker (which DOES see the device's
+ * edge geo) and attaches the answer to the OTA check payload. Host-supplied
+ * country always wins; the server treats a client country as locale-grade, not
+ * proof of location.
+ *
+ * Failure-soft by design: a dead Worker, a timeout, or a bad payload leaves the
+ * country unset — an unknown country must render as unknown, never be guessed.
+ */
+
+/** Default lookup endpoint. Overridable via {@link setGeoEndpoint}. */
+const DEFAULT_GEO_ENDPOINT = 'https://get-location.imohamadfahmy.workers.dev/';
+
+const K_COUNTRY = 'scalebun.ota.geoCountry';
+const K_FETCHED_AT = 'scalebun.ota.geoCountryAt';
+const TTL_MS = 24 * 60 * 60 * 1000; // countries change when people travel — daily is plenty
+const TIMEOUT_MS = 2500;
+
+/** Cloudflare's non-countries: Tor exits and internal probes. Unknown, not a place. */
+const NON_COUNTRIES = new Set(['XX', 'T1', 'ZZ']);
+
+let endpoint = DEFAULT_GEO_ENDPOINT;
+let memory: string | null = null;
+let inFlight: Promise<void> | null = null;
+const storage = createStorageBackend();
+
+/** Override the lookup endpoint (e.g. a self-hosted Worker). */
+export function setGeoEndpoint(url: string): void {
+    endpoint = url;
+}
+
+/**
+ * Synchronous read of the cached country (uppercase ISO 3166-1 alpha-2), or
+ * null when no fresh lookup has ever succeeded. Never triggers network.
+ */
+export function getDeviceCountry(): string | null {
+    if (memory) return memory;
+    const stored = storage.get(K_COUNTRY);
+    const at = parseInt(storage.get(K_FETCHED_AT) ?? '0', 10) || 0;
+    if (stored && Date.now() - at < TTL_MS) {
+        memory = stored;
+        return stored;
+    }
+    return null;
+}
+
+/**
+ * Refresh the cache from the Worker if stale. Fire-and-forget: call it at
+ * orchestrator init; the first check of a cold install may go out without a
+ * country (the server stores the country per device on later checks anyway).
+ */
+export function prefetchDeviceCountry(): Promise<void> {
+    if (getDeviceCountry()) return Promise.resolve(); // fresh — nothing to do
+    if (inFlight) return inFlight;
+    inFlight = (async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        try {
+            const res = await fetch(endpoint, { signal: controller.signal });
+            if (!res.ok) return;
+            const body = (await res.json()) as { country?: unknown };
+            const raw = typeof body?.country === 'string' ? body.country.trim().toUpperCase() : '';
+            if (!/^[A-Z]{2}$/.test(raw) || NON_COUNTRIES.has(raw)) return;
+            memory = raw;
+            storage.set(K_COUNTRY, raw);
+            storage.set(K_FETCHED_AT, String(Date.now()));
+            logger.debug(`[OTA] Device country resolved: ${raw}`);
+        } catch (err: any) {
+            logger.debug(`[OTA] Geo lookup skipped: ${err?.message ?? err}`);
+        } finally {
+            clearTimeout(timer);
+            inFlight = null;
+        }
+    })();
+    return inFlight;
+}

package/src/features/ota/useOtaUpdate.ts

@@ -7,7 +7,22 @@ export interface UseOtaUpdateOptions {
   apiUrl: string;
   clientKey: string;
   appVersion: string;
-  installationId: string;
+  /**
+   * Omit to use the SDK's canonical per-install id (recommended). Supplying a
+   * different id here — the old docs suggested `deviceId` — put OTA telemetry
+   * in its own identity namespace, disconnected from every other SDK lane.
+   */
+  installationId?: string;
+  /** OTA channel to pull from. Omitted means `default`. */
+  channelName?: string;
+  /** ISO 3166-1 alpha-2. The server resolves this from the edge when absent. */
+  country?: string;
+  /** Free-form device attributes evaluated by ATTRIBUTE targeting rules. */
+  attributes?: Record<string, string | number>;
+  /** CDP segment ids this installation belongs to. */
+  segmentIds?: string[];
+  /** Lifecycle stage evaluated by LIFECYCLE_STAGE targeting rules. */
+  lifecycleStage?: string;
   autoRestart?: boolean;
   /**
    * When true and the server says `isMandatory`, the hook sets
@@ -49,7 +64,10 @@ export interface UseOtaUpdateReturn {
  *   apiUrl: 'https://api.scalebun.com/api/v1',
  *   clientKey: 'scalebun_ck_…',
  *   appVersion: '1.0.0',
- *   installationId: deviceId,
+ *   // installationId is resolved from the SDK's own persisted install id —
+ *   // do NOT pass deviceId here (the old example did; it split OTA telemetry
+ *   // into a separate identity namespace from every other lane).
+ *   channelName: 'production',
  *   mandatoryBlocksUi: true,
  * });
  * ```

package/src/features/performance/PerformanceFeature.ts

@@ -71,7 +71,6 @@ export class PerformanceFeature implements IFeature {
     private static readonly CAPTURE_DELAYS = [300, 600, 1200];
 
     // Track event function from SDK pipeline
-    private trackFn: ((name: string, payload?: Record<string, unknown>) => void) | null = null;
 
     constructor(config?: Partial<PerformanceConfig>) {
         this.config = mergePerformanceConfig(config);
@@ -208,7 +207,6 @@ export class PerformanceFeature implements IFeature {
     async initialize(context: FeatureContext): Promise<void> {
         if (this.active || !this.config.enabled) return;
 
-        this.trackFn = context.trackEvent;
         this.active = true;
 
         // Activate native performance collectors (Android AppStart/Frame/ANR,
@@ -549,13 +547,28 @@ export class PerformanceFeature implements IFeature {
         // Send to debug transport
         this.transport.sendEvent(event);
 
-        // Also track through SDK pipeline (for backend ingestion)
-        if (this.trackFn) {
-            this.trackFn('$perf_event', {
-                perfType: event.type,
-                ...event,
-            });
-        }
+        /**
+         * REMOVED: a duplicate `$perf_event` through the analytics/event pipeline.
+         *
+         * This claimed to be "for backend ingestion", but the `queuePerformanceMetric` call below is
+         * the backend ingestion path — it writes the dedicated `performance_metrics` table, and that
+         * is what EVERY consumer reads: `perf-aggregate.ch.ts` (FPS, frameMetricsSessions), the
+         * Monitor low-FPS KPI, the page-load RenderingPanel and the Replay Inspector's FPS readout.
+         * Nothing in the backend or the dashboard reads `$perf_event` — verified by search.
+         *
+         * So this line wrote every perf sample a SECOND time, into the event lane, where it landed as
+         * `USER_ACTION` and was counted as a user interaction. Measured in production:
+         *
+         *     performance_metrics.frame_metrics   75,278   ← read by everything
+         *     replay_events (as USER_ACTION)      47,019   ← read by nothing
+         *
+         * `USER_ACTION` was 99% of all mobile events (62,026 of ~62,600), and only 980 of those
+         * carried real gesture data. One session showed 4,735 events against SIX real gestures. That
+         * made session event counts meaningless and polluted anything counting user interactions.
+         *
+         * Dropping it loses no data and no feature — the perf lane's copy is the more complete one —
+         * and it costs a duplicate serialize + upload per sample on every session.
+         */
 
         // Queue to SaaS backend dedicated performance endpoint
         const backendTransport = SessionManager.getExistingInstance()?.getBackendTransport();

package/src/features/performance/collectors/FrameMetricsCollector.ts

@@ -11,7 +11,7 @@
  * - Emits FrameMetricsEvent for transport
  */
 
-import { NativeEventEmitter } from 'react-native';
+import { AppState, NativeEventEmitter, type NativeEventSubscription } from 'react-native';
 import { getNativePerformanceModule } from '../getNativePerformanceModule';
 import type { FrameMetricsEvent, PerfContext } from '../models';
 import { PERF_SCHEMA_VERSION } from '../models';
@@ -25,6 +25,10 @@ export class FrameMetricsCollector {
     private contextProvider: () => PerfContext;
     private eventSubscription: any = null;
     private running = false;
+    /** AppState subscription — see `_installAppStateGate`. */
+    private appStateSubscription: NativeEventSubscription | null = null;
+    /** True while the native sampler is actually running (i.e. armed AND foregrounded). */
+    private sampling = false;
 
     constructor(
         config: PerformanceConfig,
@@ -56,22 +60,64 @@ export class FrameMetricsCollector {
                 },
             );
 
-            // Tell native module to start collecting frame metrics
-            if (typeof perfModule.startFrameMetrics === 'function') {
-                perfModule.startFrameMetrics(this.config.reportIntervalMs);
-            }
+            this._startNativeSampler();
+            this._installAppStateGate();
         } catch {
             // Native module not available — graceful degradation
         }
     }
 
-    stop(): void {
-        this.running = false;
-        if (this.eventSubscription) {
-            this.eventSubscription.remove();
-            this.eventSubscription = null;
+    /**
+     * Pause sampling while the app is backgrounded.
+     *
+     * THE BUG THIS FIXES. `startFrameMetrics` hands off to a native loop that runs until something
+     * calls `stopFrameMetrics`. Nothing did. The collector had no AppState awareness at all — unlike
+     * `AutoScreenLoadCollector`, which has subscribed to it since it was written — so once a session
+     * was sampled in, it kept sampling for as long as the PROCESS lived, not as long as the app was
+     * being used.
+     *
+     * Measured in production: sessions with `durationMs` of 86,400,000 (exactly 24h) and 70,797,000
+     * (~19.7h) carrying 39,766 and 3,709 frame samples against 0 and 6 real gestures respectively.
+     * `frame_metrics` was 75% of ALL mobile events for this reason.
+     *
+     * The `tier2SampleRate` knob does not help here: it gates WHICH sessions collect, not how long
+     * they collect for. A sampled-in session that gets backgrounded still samples for hours, which is
+     * why lowering it would have hidden the symptom while leaving the cause.
+     *
+     * It is also a DATA-QUALITY fix, not only a volume one. Frame timings from a backgrounded app
+     * describe a screen nobody is looking at, and they were feeding the low-FPS KPI and jank
+     * detection — so the noise was not merely stored, it was being reported as UI performance.
+     *
+     * NOTE: on iOS the OS already stops delivering CADisplayLink callbacks on background, so the
+     * practical effect is largest on Android. Gating in JS keeps the two platforms behaving the same
+     * either way, rather than relying on an OS side effect that is not part of any contract.
+     */
+    private _installAppStateGate(): void {
+        if (this.appStateSubscription) return;
+        this.appStateSubscription = AppState.addEventListener('change', (next) => {
+            if (!this.running) return; // stop() already tore us down
+            if (next === 'active') this._startNativeSampler();
+            else this._stopNativeSampler(); // 'background' and 'inactive' (iOS call/app-switcher)
+        });
+    }
+
+    /** Idempotent — AppState can fire 'active' more than once without an intervening background. */
+    private _startNativeSampler(): void {
+        if (this.sampling) return;
+        try {
+            const perfModule = getNativePerformanceModule();
+            if (typeof perfModule?.startFrameMetrics === 'function') {
+                perfModule.startFrameMetrics(this.config.reportIntervalMs);
+                this.sampling = true;
+            }
+        } catch {
+            // No-throw: a perf collector must never break the host app.
         }
+    }
 
+    private _stopNativeSampler(): void {
+        if (!this.sampling) return;
+        this.sampling = false;
         try {
             const perfModule = getNativePerformanceModule();
             if (typeof perfModule?.stopFrameMetrics === 'function') {
@@ -82,6 +128,22 @@ export class FrameMetricsCollector {
         }
     }
 
+    stop(): void {
+        this.running = false;
+        if (this.eventSubscription) {
+            this.eventSubscription.remove();
+            this.eventSubscription = null;
+        }
+        // Remove the AppState listener BEFORE stopping the sampler: a 'change' arriving mid-teardown
+        // would otherwise restart the native loop on a collector that is being shut down, which is the
+        // same leak this gate exists to close.
+        if (this.appStateSubscription) {
+            this.appStateSubscription.remove();
+            this.appStateSubscription = null;
+        }
+        this._stopNativeSampler();
+    }
+
     private _handleNativeFrameMetrics(data: any): void {
         if (!data || typeof data.totalFrames !== 'number') return;
 

package/src/features/performance/transport/PerformanceTransport.ts

@@ -68,6 +68,24 @@ export class PerformanceTransport {
 
     /** Send a metric value (for backward compat with existing metric handler) */
     sendMetric(name: string, value: number, unit?: string, tags?: Record<string, string>): void {
+        // D4: the desktop sink is only wired under enableDebug(), so in a
+        // production build everything through here — JS stall stats, launch
+        // timings, and the PUBLIC ScaleBun.sendMetric() API — was buffered into
+        // a bounded array and discarded. Mirror every metric onto the backend
+        // ingestion lane (the one that provably lands rows); the desktop sink
+        // remains the dev-tooling fan-out below.
+        try {
+            // Lazy import avoids a static cycle: session → performance → session.
+            const { SessionManager } = require('../../session/SessionManager');
+            const backend = SessionManager.getExistingInstance()?.getBackendTransport();
+            backend?.queuePerformanceMetric({
+                type: name,
+                value,
+                metadata: { ...(unit ? { unit } : {}), ...(tags ?? {}) },
+            });
+        } catch {
+            // Backend lane unavailable (no session yet) — dev sink may still get it.
+        }
         const msg = {
             type: 'metric' as const,
             protocolVersion: PROTOCOL_VERSION,

package/src/features/session/BackendSessionAdapter.ts

@@ -258,6 +258,7 @@ export class BackendSessionAdapter implements SessionTransport {
         bridgeAdapter.getDeviceInfo()
             .then(nativeInfo => {
                 const m = session.metadata;
+                this._cachedAppVersion = nativeInfo?.appVersion ?? m?.appVersion ?? null;
                 const payload = {
                     sessionId: session.sessionId,
                     deviceId: session.deviceId,
@@ -394,6 +395,7 @@ export class BackendSessionAdapter implements SessionTransport {
         try {
             const nativeInfo = await bridgeAdapter.getDeviceInfo();
             const m = session.metadata;
+            this._cachedAppVersion = nativeInfo?.appVersion ?? m?.appVersion ?? null;
             const payload = {
                 sessionId: session.sessionId,
                 deviceId: session.deviceId,
@@ -639,18 +641,56 @@ export class BackendSessionAdapter implements SessionTransport {
         }
     }
 
+    // D8/D9/D12: this signature was {type, message, stack, screenName} — four
+    // fields — while the backend row and every dashboard surface were already
+    // built for the rest. The consequences of the four-field bottleneck:
+    // regression detection permanently false (no appVersion on any mobile
+    // error), Issue.primaryPlatform NULL for every RN crash (no platform), and
+    // native crash signal/thread/exception-type discarded one call before the
+    // wire (no metadata). The receiver needed nothing; only this signature did.
+    /** App version resolved at session start; errors stamp it so regression
+     *  detection has a version to work with (D8). Null until a session starts. */
+    private _cachedAppVersion: string | null = null;
+
+    private _appVersion(): string | undefined {
+        return this._cachedAppVersion ?? undefined;
+    }
+
     queueError(data: {
         type: string; message: string; stack?: string; screenName?: string;
+        platform?: string;
+        appVersion?: string;
+        isFatal?: boolean;
+        metadata?: Record<string, unknown>;
+        /** Target session. Set ONLY by a recovered native crash; absent means the current session. */
+        sessionId?: string;
+        /** Stable idempotency key. Set ONLY by a recovered crash; the backend dedupes on it. */
+        clientId?: string;
     }): void {
         if (this.destroyed || !this.config.clientKey) return;
-        this.pendingErrors.push({ ...data, clientId: this._clientId(), timestamp: new Date().toISOString() });
+        this.pendingErrors.push({
+            ...data,
+            // The session already knows the app version — never make a crash
+            // reporter's callers supply what the transport can fill itself.
+            appVersion: data.appVersion ?? this._appVersion(),
+            // A recovered crash brings its OWN clientId — the stable id written when the crash was
+            // first persisted. Generating a fresh one here would mint a new identity on every retry
+            // and defeat the unique constraint the backend dedupes with.
+            clientId: data.clientId ?? this._clientId(),
+            timestamp: new Date().toISOString(),
+        });
         if (this.pendingErrors.length >= 10) {
             this._flushErrors().catch(() => {});
         }
     }
 
-    /** Public: force-flush queued errors immediately (handled-error delivery). */
-    flushErrors(): Promise<void> {
+    /**
+     * Public: force-flush queued errors immediately (handled-error delivery).
+     *
+     * @returns whether the batch was DURABLY accepted. Crash recovery deletes its on-disk record on
+     *          this answer, so it must reflect the backend and not merely that the call returned.
+     */
+    flushErrors(): Promise<boolean> {
         return this._flushErrors();
     }
 
@@ -724,13 +764,23 @@ export class BackendSessionAdapter implements SessionTransport {
     private async _enqueueNative(
         lane: 'events' | 'network' | 'errors' | 'performance' | 'logs',
         records: Array<Record<string, unknown>>,
+        /**
+         * Session to enqueue UNDER. Defaults to the current one, which is right for every live lane.
+         *
+         * A recovered native crash must override it. Without this parameter the outbox stamped
+         * `currentSessionId` on everything, so with the outbox enabled a recovered crash was filed
+         * against the session created after the restart — the exact defect the routing above exists
+         * to prevent, reappearing through a path that routing never touched.
+         */
+        targetSessionId?: string,
     ): Promise<boolean> {
-        if (!this.nativeOutboxEnabled || !this.currentSessionId) return false;
+        const sessionId = targetSessionId || this.currentSessionId;
+        if (!this.nativeOutboxEnabled || !sessionId) return false;
         const native = getReplaySdkNative();
         if (!native?.enqueueOutboxRecords) return false;
         if (!(await this._ensureNativeOutbox(native))) return false;
         try {
-            return await native.enqueueOutboxRecords(lane, this.currentSessionId, records);
+            return await native.enqueueOutboxRecords(lane, sessionId, records);
         } catch {
             return false;
         }
@@ -852,6 +902,17 @@ export class BackendSessionAdapter implements SessionTransport {
         if (screen) out.screenName = screen;
         const label = e.subtype ?? e.type;
         if (label && label !== e.type) out.label = label;
+        /**
+         * THIS MAPPER ENUMERATES. Every field the wire carries has to be named here, so a field
+         * added to JourneyEvent and not added here is dropped silently — no error, no warning, and
+         * nothing downstream can tell the difference between "the SDK did not send it" and "the
+         * user never produced it". `frameId` was exactly that case: the column, the DTO field and
+         * the ingest write all existed already, and the value died on this line.
+         *
+         * Omitted when absent rather than sent as null, matching how screenName and label behave
+         * above — the v2 lean shape drops empty fields and the server reconstructs them.
+         */
+        if (e.frameId) out.frameId = e.frameId;
         const data = this._pruneEmpty(e.payload);
         if (data && Object.keys(data).length > 0) out.data = data;
         return out;
@@ -1265,15 +1326,81 @@ export class BackendSessionAdapter implements SessionTransport {
         }
     }
 
-    private async _flushErrors(): Promise<void> {
-        if (this.pendingErrors.length === 0 || !this.currentSessionId || !this.config.clientKey) return;
+    /**
+     * D11: deliver a bug report to the SAME ingest the web SDK uses
+     * (`POST /ingestion/sessions/:id/bug-reports`). Fire-and-forget with one
+     * retry deferral: RN previously had NO path to this endpoint at all —
+     * `reportBug()` emitted an analytics event no handler consumed, so the
+     * bug-reports page was empty forever for every RN app.
+     */
+    submitBugReport(report: { message: string; title?: string; email?: string }): void {
+        if (this.destroyed || !this.config.clientKey || !this.currentSessionId) return;
+        void this._post(
+            `/ingestion/sessions/${this.currentSessionId}/bug-reports`,
+            { ...report, timestamp: Date.now() },
+        ).catch(() => {
+            /* best-effort; the $bug_report analytics breadcrumb still records intent */
+        });
+    }
+
+    /**
+     * @returns TRUE only when every group in this batch was DURABLY accepted — an HTTP 2xx, or a
+     *          handoff to the native outbox, which is itself a persistent retrying queue.
+     *
+     * The return value is not cosmetic: `drainNativeCrash` deletes the on-disk crash record on the
+     * strength of it. This method used to return `void` and swallow its own errors in the catch
+     * below, so "the promise resolved" meant nothing at all — a failed POST looked exactly like a
+     * successful one, and the caller would have deleted the only durable copy of a crash that never
+     * arrived. Anything less than a real acknowledgement here reintroduces the loss this whole
+     * change exists to prevent.
+     */
+    private async _flushErrors(): Promise<boolean> {
+        if (this.pendingErrors.length === 0 || !this.currentSessionId || !this.config.clientKey) return false;
         const batch = this.pendingErrors.splice(0, 20);
         try {
-            if (await this._enqueueNative('errors', batch)) return;
-            if (!this._sessionRowReady()) { this.pendingErrors.unshift(...batch); return; }
-            await this._post(ENDPOINTS.INGESTION_ERRORS(this.currentSessionId), { errors: batch });
+            if (!this._sessionRowReady()) { this.pendingErrors.unshift(...batch); return false; }
+            /**
+             * ROUTED BY THE ERROR'S OWN SESSION, not by whichever session is current.
+             *
+             * A recovered native crash carries the id of the session it actually happened in — that
+             * process is gone, so the current session is the wrong owner. Sending it under
+             * `currentSessionId` is what marked a healthy session crashed and left the crashed one
+             * looking clean.
+             *
+             * The URL still carries a session because that is the established ingest shape; the
+             * error's own `sessionId` simply chooses WHICH one. Errors are grouped by their target
+             * so a batch mixing a recovered crash with live errors cannot drag the live ones onto
+             * the dead session.
+             */
+            const byTarget = new Map<string, typeof batch>();
+            for (const e of batch) {
+                const target = (e as { sessionId?: string }).sessionId || this.currentSessionId;
+                byTarget.set(target, [...(byTarget.get(target) ?? []), e]);
+            }
+            let allAccepted = true;
+            for (const [target, errors] of byTarget) {
+                // `sessionId` is a routing instruction, not payload — strip it so the stored row is
+                // byte-identical to one sent the ordinary way.
+                const cleaned = errors.map(({ sessionId: _s, ...rest }: any) => rest);
+
+                // The outbox is enqueued PER TARGET, so a recovered crash keeps its own session.
+                if (await this._enqueueNative('errors', cleaned, target)) continue;
+
+                try {
+                    await this._post(ENDPOINTS.INGESTION_ERRORS(target), { errors: cleaned });
+                } catch (err) {
+                    allAccepted = false;
+                    // A permanent error (4xx) will never succeed, so re-queuing it would spin
+                    // forever; anything else is worth another attempt.
+                    if (!BackendSessionAdapter._isPermanentHttpError(err)) {
+                        this.pendingErrors.unshift(...errors);
+                    }
+                }
+            }
+            return allAccepted;
         } catch (err) {
             if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingErrors.unshift(...batch);
+            return false;
         }
     }
 

package/src/features/session/JourneyEventPipeline.ts

@@ -91,6 +91,8 @@ export class JourneyEventPipeline {
             traceId?: string;
             source?: JourneyEventSource;
             journeyId?: string;
+            /** Frame that was on screen when this happened. Resolved by the caller; see sessionTypes. */
+            frameId?: string;
         },
     ): JourneyEvent | null {
         try {
@@ -120,6 +122,7 @@ export class JourneyEventPipeline {
                 subtype: opts?.subtype,
                 severity: opts?.severity ?? inferSeverity(type),
                 screen: opts?.screen,
+                frameId: opts?.frameId,
                 payload: opts?.payload,
                 correlationId: opts?.correlationId,
                 traceId: opts?.traceId,

package/src/features/session/ReplayCaptureManager.ts

@@ -36,6 +36,7 @@ import {
     getFrameRetentionPriority,
     QUALITY_PRESETS,
 } from './sessionTypes';
+import type { PlatformOS } from '../../core/context/device';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -70,7 +71,8 @@ export interface StagedFrameResult {
     frameHash: string;
     masked: boolean;
     timestamp: number;
-    platform: 'android' | 'ios';
+    // Widened: frames now carry the REAL Platform.OS instead of being relabelled 'android'.
+    platform: PlatformOS;
 }
 
 /** JS-authoritative frame metadata written to the outbox on commit. */
@@ -258,6 +260,15 @@ export class ReplayCaptureManager {
     private _lastKeyframeTs = 0;
     /** P2-5: frameId of the last emitted keyframe — delta base reference. */
     private _lastKeyframeId: string | null = null;
+    /**
+     * Screen the last emitted keyframe was captured on.
+     *
+     * Tracked alongside the id purely so `currentKeyframe()` can refuse to hand a frame to an
+     * event on a different screen. The id and timestamp alone cannot answer that, and a frame
+     * from the previous screen is worse than none — it attaches a tap to a photograph of
+     * somewhere else, which every layer downstream would then present with full confidence.
+     */
+    private _lastKeyframeScreen: string | null = null;
     /** P2-5: emitted frames since the last keyframe (keyframe-interval guard). */
     private _framesSinceKeyframe = 0;
 
@@ -275,6 +286,45 @@ export class ReplayCaptureManager {
 
     // ─── Public API ─────────────────────────────────────────────────────
 
+    /**
+     * The keyframe that is still showing, or null.
+     *
+     * Answers "which picture was the user looking at" for an event that is about to be emitted,
+     * so a tap can carry the id of the frame it happened ON. Read-only; captures nothing.
+     *
+     * TWO CONDITIONS, both refusals rather than approximations:
+     *
+     *   SAME SCREEN. A keyframe from the previous screen is not what the user was looking at.
+     *   Navigation evicts the pending capture rather than re-pointing it, so after a screen
+     *   change the newest keyframe genuinely belongs to somewhere else.
+     *
+     *   STILL FRESH. A screen mutates constantly — a list loads, a banner rotates, a sheet is
+     *   dismissed. Past `maxAgeMs` the stored picture stops being evidence of what is on screen,
+     *   and stale evidence presented as current is the failure mode this whole feature exists to
+     *   avoid. 10 s is deliberately conservative: the capture manager already photographs on
+     *   interaction, navigation and scroll settle, so a genuinely active screen refreshes well
+     *   inside it, and a screen quiet for longer than that is one nobody is interacting with.
+     *
+     * Returning null is a correct, common answer and downstream MUST treat it as "not captured"
+     * rather than as a default.
+     */
+    currentKeyframe(
+        screenName?: string,
+        maxAgeMs = 10_000,
+        now: number = Date.now(),
+    ): { frameId: string; screen: string | null; capturedAt: number } | null {
+        if (!this._lastKeyframeId || this._lastKeyframeTs <= 0) return null;
+        if (now - this._lastKeyframeTs > maxAgeMs) return null;
+        // Compared only when the caller knows its screen. An event with no screen cannot be shown
+        // to belong to this frame, so it does not get one.
+        if (!screenName || this._lastKeyframeScreen !== screenName) return null;
+        return {
+            frameId: this._lastKeyframeId,
+            screen: this._lastKeyframeScreen,
+            capturedAt: this._lastKeyframeTs,
+        };
+    }
+
     /** Set callback for when a frame is captured */
     setFrameEmitCallback(cb: FrameEmitCallback): void {
         this.onFrameEmit = cb;
@@ -291,6 +341,7 @@ export class ReplayCaptureManager {
         this._lastFrameHash = null;
         this._lastKeyframeTs = 0;
         this._lastKeyframeId = null;
+        this._lastKeyframeScreen = null;
         this._framesSinceKeyframe = 0;
 
         // Start frequency timer if in frequency mode
@@ -808,6 +859,7 @@ export class ReplayCaptureManager {
             if (frameType === 'keyframe') {
                 this._lastKeyframeId = frameId;
                 this._lastKeyframeTs = now;
+                this._lastKeyframeScreen = screenName ?? null;
                 this._framesSinceKeyframe = 0;
             } else {
                 this._framesSinceKeyframe++;