@goliapkg/sentori-react-native 0.9.11 → 1.0.0-rc.10

package/src/__tests__/capture-replay.test.ts

@@ -0,0 +1,150 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+import { __captureAndAttachReplayForTests } from '../capture';
+import { setConfig, __resetForTests as resetConfig } from '../config';
+import type { Event } from '../types';
+
+// Insight 2026-05-18 rc.3 verify: walker is healthy, ticks land
+// deep wireframe JSON with TextView text, but the `replay` kind
+// never reaches `event.attachments`. Root cause was the inline
+// `btoa(ndjson)` upload path — spec-compliant Hermes / Bun btoa
+// throws `InvalidCharacterError` on any code point > 0xFF, and the
+// surrounding catch swallowed the throw silently. rc.4 routes
+// through `base64Utf8`, fixing both Latin-1 and UTF-8 inputs.
+//
+// These tests run the actual captureAndAttachReplay function the
+// captureException pipeline runs. fetch is mocked at the
+// transport.ts boundary so the upload landing isn't tested here
+// (covered separately in screenshot.test.ts); what we care about
+// is "does event.attachments grow when the input contains
+// non-Latin-1 text?".
+
+const origFetch = globalThis.fetch;
+
+beforeEach(() => {
+  setConfig({
+    enabled: true,
+    environment: 'test',
+    errorSampleRate: null,
+    ingestUrl: 'http://localhost:18080',
+    release: 'app@1.0.0+1',
+    screenshotsEnabled: true,
+    sessionTrailEnabled: true,
+    token: 'st_pk_test',
+    traceSampleRate: null,
+  });
+});
+
+afterEach(() => {
+  globalThis.fetch = origFetch;
+  resetConfig();
+});
+
+function makeEvent(): Event {
+  return {
+    id: '019eaa00-0000-7000-8000-000000000001',
+    timestamp: '2026-05-18T05:15:24.000Z',
+    kind: 'error',
+    platform: 'javascript',
+    release: 'app@1.0.0+1',
+    environment: 'test',
+    device: { os: 'android', osVersion: '36' },
+    app: {
+      version: '1.0.0',
+      build: '1',
+      framework: { name: 'react-native', version: '0.80.0' },
+    },
+    user: null,
+    tags: undefined,
+    breadcrumbs: [],
+    error: { type: 'Error', message: 'boom', stack: [], cause: null },
+    fingerprint: undefined,
+  };
+}
+
+function mockUploadSuccess(): { calls: { url: string; body: unknown }[] } {
+  const calls: { url: string; body: unknown }[] = [];
+  globalThis.fetch = mock(async (url: Request | string | URL, init?: RequestInit) => {
+    let body: unknown = undefined;
+    try {
+      body = init?.body ? JSON.parse(String(init.body)) : undefined;
+    } catch {
+      body = init?.body;
+    }
+    calls.push({ url: String(url), body });
+    return new Response(
+      JSON.stringify({
+        kind: 'replay',
+        mediaType: 'application/x-ndjson',
+        refId: '019e3000-7000-7000-8000-00000000aaaa',
+        sizeBytes: 200,
+      }),
+      { headers: { 'content-type': 'application/json' }, status: 201 },
+    );
+  }) as typeof fetch;
+  return { calls };
+}
+
+describe('captureAndAttachReplay — Insight rc.3 regression', () => {
+  test('Latin-1 ndjson attaches replay kind (control)', async () => {
+    const { calls } = mockUploadSuccess();
+    const event = makeEvent();
+    const ndjson =
+      '{"ts":1700000000,"width":390,"height":844,"nodes":[' +
+      '{"kind":"text","x":10,"y":20,"w":100,"h":20,"text":"Settings"}]}';
+    await __captureAndAttachReplayForTests(event, ndjson);
+    expect(calls.length).toBe(1);
+    expect(event.attachments?.length).toBe(1);
+    expect(event.attachments?.[0]?.kind).toBe('replay');
+  });
+
+  test('UTF-8 ndjson attaches replay kind (the rc.3 Android crash repro)', async () => {
+    // This is the bug: pre-rc.4 `btoa(ndjson)` threw on the
+    // Japanese characters below, the catch swallowed it, the
+    // attachment silently never landed. Post-rc.4 the helper
+    // handles UTF-8 and the attachment lands normally.
+    const { calls } = mockUploadSuccess();
+    const event = makeEvent();
+    const ndjson =
+      '{"ts":1700000000,"width":390,"height":844,"nodes":[' +
+      '{"kind":"text","x":10,"y":20,"w":100,"h":20,"text":"設定"},' +
+      '{"kind":"text","x":10,"y":50,"w":100,"h":20,"text":"ログアウト"}]}';
+    await __captureAndAttachReplayForTests(event, ndjson);
+    expect(calls.length).toBe(1);
+    expect(event.attachments?.length).toBe(1);
+    expect(event.attachments?.[0]?.kind).toBe('replay');
+  });
+
+  test('mixed em-dash / smart-quote / emoji attaches replay kind', async () => {
+    const { calls } = mockUploadSuccess();
+    const event = makeEvent();
+    const ndjson =
+      '{"ts":1,"width":390,"height":844,"nodes":[' +
+      '{"kind":"text","x":0,"y":0,"w":50,"h":20,"text":"hello — world"},' +
+      '{"kind":"text","x":0,"y":30,"w":50,"h":20,"text":"\\"quoted\\""},' +
+      '{"kind":"text","x":0,"y":60,"w":50,"h":20,"text":"🎉"}]}';
+    await __captureAndAttachReplayForTests(event, ndjson);
+    expect(calls.length).toBe(1);
+    expect(event.attachments?.length).toBe(1);
+    expect(event.attachments?.[0]?.kind).toBe('replay');
+  });
+
+  test('upload returns null → no attachment, no throw', async () => {
+    globalThis.fetch = (async () =>
+      new Response('{"error":"tooLarge"}', { status: 413 })) as typeof fetch;
+    const event = makeEvent();
+    const ndjson = '{"ts":1,"nodes":[]}';
+    await __captureAndAttachReplayForTests(event, ndjson);
+    expect(event.attachments).toBeUndefined();
+  });
+
+  test('fetch throws (offline) → no attachment, no throw out of the function', async () => {
+    globalThis.fetch = (async () => {
+      throw new TypeError('Network request failed');
+    }) as typeof fetch;
+    const event = makeEvent();
+    const ndjson = '{"ts":1,"nodes":[]}';
+    await __captureAndAttachReplayForTests(event, ndjson);
+    expect(event.attachments).toBeUndefined();
+  });
+});

