@scalebun/react-native 1.0.1 → 1.0.3

package/src/features/session/BackendSessionAdapter.ts

@@ -31,6 +31,10 @@ import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
 import { getReplaySdkNative } from '../replay/bridge/nativeModule';
 import type { ReplaySdkNativeModule } from '../replay/bridge/nativeModule';
 import type { StorageBackend } from '../../storage/StorageBackend';
+// Reused rather than reimplemented: `chunkEvents` is generic, order-preserving, and already carries
+// a contract test proving it drops and duplicates nothing (analytics/__tests__/batchChunking.test.ts).
+// Its internal ceiling (MAX_BATCH_EVENTS = 500) is well above the 100-frame cap passed here.
+import { chunkEvents } from '../../analytics/batching';
 import type {
     SessionTransport,
     Session,
@@ -110,8 +114,31 @@ export class BackendSessionAdapter implements SessionTransport {
     private readonly _frameStore: StorageBackend | null;
     /** Storage key for the snapshotted unflushed frame buffer (see persistPendingFrames). */
     private static readonly PENDING_FRAMES_KEY = 'scalebun_replay_pending_frames';
-    /** Cap on frames persisted per snapshot — bounds KV footprint (keeps the most recent). */
-    private static readonly MAX_PERSIST_FRAMES = 10;
+    /**
+     * Byte budget for the cross-kill frame snapshot (see `_selectFramesToPersist`).
+     *
+     * Replaces a flat 10-frame cap. A count could not bound the KV write at all — these frames carry
+     * base64 screenshots, so ten of them is anywhere from ~200 KB to several MB depending on device
+     * resolution, and an oversized value is exactly what fails on the background transition where
+     * this write happens.
+     *
+     * 2 MB is deliberately modest: this is a last-resort snapshot for frames that never reached the
+     * network, not a mirror of the session. Enough for a keyframe plus a run of deltas on any device;
+     * small enough that writing it cannot itself be the reason backgrounding stalls.
+     */
+    private static readonly MAX_PERSIST_BYTES = 2 * 1024 * 1024;
+    /**
+     * Frames the backend accepts in ONE request — `'Max 100 frames per batch'`
+     * (`IngestionService.uploadFrames`). Exceeding it is a 4xx, which this SDK classifies as
+     * permanent.
+     *
+     * This has to exist alongside the byte budget, not instead of it. The budget alone cannot bound
+     * the COUNT, and the count is what the server checks: measured on real traffic, mobile keyframes
+     * average ~16 KB, so a 2 MB snapshot is around 128 frames — over the cap by construction. The old
+     * flat 10-frame rule was under it by construction, which is why this failure could not happen
+     * before and can now.
+     */
+    private static readonly MAX_FRAMES_PER_BATCH = 100;
     // Per-session toggle: cleared to false if the backend reports storage disabled.
     private objectStorageActive: boolean;
     // True when telemetry should divert to the durable native outbox (both flags on).
@@ -139,6 +166,14 @@ export class BackendSessionAdapter implements SessionTransport {
     private pendingLogs: LogQueueItem[] = [];
     private flushTimer: ReturnType<typeof setInterval> | null = null;
     private destroyed = false;
+    /**
+     * Latch for `sdk_replay_capture_failed` — reported once per adapter, not once per rejected batch.
+     *
+     * A session whose row was never created rejects EVERY frame batch, so an unlatched report would
+     * emit one analytics event per flush for as long as the app stays open, on the same lane it is
+     * trying to report through.
+     */
+    private _captureFailureReported = false;
 
     // ── Analytics lane (always-on, foreground-scoped; isolated from recording) ──
     // Fully separate from currentSessionId/pendingEvents/_flushEvents, which serve
@@ -344,6 +379,11 @@ export class BackendSessionAdapter implements SessionTransport {
     }): Promise<void> {
         if (this.destroyed) return;
         this._analyticsSessionId = session.sessionId;
+        // A new session gets its own capture-failure report. The latch bounds reports WITHIN a
+        // session; left standing across sessions it silenced every session after the first in the
+        // app process, which is the one place this differs from the web SDK — that pipeline is
+        // constructed per page and its session id is readonly, so its latch cannot outlive a session.
+        this._captureFailureReported = false;
         this._startAnalyticsFlushTimer();
 
         // Replay pre-ready buffered events now that the id exists. sessionId is
@@ -838,21 +878,109 @@ export class BackendSessionAdapter implements SessionTransport {
         const sessionId = this.currentSessionId;
 
         const batch = this.pendingFrames.splice(0, this.config.batchSize);
+        /**
+         * Chunked, because `config.batchSize` is HOST-CONFIGURABLE and the server's 100-frame cap is
+         * not. A host raising it past 100 previously turned every frame flush into a permanent 4xx —
+         * silent, total replay loss for that app, from a config value that looks like a tuning knob.
+         *
+         * A permanent rejection is reported and abandoned inside `_postFramesChunked`; what comes
+         * back is only what is still worth another attempt.
+         */
+        const remaining = await this._postFramesChunked(sessionId, batch);
+        if (remaining.length) {
+            logger.warn(`[replay.sdk.error] backend frame upload failure`, { count: remaining.length });
+            this.pendingFrames.unshift(...remaining);
+            return;
+        }
+        logger.debug(`[BackendSessionAdapter] Flushed ${batch.length} frame(s)`);
+        // Delivered — the durable snapshot (if any) is now redundant. Clear it once
+        // the in-memory buffer is fully drained so a later kill can't replay
+        // already-uploaded frames.
+        if (this.pendingFrames.length === 0) this._clearPersistedFrames();
+    }
+
+    /**
+     * Report frames the SDK gave up on, on the analytics lane.
+     *
+     * SAME EVENT NAME AS THE WEB SDK (`sdk_replay_capture_failed`) with platform-specific `reason`
+     * values, so one dashboard breakdown reads both platforms without a concept-map alias — the two
+     * SDKs share no event vocabulary otherwise (`$pageview` vs `screen_viewed`), and adding a second
+     * name here would need an entry in `event-concepts.ts` for no benefit.
+     *
+     * Latched to once per session: a session whose row was never created rejects every batch, and an
+     * unlatched report would emit one event per flush for as long as the app is open.
+     *
+     * Best-effort and never throws — a diagnostic must not be able to break the capture path it
+     * describes.
+     */
+    private _reportCaptureFailure(stage: string, err: unknown, frameCount: number): void {
+        if (this._captureFailureReported) return;
+        this._captureFailureReported = true;
         try {
-            await this._postFrameBatch(sessionId, batch);
-            logger.debug(`[BackendSessionAdapter] Flushed ${batch.length} frame(s)`);
-            // Delivered — the durable snapshot (if any) is now redundant. Clear it once
-            // the in-memory buffer is fully drained so a later kill can't replay
-            // already-uploaded frames.
-            if (this.pendingFrames.length === 0) this._clearPersistedFrames();
-        } catch (err) {
-            if (BackendSessionAdapter._isPermanentHttpError(err)) return;
-            logger.warn(`[replay.sdk.error] backend frame upload failure`, { count: batch.length });
-            // Re-queue on failure
-            this.pendingFrames.unshift(...batch);
+            if (!this._analyticsSessionId) return; // no lane open — nothing to attach it to
+            const status = (err as { status?: number })?.status;
+            this.trackEvent({
+                eventId: this._clientId(),
+                sessionId: this._analyticsSessionId,
+                ts: Date.now(),
+                type: 'sdk_replay_capture_failed',
+                source: 'sdk',
+                payload: {
+                    stage,
+                    // Platform-specific vocabulary. The HTTP status is the honest reason on this path:
+                    // RN posts to the per-lane endpoints, which surface a real status — unlike the web
+                    // batch fan-out, whose 200 says nothing about what it stored.
+                    reason: status ? `http_${status}` : 'upload_failed',
+                    frames: frameCount,
+                    platform: 'react-native',
+                },
+            } as unknown as JourneyEvent);
+        } catch {
+            // Diagnostics must never break the capture path.
         }
     }
 
+    /**
+     * Post frames in BACKEND-SAFE CHUNKS, and return the ones that were not durably accepted.
+     *
+     * WHY THIS EXISTS. `_postFrameBatch` issues exactly one request for whatever array it is handed,
+     * and both callers could hand it more than the server's 100-frame cap — the live flush via
+     * `config.batchSize`, and cross-kill recovery via the 2 MB persistence budget (~128 frames at the
+     * measured 16 KB average). The result was a 4xx, classified permanent, and on the recovery path
+     * that meant `_clearPersistedFrames()` — the ENTIRE cross-kill snapshot deleted because it was
+     * one frame too big to send in a single request it never needed to be sent in.
+     *
+     * THE RETURN VALUE IS THE POINT. The caller must be able to delete exactly what landed and keep
+     * exactly what did not, so this reports the survivors rather than throwing:
+     *   - chunk accepted            → dropped from the result (it is durably stored)
+     *   - chunk PERMANENTLY refused → dropped, and reported once. Re-sending identical bytes cannot
+     *                                 succeed, and holding it would wedge every future launch on the
+     *                                 same poison chunk. Only that chunk is abandoned; the rest still
+     *                                 gets its chance, which is the whole difference from before.
+     *   - chunk TRANSIENTLY failed  → that chunk AND every chunk after it are kept, in order. We stop
+     *                                 on the first transient failure rather than pressing on, because
+     *                                 the usual cause is the network being gone and the rest would
+     *                                 fail identically.
+     */
+    private async _postFramesChunked(
+        sessionId: string,
+        items: Array<{ frame: ReplayFrame; imageData: string }>,
+    ): Promise<Array<{ frame: ReplayFrame; imageData: string }>> {
+        const chunks = chunkEvents(items, BackendSessionAdapter.MAX_FRAMES_PER_BATCH);
+        for (let i = 0; i < chunks.length; i++) {
+            try {
+                await this._postFrameBatch(sessionId, chunks[i]);
+            } catch (err) {
+                if (BackendSessionAdapter._isPermanentHttpError(err)) {
+                    this._reportCaptureFailure('upload-rejected', err, chunks[i].length);
+                    continue;
+                }
+                return chunks.slice(i).flat();
+            }
+        }
+        return [];
+    }
+
     /**
      * POST one frame batch under an EXPLICIT sessionId (object-storage path when
      * active, else legacy inline base64). Used by both the live flush and cross-kill
@@ -905,7 +1033,8 @@ export class BackendSessionAdapter implements SessionTransport {
         if (!this._frameStore || this.destroyed || !this.currentSessionId) return;
         if (this.pendingFrames.length === 0) return;
         try {
-            const items = this.pendingFrames.slice(-BackendSessionAdapter.MAX_PERSIST_FRAMES);
+            const items = BackendSessionAdapter._selectFramesToPersist(this.pendingFrames);
+            if (items.length === 0) return;
             this._frameStore.set(
                 BackendSessionAdapter.PENDING_FRAMES_KEY,
                 JSON.stringify({ sessionId: this.currentSessionId, items }),
@@ -915,6 +1044,70 @@ export class BackendSessionAdapter implements SessionTransport {
         }
     }
 
+    /**
+     * Choose which unflushed frames survive a process kill.
+     *
+     * WHY THIS IS NOT `slice(-10)`.
+     *
+     * The old rule kept the ten most RECENT frames, which is the wrong end of the buffer for replay.
+     * A delta reconstructs against its base keyframe, so ten trailing deltas whose keyframe was
+     * dropped are unplayable on their own — they arrive as `orphaned`, the state the dashboard flags
+     * as a capture defect. Keeping the keyframe and fewer deltas yields a SHORTER replay; keeping the
+     * deltas and no keyframe yields NO replay. That asymmetry is the whole decision.
+     *
+     * So: every keyframe is kept, then the most recent deltas fill whatever byte budget is left. This
+     * mirrors the web SDK's `capBytes` policy (which sheds deltas first and never the keyframe), so
+     * the two platforms lose the same thing under pressure instead of two different things.
+     *
+     * BYTES, not a frame count. A count is a poor proxy here: these carry base64 screenshots, so ten
+     * frames may be 200 KB or 4 MB depending on device resolution — and this write goes to a KV store
+     * on the background transition, where an oversized value is the thing most likely to fail and
+     * lose the snapshot entirely. `imageData.length` is the base64 length, which is within ~1% of the
+     * serialized cost and needs no extra pass.
+     */
+    private static _selectFramesToPersist(
+        pending: Array<{ frame: ReplayFrame; imageData: string }>,
+    ): Array<{ frame: ReplayFrame; imageData: string }> {
+        const isKeyframe = (b: { frame: ReplayFrame }) => b.frame.frameType !== 'delta';
+        const size = (b: { imageData: string }) => b.imageData?.length ?? 0;
+
+        const keep: Array<{ frame: ReplayFrame; imageData: string }> = [];
+        let budget = BackendSessionAdapter.MAX_PERSIST_BYTES;
+        /**
+         * A COUNT cap as well as a byte budget.
+         *
+         * The byte budget is the right bound for the KV write; it is the wrong bound for the upload,
+         * because the server checks a count. Recovery now chunks, so exceeding this is no longer
+         * destructive — but persisting more than can ever be sent in one pass just guarantees leftover
+         * work on every launch, and the frames past this point are the least valuable ones anyway.
+         */
+        const maxCount = BackendSessionAdapter.MAX_FRAMES_PER_BATCH;
+
+        // Keyframes first, newest back to oldest — a later keyframe supersedes an earlier one, so if
+        // only one fits it should be the one closest to what the user last saw.
+        for (let i = pending.length - 1; i >= 0; i--) {
+            const b = pending[i];
+            if (!isKeyframe(b)) continue;
+            const cost = size(b);
+            if (cost > budget || keep.length >= maxCount) continue;
+            budget -= cost;
+            keep.push(b);
+        }
+        // Then the most recent deltas with what remains.
+        for (let i = pending.length - 1; i >= 0; i--) {
+            const b = pending[i];
+            if (isKeyframe(b)) continue;
+            const cost = size(b);
+            if (cost > budget || keep.length >= maxCount) continue;
+            budget -= cost;
+            keep.push(b);
+        }
+
+        // Restore capture order: the backend orders frames by `sequenceNumber`, and the recovery POST
+        // re-sends this array as-is.
+        return keep.sort((a, b) => (a.frame.sequenceNumber ?? 0) - (b.frame.sequenceNumber ?? 0));
+    }
+
     /** Drop the persisted frame snapshot (after successful delivery). Never throws. */
     private _clearPersistedFrames(): void {
         if (!this._frameStore) return;
@@ -958,18 +1151,33 @@ export class BackendSessionAdapter implements SessionTransport {
             return;
         }
 
-        try {
-            logger.info(`[replay.sdk.frame] recovering ${items.length} frame(s) for prior session ${sessionId}`);
-            await this._postFrameBatch(sessionId, items);
+        logger.info(`[replay.sdk.frame] recovering ${items.length} frame(s) for prior session ${sessionId}`);
+        /**
+         * DELETE ONLY WHAT WAS ACCEPTED.
+         *
+         * This posted every recovered frame in ONE request and, on any permanent rejection, deleted
+         * the whole snapshot. Since the persistence budget is 2 MB of ~16 KB frames, that request was
+         * routinely over the server's 100-frame cap — so the common outcome was a 4xx followed by the
+         * deletion of a cross-kill recovery snapshot in which every frame was individually fine. The
+         * one thing a recovery buffer must never do.
+         *
+         * Now the send is chunked and only the unaccepted remainder survives. A chunk the server will
+         * never take is abandoned inside `_postFramesChunked` (and reported), so a single poison chunk
+         * cannot wedge every future launch — but a transient failure keeps its frames for next time.
+         */
+        const remaining = await this._postFramesChunked(sessionId, items);
+        if (remaining.length === 0) {
             this._clearPersistedFrames();
-        } catch (err) {
-            if (BackendSessionAdapter._isPermanentHttpError(err)) {
-                // Server rejected permanently (e.g. session gone) — don't retry forever.
-                this._clearPersistedFrames();
-                return;
-            }
-            // Transient — keep the snapshot for the next launch.
-            logger.warn(`[replay.sdk.frame] prior-session frame recovery deferred (transient)`);
+            return;
+        }
+        logger.warn(`[replay.sdk.frame] prior-session frame recovery deferred`, { kept: remaining.length });
+        try {
+            this._frameStore.set(
+                BackendSessionAdapter.PENDING_FRAMES_KEY,
+                JSON.stringify({ sessionId, items: remaining }),
+            );
+        } catch {
+            // Re-writing the trimmed snapshot is best-effort; the original is still on disk.
         }
     }
 

package/src/index.ts

@@ -16,6 +16,12 @@
 
 export { default } from './public/ScaleBunFacade';
 export { ScaleBunProvider } from './public/ScaleBunProvider';
+/**
+ * Render-error boundary. Named and shaped to match `@scalebun/web-react`'s export so the same code
+ * works on both platforms — see the note in ScaleBunErrorBoundary.tsx for why a host boundary
+ * without this silently swallowed every React render error.
+ */
+export { ScaleBunErrorBoundary, type ScaleBunErrorBoundaryProps } from './public/ScaleBunErrorBoundary';
 
 // ─── React Components & Hooks (consumer-facing) ────────────────────────────
 // These are needed by app developers to wrap their app and track screens.

package/src/public/ScaleBunErrorBoundary.tsx

@@ -0,0 +1,79 @@
+/**
+ * ScaleBunErrorBoundary — React render errors, forwarded to the SDK.
+ *
+ * THE GAP THIS CLOSES
+ * `ErrorUtils.setGlobalHandler` catches a render error only when NO boundary intercepts it first.
+ * The moment a host wraps its tree in its own boundary — which most production apps do — that
+ * boundary's `componentDidCatch` consumes the error, it never reaches `ErrorUtils`, and the SDK
+ * recorded nothing at all. The screen went blank or fell back, and the crash list stayed empty.
+ *
+ * The web SDK has shipped `ScaleBunErrorBoundary` from `@scalebun/web-react` for exactly this reason;
+ * React Native had no equivalent and no `componentDidCatch` hook a host could forward through. This
+ * is the counterpart, and the two are deliberately the same component with the same prop names so a
+ * team working across both platforms writes the same thing twice.
+ *
+ * Use it INSTEAD of your own boundary, or nest it inside one — `onError` runs after capture so an
+ * existing boundary's logging keeps working.
+ *
+ * ```tsx
+ * <ScaleBunErrorBoundary fallback={(e) => <Text>Something broke: {e.message}</Text>}>
+ *   <App />
+ * </ScaleBunErrorBoundary>
+ * ```
+ */
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import ScaleBun from './ScaleBunFacade';
+
+export interface ScaleBunErrorBoundaryProps {
+    children: ReactNode;
+    /** Rendered after a caught error. A function receives the error; a node is rendered as-is. */
+    fallback?: ReactNode | ((error: Error) => ReactNode);
+    /** Extra hook after the error is captured (e.g. custom logging). */
+    onError?: (error: Error, info: ErrorInfo) => void;
+    /** Screen name to attribute the error to, when the host knows it. */
+    screenName?: string;
+}
+
+interface State {
+    error: Error | null;
+}
+
+export class ScaleBunErrorBoundary extends Component<ScaleBunErrorBoundaryProps, State> {
+    state: State = { error: null };
+
+    static getDerivedStateFromError(error: Error): State {
+        return { error };
+    }
+
+    componentDidCatch(error: Error, info: ErrorInfo): void {
+        try {
+            /**
+             * NOT fatal, matching the web boundary.
+             *
+             * The app is still running — that is the entire point of a boundary — so this is reported
+             * as a handled error rather than a crash. Marking it fatal would put an event the user
+             * experienced as a fallback screen into the same bucket as an app that actually died, and
+             * the crash rate is a number people act on.
+             *
+             * `componentStack` travels in `metadata` because that is the shape RN's `captureError`
+             * takes; the web SDK accepts it as a top-level context key. Same information, and the
+             * difference is in the two facades, not here.
+             */
+            ScaleBun.captureError(error, {
+                screenName: this.props.screenName,
+                metadata: { componentStack: info.componentStack ?? undefined },
+            });
+        } catch {
+            /* never let capture break the boundary */
+        }
+        this.props.onError?.(error, info);
+    }
+
+    render(): ReactNode {
+        if (this.state.error) {
+            const { fallback } = this.props;
+            return typeof fallback === 'function' ? fallback(this.state.error) : (fallback ?? null);
+        }
+        return this.props.children;
+    }
+}

package/src/specs/NativeScaleBunOta.ts

@@ -73,6 +73,18 @@ export interface Spec extends TurboModule {
    * at cold start, BEFORE JS loads.
    */
   revertToPrevious(): Promise<boolean>;
+
+  /**
+   * Restart the React Native runtime so the applied bundle loads NOW.
+   *
+   * Exists because `DevSettings.reload()` is a silent no-op in RELEASE builds
+   * (verified live: "Triggering app restart…" logged, nothing happened, same
+   * process, old bundle still running). That made IMMEDIATE / ON_NEXT_RESUME /
+   * `autoRestart` / the CodePush shim's restart all fiction in production.
+   * Android: `ReactHost.reload()` (bridgeless) or
+   * `recreateReactContextInBackground()` (bridge). iOS: RCTReloadCommand.
+   */
+  restartApp(): void;
 }
 
 /**