@scalebun/react-native 1.0.3 → 1.0.4

package/src/features/session/SessionManager.ts

@@ -40,6 +40,7 @@ import { generateEventId } from '../replay/core/ids/sessionId';
 import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
 import { redactBody } from '../../debug/redaction';
 import { consumeCalibrationTarget } from '../journey/calibrationContext';
+import { resolvePlatformOS } from '../../core/context/device';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -385,12 +386,11 @@ export class SessionManager {
                 startedAt: Date.now(),
                 status: 'active',
                 metadata: {
-                    platform: (() => {
-                        try {
-                            const { Platform } = require('react-native');
-                            return Platform.OS === 'ios' ? 'ios' : 'android';
-                        } catch { return 'android'; }
-                    })(), // Real OS; enriched by native device info when available
+                    // The real Platform.OS. This used to be a ternary whose else-branch was 'android'
+                    // and whose catch was ALSO 'android' — so a macOS session, a Windows session, and
+                    // a failure to load react-native at all were reported identically, as Android.
+                    // Enriched by native device info when the bridge answers.
+                    platform: resolvePlatformOS(),
                     buildType: __DEV__ ? 'debug' : 'release',
                     ...metadata,
                     // Capture window dp dims here so emitEvent() can normalize coords
@@ -748,6 +748,20 @@ export class SessionManager {
             // new object and strips known-sensitive keys; coords/gesture survive.
             const safePayload = redactBody(payload) as Record<string, unknown>;
 
+            /**
+             * NO `frameId` HERE, and it is not an oversight.
+             *
+             * This method is guarded by `if (this.active) return;` — it runs ONLY when no replay
+             * recording is active, which is precisely when no screenshots are being captured.
+             * There is no frame on screen to point at, so an analytics-lane tap can never be
+             * attributed to a visual state.
+             *
+             * That makes it a permanent property of this lane rather than a gap to close later,
+             * and the dashboard has to account for it: these taps live in the heatmap grid
+             * alongside recorded ones, so a state filter necessarily covers a subset of the
+             * traffic. `heat:screen-coverage` reports that subset's size per app for exactly this
+             * reason.
+             */
             const event: JourneyEvent = {
                 eventId: generateEventId(),
                 // sessionId is (re)stamped by the analytics lane at flush time.
@@ -849,7 +863,32 @@ export class SessionManager {
                 } catch { /* no-throw */ }
             }
 
-            const event = this.pipeline.emit(type, opts);
+            /**
+             * Which frame was on screen when this happened.
+             *
+             * Resolved BEFORE `pipeline.emit`, and deliberately before the capture triggers
+             * below: those capture the frame that shows the RESULT of the interaction, and a tap
+             * belongs to the state it was made IN, not the one it produced. Reading after them
+             * would attribute every tap to its own consequence.
+             *
+             * USER_ACTION only. A SCREEN_VIEW's frame is the screen being left, which is
+             * misleading rather than useful, and no consumer asks for it.
+             *
+             * `currentKeyframe` returns null unless the frame is from this same screen and still
+             * fresh — see its contract. Null is the common, correct answer and stays absent on
+             * the event rather than becoming a default.
+             */
+            const framedOpts =
+                type === 'USER_ACTION'
+                    ? {
+                          ...opts,
+                          frameId: this.captureManager?.currentKeyframe(
+                              opts?.screen ?? this._lastKnownScreen ?? undefined,
+                          )?.frameId,
+                      }
+                    : opts;
+
+            const event = this.pipeline.emit(type, framedOpts);
 
             // Trigger capture on screen view or interaction
             if (event) {

package/src/features/session/nativeCapture.ts

@@ -4,6 +4,7 @@
  * Provides the callback for the SessionManager to request screenshots
  * from the native layer (PixelCopy on Android, UIWindow on iOS).
  */
+import { resolvePlatformOS, type PlatformOS } from '../../core/context/device';
 
 export const nativeCapture = async (sessionId: string, reason: string, _quality: any) => {
     try {
@@ -17,8 +18,8 @@ export const nativeCapture = async (sessionId: string, reason: string, _quality:
         const result = await replaySdk.captureScreenshot(reason);
         if (!result?.base64) return null;
 
-        const { Platform } = require('react-native');
-        const platform: 'android' | 'ios' = Platform.OS === 'ios' ? 'ios' : 'android';
+        // Platform.OS verbatim. The ternary this replaces labelled every non-iOS frame 'android'.
+        const platform: PlatformOS = resolvePlatformOS();
 
         return {
             base64: result.base64 as string,

package/src/features/session/outboxFrameCapture.ts

@@ -15,13 +15,14 @@
  * transparently falls back to the legacy `captureScreenshot` path.
  */
 
-import { Platform } from 'react-native';
 import { getReplaySdkNative } from '../replay/bridge/nativeModule';
+import { resolvePlatformOS, type PlatformOS } from '../../core/context/device';
 import type { OutboxFrameCapture, StagedFrameResult, OutboxFrameMeta } from './ReplayCaptureManager';
 
 /** Build the adapter. `ensureReady` resolves false when the native outbox is off. */
 export function makeOutboxFrameCapture(ensureReady: () => Promise<boolean>): OutboxFrameCapture {
-    const platform: 'android' | 'ios' = Platform.OS === 'ios' ? 'ios' : 'android';
+    // Platform.OS verbatim — see core/context/device.
+    const platform: PlatformOS = resolvePlatformOS();
 
     return {
         async capture(sessionId, screenName, trigger): Promise<StagedFrameResult | null> {

package/src/features/session/sessionTypes.ts

@@ -1,3 +1,4 @@
+import type { PlatformOS } from '../../core/context/device';
 /**
  * ScaleBun SDK — Unified Session Domain Model
  *
@@ -21,7 +22,9 @@ export interface SessionMetadata {
     appName?: string;
     appVersion?: string;
     bundleId?: string;
-    platform?: 'android' | 'ios' | 'web';
+    // Widened to the real Platform.OS — see core/context/device. The wire's platform field is an
+    // open enum, so a value this union did not anticipate travels rather than being coerced.
+    platform?: PlatformOS;
     osVersion?: string;
     deviceModel?: string;
     deviceName?: string;
@@ -78,6 +81,22 @@ export interface JourneyEvent {
     severity?: JourneyEventSeverity;
     /** Screen name at time of event */
     screen?: string;
+    /**
+     * frameId of the screenshot that was ON SCREEN when this event happened.
+     *
+     * The picture the user was looking at, not the one that follows. Mobile has no DOM to
+     * reconstruct, so a captured frame is the only record of what a screen looked like at a
+     * moment — which makes this the join key between a tap and the state it was made in.
+     *
+     * Set only when a keyframe from the SAME screen was captured recently enough to still be
+     * showing (see SessionManager.currentFrameForEvent). Absent means "not captured", which is a
+     * DIFFERENT answer from "nothing was open" and must never be folded into it:
+     *   · the analytics lane never has one — it runs only when no recording is active, so no
+     *     screenshots exist at all
+     *   · a tap right after navigation has none — the capture is debounced and evicted on
+     *     screen change
+     */
+    frameId?: string;
     payload?: Record<string, unknown>;
     /** Links related events (e.g. network request start → complete) */
     correlationId?: string;
@@ -114,7 +133,9 @@ export interface ReplayFrame {
     quality: ReplayQuality;
     captureReason: CaptureReason;
     /** Native-only capture — JS never captures frames */
-    sourcePlatform: 'android' | 'ios';
+    // Widened: a frame reports the REAL Platform.OS. The old union forced every non-iOS capture to
+    // be relabelled 'android', which is how RN-macOS and RN-Windows sessions became Android ones.
+    sourcePlatform: PlatformOS;
     redactionState?: 'none' | 'text-masked' | 'full';
     /** Screen name at capture time — for frame-to-screen correlation */
     screen?: string;
@@ -363,7 +384,9 @@ export interface NativeFrameResult {
     /** Byte size of the compressed image */
     byteSize: number;
     /** Platform that performed the capture */
-    platform: 'android' | 'ios';
+    // Widened from 'android'|'ios': a frame is labelled with the REAL Platform.OS now, and the
+    // old union forced every non-iOS capture to be relabelled 'android'.
+    platform: PlatformOS;
     /** Actual on-device encoding after the AVIF->WebP->JPEG fallback (P2-2). */
     format?: string;
     /** Optional native frame hash for change detection (P2-1). JS falls back to hashing base64. */

package/src/index.ts

@@ -49,6 +49,9 @@ export {
 } from './features/engage/EngageAnchor';
 
 // ─── OTA Updates ───────────────────────────────────────────────────────────
+// D3: manual capture — existed for a year, exported to nobody, delivered to a
+// queue nothing drained. Now rides the proven crash pipeline.
+export { captureException, captureMessage } from './features/crash/capture';
 export { otaOrchestrator, OtaOrchestrator } from './features/ota/OtaOrchestrator';
 export type { SyncResult, BootGuardConfig } from './features/ota/OtaOrchestrator';
 export { useOtaUpdate } from './features/ota/useOtaUpdate';

package/src/public/ScaleBunFacade.ts

@@ -13,10 +13,14 @@ import { noThrow, safeAsync } from '../core/lifecycle/crashSafe';
 import { logger } from '../core/logger/internalLogger';
 import { createEnvelope } from '../pipeline/envelope/envelope';
 import { generateEventId } from '../features/replay/core/ids/sessionId';
+import { buildBugReportPayload } from '../features/bugreport/buildPayload';
+import type { BugSubmitResult } from '../features/bugreport/BugReportFeature';
+import { BugReportFeature } from '../features/bugreport/BugReportFeature';
 import { PersistentQueue } from '../pipeline/queue/persistentQueue';
 import { MemoryBackend, createStorageBackend } from '../storage/StorageBackend';
 import { HttpClient } from '../transport/http/httpClient';
 import { getDeviceId } from '../core/id/deviceId';
+import { mergeDeviceContext } from '../core/context/device';
 import { coreContainer } from '../core/di/container';
 import { flushQueue } from '../pipeline/queue/flushQueue';
 import {
@@ -278,7 +282,9 @@ class ScaleBunFacade {
             const appId = rawConfig?.appId;
             const enabled = rawConfig?.eventTracking !== false;
             const clientKey = this._clientKey ?? rawConfig?.clientKey;
-            const apiBaseUrl = this._apiBaseUrl ?? rawConfig?.apiBaseUrl;
+            // apiBaseUrl is LOCKED — use only the bootstrapped value, never fall back to raw
+            // integrator input, so the event-tracker/SKAdNetwork lane can't be repointed either.
+            const apiBaseUrl = this._apiBaseUrl;
             if (!enabled || !appId || !clientKey || !apiBaseUrl) {
                 if (enabled && !appId) {
                     logger.info('[ScaleBun] Envelope event tracking disabled — no appId in init config.');
@@ -307,7 +313,16 @@ class ScaleBunFacade {
                 automaticEventTracking:
                     rawConfig?.automaticEventTracking === true,
                 flushIntervalMs: rawConfig?.flushIntervalMs,
-                context: rawConfig?.context,
+                /**
+                 * DETECTED, not configured.
+                 *
+                 * This was `rawConfig?.context` — whatever the app typed. Production carries
+                 * `device_model: "android"` and `manufacturer: "android"` from a hand-written
+                 * literal, while the replay lane was reading the real values off the native bridge
+                 * the whole time. The SDK knows the device; the integrator is guessing at it.
+                 * Everything outside the detected keys is still theirs.
+                 */
+                context: mergeDeviceContext(rawConfig?.context),
                 // Use the same foreground id as replay/journey capture. The
                 // callback is resolved per event because the session subsystem
                 // may start after this tracker is constructed.
@@ -597,6 +612,125 @@ class ScaleBunFacade {
         return null;
     }
 
+    // ─── Bug reports (F-BUG) ────────────────────────────────────────────
+
+    /**
+     * Thin feature object; the facade owns the HTTP, mirroring the web SDK split.
+     * Its only job here is raising the 'report' capture signal so replay flushes.
+     */
+    private readonly _bugReport = new BugReportFeature();
+
+    /**
+     * Submit a bug report against the CURRENT session.
+     *
+     * Mirrors the web SDK's `reportBugDetailed` ordering, which is load-bearing rather than
+     * incidental:
+     *
+     *   1. resolve the session   — a report with no session cannot be joined to its evidence
+     *   2. signal 'report'       — replay flushes its buffer so the report has visual context
+     *   3. snapshot the anchor   — BEFORE the POST. A flush asks the recorder to deliver pending
+     *                              bytes; it cannot retroactively manufacture a frame, so an absent
+     *                              coordinate must stay absent rather than becoming a misleading
+     *                              "start of session" link in the dashboard
+     *   4. build + POST          — bounds enforced by buildBugReportPayload against the server DTO
+     *
+     * Returns the report id, or `{ e }` naming which branch failed — 'init' (SDK not configured)
+     * reads differently from 'send' (network), and that difference is what tells an integrator
+     * whether to check their setup or their connection. It never throws: this is called from a UI
+     * the host app renders, usually from a user gesture, and an exception escaping into a React
+     * Native render tree is a redbox shown to the customer's user over a report they were sending us.
+     */
+    public async reportBugDetailed(input: {
+        message: string;
+        title?: string;
+        email?: string;
+        clientReportId?: string;
+    }): Promise<BugSubmitResult> {
+        if (!input || !input.message || input.message.trim().length === 0) {
+            logger.warn('[ScaleBun] reportBug: a message is required');
+            return { e: 'empty' };
+        }
+        if (!this._clientKey || !this._apiBaseUrl) {
+            logger.warn('[ScaleBun] reportBug: SDK is not configured (clientKey/apiBaseUrl)');
+            return { e: 'init' };
+        }
+
+        const sessionId = this.getActiveSessionId();
+        if (!sessionId) {
+            // No session means no row to attach to, and the ingestion route is session-scoped.
+            logger.warn('[ScaleBun] reportBug: no active session');
+            return { e: 'init' };
+        }
+
+        try {
+            // Flush replay into the session BEFORE reading the anchor below.
+            this._bugReport.signalReport();
+
+            const coord = this._replayCoord();
+            const payload = buildBugReportPayload(input, this._recentBreadcrumbs(), {
+                replayCoord: coord,
+                timestamp: Date.now(),
+            });
+
+            const res = await fetch(
+                `${this._apiBaseUrl}/ingestion/sessions/${sessionId}/bug-reports`,
+                {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-scalebun-client-key': this._clientKey,
+                    },
+                    body: JSON.stringify(payload),
+                },
+            );
+            if (!res.ok) {
+                logger.warn('[ScaleBun] reportBug: server rejected the report', res.status);
+                return { e: 'send' };
+            }
+            const body = await res.json().catch(() => null);
+            return body?.id ?? { e: 'send' };
+        } catch (err: any) {
+            logger.warn('[ScaleBun] reportBug failed:', err?.message);
+            return { e: 'send' };
+        }
+    }
+
+    /**
+     * The replay coordinate at submit time, or null.
+     *
+     * Deliberately returns null rather than a zeroed coordinate when replay is disabled, paused, or
+     * has not produced a frame yet — see the anchor note on reportBug.
+     */
+    /**
+     * The replay coordinate at submit time.
+     *
+     * ALWAYS null today, deliberately and visibly.
+     *
+     * The web SDK reads this from its recorder, but the RN replay subsystem exposes no sequence or
+     * segment accessor on its public API (features/replay/public/api.ts) -- there is currently no
+     * supported way to ask it where playback is. Probing for it through an `any` cast would compile,
+     * miss, and leave every report anchor-less while looking wired: the same defect as the existing
+     * reportBug(), which emits an analytics event and looks like it files a report.
+     *
+     * Returning null keeps the payload HONEST -- buildBugReportPayload omits replaySeq entirely, so
+     * the dashboard shows no anchor rather than a false one pointing at the start of the session.
+     * To finish this: expose the current seq + segment id from the replay recorder, then read them
+     * here. The payload builder and its contract tests already handle a real coordinate, including
+     * a genuine seq of 0.
+     */
+    private _replayCoord(): { seq?: number | null; segmentId?: string | null } | null {
+        return null;
+    }
+    /** Recent console breadcrumbs for quick triage. The full set already travels with the session. */
+    private _recentBreadcrumbs(): readonly unknown[] {
+        try {
+            const f = (this as any)._loggerFeature ?? (this as any)._consoleFeature;
+            return f?.getRecent?.() ?? [];
+        } catch {
+            return [];
+        }
+    }
+
     // ─── Engage ─────────────────────────────────────────────────────────
 
     /**
@@ -1131,6 +1265,23 @@ class ScaleBunFacade {
 
     /** Report a bug (convenience wrapper over track) */
     public reportBug(description: string, metadata?: Record<string, unknown>) {
+        // D11: this used to be ONLY `track('$bug_report')` — an analytics event
+        // with zero consumers (no mapper, no handler, no BugReport row), so
+        // /diagnose/bug-reports stayed empty forever for RN apps while the web
+        // SDK used the real ingest. Route to the same endpoint the web SDK
+        // uses; the analytics event is kept as a breadcrumb, not the delivery.
+        try {
+            const transport = SessionManager.getExistingInstance()?.getBackendTransport();
+            transport?.submitBugReport({
+                message: description,
+                title:
+                    typeof metadata?.title === 'string' ? (metadata.title as string) : undefined,
+                email:
+                    typeof metadata?.email === 'string' ? (metadata.email as string) : undefined,
+            });
+        } catch {
+            /* delivery is best-effort; the track below still records intent */
+        }
         return this.track('$bug_report', { description, ...metadata });
     }
 

package/src/specs/NativeScaleBunCrash.ts

@@ -23,8 +23,24 @@ export interface Spec extends TurboModule {
   /** DEV/TEST only: crash the process so the next launch can drain it. */
   crashNow(): Promise<boolean>;
 
+  /**
+   * Record which session is live so a crash can name it.
+   *
+   * Called once per session. Native writes it to crash-safe storage BEFORE any crash can happen —
+   * a fatal handler cannot call back into JS to ask.
+   */
+  setActiveSessionId(sessionId: string): Promise<boolean>;
+
   /** Return the previous run's crash record (or null), then clear it. */
   drainPendingCrash(): Promise<Object>;
+
+  /**
+   * Delete a delivered crash by its stable id.
+   *
+   * Called ONLY after the backend has accepted it. The read is non-destructive precisely so this
+   * can be the moment of deletion — a failed upload must leave the durable copy in place.
+   */
+  clearPendingCrash(crashId: string): Promise<boolean>;
 }
 
 /**