package/src/__tests__/replay-encoding.test.ts

@@ -0,0 +1,237 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+
+import {
+  __feedTickForTests,
+  __resetReplayForTests,
+  computeDelta,
+  drainReplay,
+} from '../replay';
+
+// Unit coverage for the rc.9 v2 replay encoder.
+//
+// The encoder lives in replay.ts; native module is mocked away via
+// __feedTickForTests so we drive the captureTick body with hand-built
+// snapshots and inspect the resulting NDJSON shape.
+//
+// See docs/replay-encoding-v2.md for the wire schema.
+
+afterEach(() => {
+  __resetReplayForTests();
+});
+
+type Node = {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  kind?: string;
+  text?: string;
+  color?: string;
+};
+
+function frame(ts: number, nodes: Node[]) {
+  return JSON.stringify({ ts, width: 1080, height: 2340, nodes });
+}
+
+function nodeRect(x: number, y: number, w: number, h: number, color = '#FF0000FF'): Node {
+  return { x, y, w, h, kind: 'rect', color };
+}
+
+function nodeText(x: number, y: number, w: number, h: number, text: string, color = '#FFFFFFFF'): Node {
+  return { x, y, w, h, kind: 'text', text, color };
+}
+
+function readDrainedLines(): unknown[] {
+  const drained = drainReplay();
+  if (drained.length === 0) return [];
+  return drained.split('\n').map((l) => JSON.parse(l) as unknown);
+}
+
+describe('rc.9 encoder — keyframe vs delta', () => {
+  test('first tick after start always emits a keyframe', () => {
+    __feedTickForTests(frame(1_000, [nodeRect(0, 0, 1080, 2340)]));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(1);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+    expect((lines[0] as { width: number }).width).toBe(1080);
+    expect((lines[0] as { nodes: Node[] }).nodes.length).toBe(1);
+  });
+
+  test('static UI ticks emit no line (no-op heartbeat dropped)', () => {
+    const nodes = [nodeRect(0, 0, 1080, 2340, '#000000FF')];
+    __feedTickForTests(frame(1_000, nodes));
+    __feedTickForTests(frame(1_250, nodes));
+    __feedTickForTests(frame(1_500, nodes));
+    __feedTickForTests(frame(1_750, nodes));
+    const lines = readDrainedLines();
+    // 1 keyframe + 0 deltas (all subsequent ticks are no-op)
+    expect(lines.length).toBe(1);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+  });
+
+  test('a single node change emits exactly one delta with the changed node', () => {
+    const baseline = [
+      nodeRect(0, 0, 1080, 2340, '#0E0E10FF'),
+      nodeText(60, 192, 960, 112, 'before'),
+    ];
+    const after = [
+      nodeRect(0, 0, 1080, 2340, '#0E0E10FF'),
+      nodeText(60, 192, 960, 112, 'after'),
+    ];
+    __feedTickForTests(frame(1_000, baseline));
+    __feedTickForTests(frame(1_250, after));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(2);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+    expect((lines[1] as { kind: string }).kind).toBe('delta');
+    const d = lines[1] as { added: Node[]; changed: Node[]; removed: Node[] };
+    expect(d.added.length).toBe(0);
+    expect(d.removed.length).toBe(0);
+    expect(d.changed.length).toBe(1);
+    expect((d.changed[0] as Node).text).toBe('after');
+  });
+
+  test('added + removed nodes both appear in the delta', () => {
+    const baseline = [nodeRect(0, 0, 1080, 100), nodeRect(0, 200, 1080, 100)];
+    const after = [nodeRect(0, 0, 1080, 100), nodeRect(0, 400, 1080, 100)];
+    __feedTickForTests(frame(1_000, baseline));
+    __feedTickForTests(frame(1_250, after));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(2);
+    const d = lines[1] as { added: Node[]; changed: Node[]; removed: Node[] };
+    expect(d.added.length).toBe(1);
+    expect((d.added[0] as Node).y).toBe(400);
+    expect(d.removed.length).toBe(1);
+    expect((d.removed[0] as Node).y).toBe(200);
+  });
+
+  test('keyframe overdue ⇒ next emit is a keyframe even when delta is small', () => {
+    const baseline = [nodeRect(0, 0, 1080, 2340), nodeText(60, 192, 960, 112, 'a')];
+    // After 4 s (default keyframeMs), the next change triggers a fresh keyframe.
+    __feedTickForTests(frame(1_000, baseline));
+    const slightlyChanged = [
+      nodeRect(0, 0, 1080, 2340),
+      nodeText(60, 192, 960, 112, 'a-changed'),
+    ];
+    __feedTickForTests(frame(1_000 + 4_001, slightlyChanged));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(2);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+    expect((lines[1] as { kind: string }).kind).toBe('key'); // overdue → key
+  });
+
+  test('big screen transition (>40% nodes change) prefers a keyframe over a huge delta', () => {
+    const baseline = Array.from({ length: 10 }, (_, i) => nodeRect(0, i * 100, 1080, 90));
+    const after = Array.from({ length: 10 }, (_, i) => nodeRect(0, i * 100 + 500, 1080, 90));
+    __feedTickForTests(frame(1_000, baseline));
+    __feedTickForTests(frame(1_250, after));
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(2);
+    expect((lines[0] as { kind: string }).kind).toBe('key');
+    // Delta would be 10 added + 10 removed = 20 changes, > 10 * 0.4 threshold,
+    // so encoder should fall back to keyframe instead.
+    expect((lines[1] as { kind: string }).kind).toBe('key');
+  });
+
+  test('reconstructing keyframe + applied deltas recovers identical final state', () => {
+    // Drive 6 ticks: keyframe + 5 small deltas, then assert reconstruction equals the last input state.
+    const finalNodes: Node[] = [];
+    const baseline = [nodeRect(0, 0, 1080, 2340, '#0E0E10FF')];
+    __feedTickForTests(frame(1_000, baseline));
+    let state: Node[] = [...baseline];
+    for (let i = 0; i < 5; i++) {
+      // Add one row per tick.
+      const row = nodeText(60, 200 + i * 100, 960, 80, `row ${i}`);
+      state = [...state, row];
+      __feedTickForTests(frame(1_000 + (i + 1) * 250, state));
+    }
+    finalNodes.push(...state);
+
+    const lines = readDrainedLines();
+    expect(lines.length).toBe(6);
+    // Reconstruct: start from keyframe, apply each delta in order.
+    let reconstructed = new Map<string, Node>();
+    for (const line of lines) {
+      const l = line as { kind: string; nodes?: Node[]; added?: Node[]; changed?: Node[]; removed?: Pick<Node, 'x' | 'y' | 'w' | 'h'>[] };
+      if (l.kind === 'key') {
+        reconstructed = new Map((l.nodes ?? []).map((n) => [`${n.x | 0},${n.y | 0},${n.w | 0},${n.h | 0}`, n]));
+      } else {
+        for (const r of l.removed ?? []) {
+          reconstructed.delete(`${r.x | 0},${r.y | 0},${r.w | 0},${r.h | 0}`);
+        }
+        for (const a of l.added ?? []) {
+          reconstructed.set(`${a.x | 0},${a.y | 0},${a.w | 0},${a.h | 0}`, a);
+        }
+        for (const c of l.changed ?? []) {
+          reconstructed.set(`${c.x | 0},${c.y | 0},${c.w | 0},${c.h | 0}`, c);
+        }
+      }
+    }
+    expect(reconstructed.size).toBe(finalNodes.length);
+    for (const n of finalNodes) {
+      const got = reconstructed.get(`${n.x | 0},${n.y | 0},${n.w | 0},${n.h | 0}`);
+      expect(got).toBeDefined();
+      expect(got!.kind).toBe(n.kind);
+      expect(got!.text).toBe(n.text);
+      expect(got!.color).toBe(n.color);
+    }
+  });
+
+  test('byte budget — 60 s × 4 Hz dense UI stays below the rc.8 baseline', () => {
+    // Simulate 60 s at 4 Hz = 240 ticks. Dense UI: 100 nodes, 2 nodes
+    // change per tick on average. This mirrors the typical
+    // mostly-static-with-small-animations app shape.
+    const baseNodes = Array.from({ length: 100 }, (_, i) => nodeRect(0, i * 24, 1080, 20));
+    let totalBytes = 0;
+    const tickCount = 240;
+    for (let t = 0; t < tickCount; t++) {
+      // Every 4th tick mutates two nodes.
+      const nodes = baseNodes.map((n, i) => {
+        if (t % 4 === 0 && (i === t % 100 || i === (t + 50) % 100)) {
+          return { ...n, color: t & 1 ? '#FF0000FF' : '#00FF00FF' };
+        }
+        return n;
+      });
+      __feedTickForTests(frame(1_000 + t * 250, nodes));
+    }
+    const drained = drainReplay();
+    totalBytes = drained.length;
+
+    // rc.8 baseline for the same window: 60 × 100 nodes × ~50 bytes/node ≈ 300 KB.
+    // rc.9 target: well under 200 KB.
+    expect(totalBytes).toBeLessThan(200_000);
+    // Sanity: not zero, and dominated by keyframes.
+    expect(totalBytes).toBeGreaterThan(10_000);
+  });
+});
+
+describe('computeDelta', () => {
+  function asMap(nodes: Node[]): Map<string, Node> {
+    return new Map(nodes.map((n) => [`${n.x | 0},${n.y | 0},${n.w | 0},${n.h | 0}`, n]));
+  }
+
+  test('empty-vs-empty produces all-empty delta', () => {
+    const d = computeDelta(new Map(), new Map());
+    expect(d.added.length).toBe(0);
+    expect(d.changed.length).toBe(0);
+    expect(d.removed.length).toBe(0);
+  });
+
+  test('identical state produces no delta', () => {
+    const m = asMap([nodeRect(0, 0, 10, 10), nodeRect(0, 10, 10, 10)]);
+    const d = computeDelta(m, m);
+    expect(d.added.length).toBe(0);
+    expect(d.changed.length).toBe(0);
+    expect(d.removed.length).toBe(0);
+  });
+
+  test('integer-rounds fingerprints so sub-pixel jitter does not register', () => {
+    const prev = asMap([{ x: 0.1, y: 0.2, w: 10.3, h: 10.4, kind: 'rect' }]);
+    const curr = asMap([{ x: 0.4, y: 0.3, w: 10.2, h: 10.1, kind: 'rect' }]);
+    // Fingerprint of both is '0,0,10,10' → matched, no diff fields differ.
+    const d = computeDelta(prev, curr);
+    expect(d.added.length).toBe(0);
+    expect(d.changed.length).toBe(0);
+    expect(d.removed.length).toBe(0);
+  });
+});

package/src/base64.ts

@@ -0,0 +1,29 @@
+/**
+ * UTF-8-safe base64 encoder used by every JSON attachment path
+ * (sessionTrail, stateSnapshot, replay).
+ *
+ * Why this needs its own helper:
+ *   • Hermes' `globalThis.btoa` (and the WHATWG spec) is **Latin-1
+ *     only** — it throws `InvalidCharacterError` on any code point
+ *     > 0xFF. A wireframe NDJSON that includes a TextView with
+ *     Japanese / Chinese / em-dash text triggers it; the JS-side
+ *     `try / catch` then swallows the throw and the replay
+ *     attachment silently never lands.
+ *   • Insight 2026-05-18 rc.3 verify hit exactly this on Android —
+ *     the walker fix in rc.3 surfaced deep TextView text, which
+ *     then collided with the unsafe `btoa(ndjson)` path that had
+ *     worked accidentally on rc.2's shallow (text-free) snapshots.
+ *
+ * The pattern `btoa(unescape(encodeURIComponent(s)))` rewrites the
+ * UTF-8 byte sequence into a Latin-1-equivalent string that btoa
+ * can chew. `unescape` is deprecated for HTML but its byte-level
+ * behaviour is stable across every JS engine we ship to.
+ *
+ * Node / bun test fallback uses `Buffer` directly.
+ */
+export function base64Utf8(s: string): string {
+  if (typeof globalThis.btoa === 'function') {
+    return globalThis.btoa(unescape(encodeURIComponent(s)));
+  }
+  return Buffer.from(s, 'utf8').toString('base64');
+}

package/src/capture.ts

@@ -1,5 +1,6 @@
 import { sealTrail, shouldSample } from '@goliapkg/sentori-core';
 
+import { base64Utf8 } from './base64';
 import {
   __peekBreadcrumbCount,
   addBreadcrumb,
@@ -8,7 +9,7 @@ import {
 import { getBundleInfo } from './bundle-info';
 import { getConfig, isInitialized } from './config';
 import { getFeatureFlagSnapshot } from './feature-flags';
-import { drainReplay } from './replay';
+import { drainReplay, isReplayRunning } from './replay';
 import { clearStateSnapshots, getStateSnapshots } from './state-snapshots';
 import { symbolicateErrorViaMetro } from './handlers/dev-symbolicate';
 import { captureScreenshot } from './handlers/screenshot';
@@ -143,6 +144,7 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
       'breadcrumbs=', crumbs.length,
       'wantScreenshot=', config.screenshotsEnabled && extras?.screenshot !== false,
       'wantSessionTrail=', config.sessionTrailEnabled,
+      'wantReplay=', isReplayRunning(),
     );
   }
 
@@ -184,6 +186,17 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
     const replayNdjson = drainReplay();
     if (replayNdjson.length > 0) {
       await captureAndAttachReplay(event, replayNdjson);
+    } else if (typeof __DEV__ !== 'undefined' && __DEV__ && isReplayRunning()) {
+      // rc.4 — explicit "replay was on but ring drained empty" signal.
+      // Without this, "kinds=screenshot,sessionTrail" looks
+      // indistinguishable from `replay: off` even though the ticks
+      // were healthy upstream. Insight 2026-05-18 verify shape made
+      // this gap painful to triage.
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[sentori] replay drain empty (no frames buffered at captureException)',
+        'eventId=', event.id,
+      );
     }
     if (typeof __DEV__ !== 'undefined' && __DEV__) {
       // eslint-disable-next-line no-console
@@ -202,25 +215,49 @@ export const captureError = (error: Error, extras?: CaptureExtras): void => {
 
 /** v0.9.6 #2 — upload the wireframe replay ring as a `replay`
  *  attachment. Plain NDJSON (one snapshot per line) — server may
- *  gzip on storage; the network upload is base64. */
+ *  gzip on storage; the network upload is base64.
+ *
+ *  rc.4: route through `base64Utf8` so non-Latin-1 text inside any
+ *  walked TextView (Japanese / Chinese / em-dash etc.) doesn't blow
+ *  up the Hermes-spec `btoa`. The pre-rc.4 inline `btoa(ndjson)` path
+ *  threw `InvalidCharacterError` on those code points, the
+ *  surrounding catch swallowed it silently, and the replay
+ *  attachment never landed. Insight 2026-05-18 verify caught it
+ *  after rc.3's walker fix surfaced deep TextView content. Dev
+ *  logs replace the silent catch so the next failure shape is
+ *  visible. */
 async function captureAndAttachReplay(event: Event, ndjson: string): Promise<void> {
   try {
-    const base64 =
-      typeof globalThis.btoa === 'function'
-        ? globalThis.btoa(ndjson)
-        : Buffer.from(ndjson, 'utf8').toString('base64');
+    const base64 = base64Utf8(ndjson);
     const meta = await uploadAttachment(
       event.id,
       'replay',
       { base64, mediaType: 'application/x-ndjson' },
       { source: 'js' },
     );
-    if (meta) {
-      if (!event.attachments) event.attachments = [];
-      event.attachments.push(meta);
+    if (!meta) {
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[sentori] replay upload returned null',
+          'eventId=', event.id,
+          'ndjsonBytes=', ndjson.length,
+        );
+      }
+      return;
+    }
+    if (!event.attachments) event.attachments = [];
+    event.attachments.push(meta);
+  } catch (e) {
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[sentori] replay attachment threw',
+        'eventId=', event.id,
+        'ndjsonBytes=', ndjson.length,
+        e,
+      );
     }
-  } catch {
-    // best-effort
   }
 }
 
@@ -233,11 +270,7 @@ async function captureAndAttachStateSnapshots(
 ): Promise<void> {
   try {
     const payload = JSON.stringify({ snapshots });
-    const base64 =
-      typeof globalThis.btoa === 'function'
-        ? globalThis.btoa(payload)
-        : // Bun / node fallback
-          Buffer.from(payload, 'utf8').toString('base64');
+    const base64 = base64Utf8(payload);
     const meta = await uploadAttachment(
       event.id,
       'stateSnapshot',
@@ -267,12 +300,7 @@ async function captureAndAttachSessionTrail(event: Event): Promise<void> {
   const payload = sealTrail(trail);
   trail.clear();
   const json = JSON.stringify(payload);
-  // base64 the JSON for the `data:` URI multipart bridge (same
-  // trick the screenshot path uses).
-  const base64 =
-    typeof globalThis.btoa === 'function'
-      ? globalThis.btoa(unescape(encodeURIComponent(json)))
-      : Buffer.from(json, 'utf-8').toString('base64');
+  const base64 = base64Utf8(json);
   const attachment = await uploadAttachment(
     event.id,
     'sessionTrail',
@@ -289,6 +317,12 @@ async function captureAndAttachSessionTrail(event: Event): Promise<void> {
 
 export const captureException = captureError;
 
+/** rc.4 — test hook. The real replay attach path is internal so we
+ *  don't bloat the public surface, but the encoding bug Insight hit
+ *  on 2026-05-18 needs a behaviour-level test that exercises the
+ *  same code path captureException runs in production. */
+export const __captureAndAttachReplayForTests = captureAndAttachReplay;
+
 /** Phase 42 sub-D.08: per-session screenshot quota gate. */
 function allowScreenshot(): boolean {
   const budget = screenshotBudget();

package/src/index.ts

@@ -102,10 +102,13 @@ export {
 } from './state-snapshots';
 export { RageTapCapture } from './rage-tap';
 export {
+  probeNativeScreenshot,
+  probeNativeWireframe,
   startAnrWatchdog,
   stopAnrWatchdog,
   triggerNativeCrash,
 } from './native';
+export { drainReplay, startReplay, stopReplay } from './replay';
 export {
   endSession,
   markSessionCrashed,