@goliapkg/sentori-react-native 5.0.0 → 5.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goliapkg/sentori-react-native",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "description": "Sentori SDK for React Native — JS-layer error capture, native crash handlers (iOS / Android), batched transport, fetch + react-navigation tracing.",
   "license": "Apache-2.0 OR MIT",
   "author": "GOLIA K.K. <takagi@golia.jp> (https://golia.jp)",
@@ -46,6 +46,7 @@
     "sentori-rn-upload-source-bundle": "bin/sentori-rn-upload-source-bundle.cjs"
   },
   "files": [
+    "MIGRATION.md",
     "lib/",
     "src/",
     "bin/",
@@ -96,6 +97,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@goliapkg/sentori-core": "^2.0.0"
+    "@goliapkg/sentori-core": "^2.1.0"
   }
 }

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

@@ -0,0 +1,63 @@
+// The screens ring: capacity, drain shape, mask-query isolation,
+// and graceful absence on an old native build.
+
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+
+import { __resetForTests as resetMask, maskedNativeIds, registerMaskQuery } from '../mask';
+import {
+  __resetForTests as resetRing,
+  __setCaptureForTests,
+  drainScreenReplay,
+  startScreenReplay,
+} from '../replay-screens';
+
+afterEach(() => {
+  resetRing();
+  resetMask();
+});
+
+describe('mask query', () => {
+  test('unregistered → empty', () => {
+    expect(maskedNativeIds()).toEqual([]);
+  });
+
+  test('registered query flows through and filters junk', () => {
+    registerMaskQuery(() => ['camera-feed', 42 as unknown as string, 'user-email']);
+    expect(maskedNativeIds()).toEqual(['camera-feed', 'user-email']);
+  });
+
+  test('a throwing query masks nothing and never throws', () => {
+    registerMaskQuery(() => {
+      throw new Error('boom');
+    });
+    expect(maskedNativeIds()).toEqual([]);
+  });
+});
+
+describe('screens ring', () => {
+  test('drain on an empty ring is null (old native builds)', () => {
+    startScreenReplay(60);
+    expect(drainScreenReplay()).toBeNull();
+  });
+
+  test('drain emits NDJSON with negative relative timestamps', async () => {
+    let n = 0;
+    __setCaptureForTests(
+      mock(async () => ({ base64: `frame${(n += 1)}`, mediaType: 'image/jpeg' })),
+    );
+    startScreenReplay(60);
+    await new Promise((r) => setTimeout(r, 2_600));
+    const out = drainScreenReplay();
+    expect(out).not.toBeNull();
+    const lines = (out ?? '')
+      .split('\n')
+      .map((l) => JSON.parse(l) as { t: number; base64: string });
+    expect(lines.length).toBeGreaterThanOrEqual(1);
+    for (const l of lines) {
+      expect(l.t).toBeLessThanOrEqual(0);
+      expect(l.base64.startsWith('frame')).toBe(true);
+    }
+    // drain does not clear: a second error still sees the window
+    expect(drainScreenReplay()).not.toBeNull();
+  }, 10_000);
+});

package/src/__tests__/responsiveness-detector.test.ts

@@ -0,0 +1,74 @@
+// dead_button / sluggish_button verdict logic.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  DEAD_THRESHOLD,
+  DEAD_WINDOW_MS,
+  RESPONSE_WINDOW_MS,
+  SLUGGISH_COOLDOWN_MS,
+  SLUGGISH_MS,
+  classifyTap,
+  recordDeadTap,
+  recordSluggish,
+} from '../responsiveness-detector';
+
+describe('classifyTap', () => {
+  test('a fast reaction is responsive', () => {
+    expect(classifyTap(1000, [1300])).toBe('responsive');
+  });
+
+  test('a slow reaction is sluggish', () => {
+    expect(classifyTap(1000, [1000 + SLUGGISH_MS + 200])).toBe('sluggish');
+  });
+
+  test('no reaction inside the window is dead', () => {
+    expect(classifyTap(1000, [])).toBe('dead');
+    expect(classifyTap(1000, [1000 + RESPONSE_WINDOW_MS + 500])).toBe('dead');
+  });
+
+  test('signals from before the tap do not count', () => {
+    expect(classifyTap(1000, [900, 500])).toBe('dead');
+  });
+
+  test('the earliest reaction decides', () => {
+    expect(classifyTap(1000, [1000 + SLUGGISH_MS + 400, 1200])).toBe('responsive');
+  });
+});
+
+describe('recordDeadTap', () => {
+  test('warns only at the threshold, then resets', () => {
+    const buckets = new Map<number, number[]>();
+    let warned = 0;
+    for (let i = 0; i < DEAD_THRESHOLD * 2; i++) {
+      if (recordDeadTap(buckets, 7, 1000 + i * 100)) warned += 1;
+    }
+    expect(warned).toBe(2);
+  });
+
+  test('stale dead taps age out of the window', () => {
+    const buckets = new Map<number, number[]>();
+    recordDeadTap(buckets, 7, 0);
+    recordDeadTap(buckets, 7, 100);
+    // Third tap arrives after the window: the old two are gone.
+    expect(recordDeadTap(buckets, 7, DEAD_WINDOW_MS + 200)).toBe(false);
+  });
+
+  test('targets are independent', () => {
+    const buckets = new Map<number, number[]>();
+    recordDeadTap(buckets, 1, 0);
+    recordDeadTap(buckets, 1, 10);
+    expect(recordDeadTap(buckets, 2, 20)).toBe(false);
+    expect(recordDeadTap(buckets, 1, 30)).toBe(true);
+  });
+});
+
+describe('recordSluggish', () => {
+  test('cooldown gates repeat warns per target', () => {
+    const warns = new Map<number, number>();
+    expect(recordSluggish(warns, 7, 1000)).toBe(true);
+    expect(recordSluggish(warns, 7, 2000)).toBe(false);
+    expect(recordSluggish(warns, 7, 1000 + SLUGGISH_COOLDOWN_MS + 1)).toBe(true);
+    expect(recordSluggish(warns, 8, 2000)).toBe(true);
+  });
+});

package/src/config.ts

@@ -19,6 +19,7 @@ export type Config = {
   };
   /** B-type replay rolling buffer, seconds. 0 disables. */
   replaySeconds: number;
+  replayScreens: boolean;
   /** Sentori console output gate. Default `warn`: silent on the
    *  host's console unless something is genuinely broken. */
   logLevel?: LogLevel;

package/src/index.ts

@@ -62,6 +62,9 @@ export default sentori;
 export { init } from './init';
 export { ErrorBoundary } from './error-boundary';
 export { RageTapCapture } from './rage-tap';
+// Privacy: register a query returning nativeIDs that must be
+// blacked out in every captured frame (visual replay, screenshots).
+export { registerMaskQuery } from './mask';
 // Dev-panel helper: crash the native layer on purpose to exercise
 // the pending-crash upload pipeline. Not part of the 8-verb surface.
 export { triggerNativeCrash } from './native';

package/src/init.ts

@@ -17,7 +17,8 @@ import { checkColdStart } from './mobile-vitals';
 import { markNativeJsBridgeReady, setNativeConfig } from './native';
 import { shipNativePending } from './native-pending';
 import { drainReplay, startReplay } from './replay';
-import { drainOfflineQueue, startTransport, uploadAttachment } from './transport';
+import { drainScreenReplay, startScreenReplay } from './replay-screens';
+import { drainOfflineQueue, queueAttachment, startTransport } from './transport';
 
 let _initialized = false;
 
@@ -50,6 +51,7 @@ export const init = safeFn('init', (config: InitConfig): void => {
       slowApi: config.detect?.slowApi ?? false,
     },
     replaySeconds: config.replaySeconds ?? 30,
+    replayScreens: config.replayScreens ?? false,
     beforeSend: config.beforeSend,
   });
   setLogLevel(config.logLevel ?? 'warn');
@@ -69,19 +71,25 @@ export const init = safeFn('init', (config: InitConfig): void => {
   const replaySeconds = config.replaySeconds ?? 30;
   if (replaySeconds > 0) {
     startReplay({ mode: 'wireframe' });
+    // Visual ring is opt-in: screenshots can carry user content.
+    if (config.replayScreens === true) startScreenReplay(replaySeconds);
     registerEmitHook((event) => {
       if (event.kind !== 'error' && event.kind !== 'warn') return;
       if (!event.id) return;
       const lines = drainReplay();
-      if (!lines) return;
-      const base64 = base64Encode(lines);
-      if (!base64) return;
-      void uploadAttachment(
-        event.id,
-        'replay',
-        { base64, mediaType: 'application/x-sentori-replay' },
-        { source: 'js' },
-      );
+      if (lines) {
+        queueAttachment(event.id, 'replay', {
+          text: lines,
+          mediaType: 'application/x-sentori-replay',
+        });
+      }
+      const frames = drainScreenReplay();
+      if (frames) {
+        queueAttachment(event.id, 'screens', {
+          text: frames,
+          mediaType: 'application/x-sentori-screens',
+        });
+      }
     });
   }
 
@@ -102,18 +110,6 @@ export const init = safeFn('init', (config: InitConfig): void => {
   void drainOfflineQueue();
 });
 
-/** RN's Hermes has no btoa in older releases; go through base64.ts. */
-const base64Encode = (text: string): string | null => {
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { encodeBase64 } = require('./base64') as {
-      encodeBase64: (s: string) => string;
-    };
-    return encodeBase64(text);
-  } catch {
-    return null;
-  }
-};
 
 export const __resetForTests = (): void => {
   _initialized = false;

package/src/mask.ts

@@ -0,0 +1,42 @@
+// Screen masking — the privacy half of visual replay.
+//
+// The host registers a query returning the `nativeID`s of views
+// that must never appear in a screenshot (camera feeds, user
+// identity, payment fields). On iOS the native matcher accepts the
+// same value via either `nativeID` or `testID` (RN maps testID to
+// accessibilityIdentifier); on Android `nativeID` rides the view
+// tag. One prop, both platforms: use `nativeID`. Native paints black rectangles over
+// those subtrees in the same render pass, so the pixels never
+// leave the device.
+//
+// The query runs on every frame tick; keep it cheap (return a
+// cached array). A throwing query is swallowed and masks NOTHING
+// that tick — so a broken query fails visible-in-review rather
+// than silently, and can never take the capture path down.
+
+import { reportInternal } from '@goliapkg/sentori-core';
+
+type MaskQuery = () => string[];
+
+let _query: MaskQuery | null = null;
+
+/** Register (or with `null`, clear) the mask query. */
+export const registerMaskQuery = (query: MaskQuery | null): void => {
+  _query = query;
+};
+
+/** The current mask list; empty when unregistered or throwing. */
+export const maskedNativeIds = (): string[] => {
+  if (!_query) return [];
+  try {
+    const ids = _query();
+    return Array.isArray(ids) ? ids.filter((x) => typeof x === 'string') : [];
+  } catch (e) {
+    reportInternal('mask-query', e);
+    return [];
+  }
+};
+
+export const __resetForTests = (): void => {
+  _query = null;
+};

package/src/native.ts

@@ -69,6 +69,13 @@ type SentoriNativeModule = {
    * snapshot string or null on failure.
    */
   captureWireframe?: (maskedIds: string[]) => null | string
+
+  /** v5.1 — low-bitrate replay frame; absent on older native builds. */
+  captureReplayFrame?: (
+    maskedIds: string[],
+    longEdgePx: number,
+    quality: number,
+  ) => Promise<null | { base64: string; mediaType: string }>
   /**
    * v0.9.12 — diagnostic readout for the wireframe path. Cheap
    * synchronous call that returns the path the last `captureWireframe`
@@ -387,6 +394,32 @@ export function getRecentNativeException(): null | {
  * Callers must treat `null` as "no screenshot this round" — the
  * error event still ships, just without a thumbnail.
  */
+/** v5.1 — one low-bitrate frame for the screens replay ring.
+ *  Null on every failure mode (module unbound, method missing on an
+ *  older native build, capture failed); the ring just skips a beat. */
+let warnedNoReplayFrame = false
+export async function captureNativeReplayFrame(
+  maskedIds: string[],
+  longEdgePx: number,
+  quality: number,
+): Promise<null | { base64: string; mediaType: string }> {
+  const n = native()
+  if (!n) return null
+  if (!n.captureReplayFrame) {
+    if (!warnedNoReplayFrame) {
+      warnedNoReplayFrame = true
+      logger.warn('native', 'captureReplayFrame missing — rebuild the native app for visual replay')
+    }
+    return null
+  }
+  try {
+    return (await n.captureReplayFrame(maskedIds, longEdgePx, quality)) ?? null
+  } catch (e) {
+    logger.warn('native', 'captureReplayFrame threw', e)
+    return null
+  }
+}
+
 export async function captureNativeScreenshotWithMask(
   maskedIds: string[],
 ): Promise<null | { base64: string; mediaType: string }> {

package/src/rage-tap.tsx

@@ -13,11 +13,18 @@
 import React, { useCallback, useRef } from 'react';
 import { View, type GestureResponderEvent, type ViewProps } from 'react-native';
 
-import { pushSignal } from '@goliapkg/sentori-core';
+import { pushSignal, snapshotSignals } from '@goliapkg/sentori-core';
 
 import { getConfig } from './config';
 import { currentScreen } from './navigation';
 import { RAGE_THRESHOLD, RAGE_WINDOW_MS, recordTap } from './rage-tap-detector';
+import {
+  RESPONSE_WINDOW_MS,
+  SLUGGISH_MS,
+  classifyTap,
+  recordDeadTap,
+  recordSluggish,
+} from './responsiveness-detector';
 import { warnDetected } from './verbs';
 
 export function RageTapCapture({
@@ -25,13 +32,50 @@ export function RageTapCapture({
   ...rest
 }: ViewProps & { children?: React.ReactNode }): React.JSX.Element {
   const recent = useRef<Map<number, number[]>>(new Map());
+  const deadBuckets = useRef<Map<number, number[]>>(new Map());
+  const sluggishWarns = useRef<Map<number, number>>(new Map());
 
   const onTouchEnd = useCallback((e: GestureResponderEvent) => {
     try {
       const target = e.nativeEvent?.target;
       if (typeof target !== 'number') return;
+      const tapAt = Date.now();
       pushSignal('tap', { target });
-      if (!recordTap(recent.current, target, Date.now())) return;
+
+      // Responsiveness verdict lands after the window closes: the
+      // ring tells us whether the app reacted to this tap at all.
+      setTimeout(() => {
+        try {
+          const screen = currentScreen();
+          // Ring snapshots carry event-relative seconds (one decimal);
+          // rebase them onto the epoch for the classifier.
+          const nowMs = Date.now();
+          const times = snapshotSignals(nowMs)
+            .filter((s) => s.kind !== 'tap')
+            .map((s) => nowMs + s.t * 1000);
+          const outcome = classifyTap(tapAt, times);
+          if (outcome === 'dead' && recordDeadTap(deadBuckets.current, target, Date.now())) {
+            warnDetected(
+              'dead_button',
+              { screen, element: String(target) },
+              { windowMs: RESPONSE_WINDOW_MS },
+            );
+          } else if (
+            outcome === 'sluggish' &&
+            recordSluggish(sluggishWarns.current, target, Date.now())
+          ) {
+            warnDetected(
+              'sluggish_button',
+              { screen, element: String(target) },
+              { thresholdMs: SLUGGISH_MS },
+            );
+          }
+        } catch {
+          // detector bug must never surface
+        }
+      }, RESPONSE_WINDOW_MS + 50);
+
+      if (!recordTap(recent.current, target, tapAt)) return;
       if (getConfig()?.detect.rageTap === false) return;
       warnDetected(
         'rage_tap',

package/src/replay-screens.ts

@@ -0,0 +1,95 @@
+// B-type visual replay — a rolling ring of low-bitrate screenshots.
+//
+// OFF by default (privacy + the client-zero-cost rule): enable
+// with `init({ replayScreens: true })`. One frame every 2.5 s at
+// 360 px / q≈0.35 runs 10-20 KB, so the 60 s window a triage
+// actually wants is ~24 frames and a few hundred KB — and those
+// bytes only ever leave the device when an error/warn fires,
+// stapled to that event as a `screens` attachment.
+//
+// Older native builds have no `captureReplayFrame`; the ring then
+// simply stays empty (one warn) — wireframe replay still works.
+
+import { logger } from '@goliapkg/sentori-core';
+
+import { maskedNativeIds } from './mask';
+import { captureNativeReplayFrame } from './native';
+
+type CaptureFn = typeof captureNativeReplayFrame;
+let _capture: CaptureFn = captureNativeReplayFrame;
+
+/** Frame cadence. 2.5 s keeps the main-thread cost of a capture
+ *  (~1-3 ms) far under the 1 % occupancy budget. */
+const TICK_INTERVAL_MS = 2_500;
+/** Long edge of a replay frame, px. Enough to read a screen's
+ *  layout and large text; deliberately not enough to read a
+ *  document over someone's shoulder. */
+const FRAME_LONG_EDGE_PX = 360;
+/** JPEG/WebP quality for replay frames. */
+const FRAME_QUALITY = 0.35;
+
+type ScreenFrame = { t: number; base64: string; mediaType: string };
+
+let _ring: ScreenFrame[] = [];
+let _capacity = 0;
+let _timer: ReturnType<typeof setInterval> | null = null;
+let _capturing = false;
+
+/** Start the ring. `windowSeconds` is how far back the replay
+ *  reaches when an event fires. */
+export const startScreenReplay = (windowSeconds: number): void => {
+  if (_timer !== null || windowSeconds <= 0) return;
+  _capacity = Math.max(1, Math.ceil((windowSeconds * 1000) / TICK_INTERVAL_MS));
+  _timer = setInterval(() => {
+    void tick();
+  }, TICK_INTERVAL_MS);
+  logger.debug('replay-screens', `ring started: ${_capacity} slots / ${windowSeconds}s`);
+};
+
+const tick = async (): Promise<void> => {
+  // Never overlap captures: a slow frame skips a beat instead of
+  // queueing main-thread work.
+  if (_capturing) return;
+  _capturing = true;
+  try {
+    const frame = await _capture(maskedNativeIds(), FRAME_LONG_EDGE_PX, FRAME_QUALITY);
+    if (frame) {
+      _ring.push({ t: Date.now(), ...frame });
+      if (_ring.length > _capacity) _ring.splice(0, _ring.length - _capacity);
+    }
+  } finally {
+    _capturing = false;
+  }
+};
+
+/** Drain the ring into the wire form: NDJSON, one frame per line,
+ *  `t` rewritten to seconds-before-now (negative, so the player
+ *  reads "-42.5s → 0s"). Returns null when empty. The ring is NOT
+ *  cleared — a second error two seconds later should still see
+ *  the minute before it. */
+export const drainScreenReplay = (): null | string => {
+  if (_ring.length === 0) return null;
+  const now = Date.now();
+  return _ring
+    .map((f) =>
+      JSON.stringify({
+        t: Number(((f.t - now) / 1000).toFixed(1)),
+        mediaType: f.mediaType,
+        base64: f.base64,
+      }),
+    )
+    .join('\n');
+};
+
+export const __resetForTests = (): void => {
+  if (_timer !== null) clearInterval(_timer);
+  _timer = null;
+  _ring = [];
+  _capacity = 0;
+  _capturing = false;
+  _capture = captureNativeReplayFrame;
+};
+
+export const __setCaptureForTests = (fn: CaptureFn): void => {
+  _capture = fn;
+};

package/src/responsiveness-detector.ts

@@ -0,0 +1,66 @@
+// dead_button / sluggish_button — pure detection logic.
+//
+// A tap is judged by what the signal ring records after it: any
+// non-tap signal (navigation, network, a trace point) inside the
+// response window counts as the app reacting.
+//
+//   - responsive: a reaction within SLUGGISH_MS.
+//   - sluggish:   a reaction, but slower than SLUGGISH_MS.
+//   - dead:       no reaction at all inside RESPONSE_WINDOW_MS.
+//
+// One dead tap is usually decoration (backgrounds, labels), so a
+// dead_button warn needs DEAD_THRESHOLD dead taps on the SAME
+// target inside DEAD_WINDOW_MS — a user repeatedly poking one
+// unresponsive control, at a slower cadence than a rage tap.
+// Sluggish warns are per-target cooldown-limited so one slow
+// button files one issue, not one per tap.
+
+export const RESPONSE_WINDOW_MS = 1_500;
+export const SLUGGISH_MS = 1_000;
+export const DEAD_THRESHOLD = 3;
+export const DEAD_WINDOW_MS = 30_000;
+export const SLUGGISH_COOLDOWN_MS = 60_000;
+
+export type TapOutcome = 'dead' | 'responsive' | 'sluggish';
+
+/** Judge one tap by the ring signals that followed it.
+ *  `signalTimes` are the timestamps (ms) of every non-tap signal
+ *  recorded after `tapAt`. */
+export function classifyTap(tapAt: number, signalTimes: number[]): TapOutcome {
+  const first = signalTimes
+    .filter((t) => t > tapAt && t - tapAt <= RESPONSE_WINDOW_MS)
+    .sort((a, b) => a - b)[0];
+  if (first === undefined) return 'dead';
+  return first - tapAt > SLUGGISH_MS ? 'sluggish' : 'responsive';
+}
+
+/** Per-target dead-tap bookkeeping. Returns true when this dead tap
+ *  crosses the warn threshold (and clears the bucket so the next
+ *  warn needs a fresh run of dead taps). */
+export function recordDeadTap(
+  buckets: Map<number, number[]>,
+  target: number,
+  now: number,
+): boolean {
+  const fresh = (buckets.get(target) ?? []).filter((t) => now - t <= DEAD_WINDOW_MS);
+  fresh.push(now);
+  if (fresh.length >= DEAD_THRESHOLD) {
+    buckets.delete(target);
+    return true;
+  }
+  buckets.set(target, fresh);
+  return false;
+}
+
+/** Per-target sluggish cooldown. Returns true when a warn should
+ *  fire (and stamps the cooldown). */
+export function recordSluggish(
+  lastWarnAt: Map<number, number>,
+  target: number,
+  now: number,
+): boolean {
+  const last = lastWarnAt.get(target);
+  if (last !== undefined && now - last < SLUGGISH_COOLDOWN_MS) return false;
+  lastWarnAt.set(target, now);
+  return true;
+}

package/src/transport.ts

@@ -82,12 +82,53 @@ export const flush = async (): Promise<void> => {
 
   try {
     await sendWithRetry(envelope, config.ingestUrl, config.token);
+    // Only now do the events exist server-side — release their
+    // queued attachments. Uploading before this point 404s: the
+    // attachment races the 5s event batch and always wins.
+    for (const ev of events) {
+      if (ev.id) void sendQueuedAttachments(ev.id);
+    }
   } catch {
     // Events survive offline; assert deltas are cheap enough to lose.
+    // Their attachments are memory-only and lost with the process —
+    // documented; a replay is context, not the crash report itself.
     await persist(events);
   }
 };
 
+// ── attachments (deferred until their event is delivered) ─────────
+
+type QueuedAttachment = {
+  kind: import('@goliapkg/sentori-core').AttachmentKind;
+  blob: { base64?: string; text?: string; mediaType: string };
+  source: 'android' | 'ios' | 'js';
+};
+
+const _pendingAttachments = new Map<string, QueuedAttachment[]>();
+
+/** Attach a blob to an event that is still in the batch queue. It
+ *  uploads right after the batch containing the event lands, so the
+ *  server always already knows the event. */
+export const queueAttachment = (
+  eventId: string,
+  kind: QueuedAttachment['kind'],
+  blob: QueuedAttachment['blob'],
+  opts: { source?: QueuedAttachment['source'] } = {},
+): void => {
+  const list = _pendingAttachments.get(eventId) ?? [];
+  list.push({ kind, blob, source: opts.source ?? 'js' });
+  _pendingAttachments.set(eventId, list);
+};
+
+const sendQueuedAttachments = async (eventId: string): Promise<void> => {
+  const list = _pendingAttachments.get(eventId);
+  if (!list) return;
+  _pendingAttachments.delete(eventId);
+  for (const a of list) {
+    await uploadAttachment(eventId, a.kind, a.blob, { source: a.source });
+  }
+};
+
 const sendWithRetry = async (
   envelope: BatchEnvelope,
   ingestUrl: string,
@@ -206,26 +247,40 @@ export const drainOfflineQueue = async (): Promise<void> => {
 export const uploadAttachment = async (
   eventId: string,
   kind: import('@goliapkg/sentori-core').AttachmentKind,
-  blob: { base64: string; mediaType: string },
+  blob: { base64?: string; text?: string; mediaType: string },
   opts: { source?: 'android' | 'ios' | 'js' } = {},
 ): Promise<{ ref: string } | null> => {
   const config = getConfig();
   if (!config) return null;
   const url = `${config.ingestUrl}/v1/events/${encodeURIComponent(eventId)}/attachments/${encodeURIComponent(kind)}`;
 
-  const form = new FormData();
-  form.append('file', {
-    name: `${kind}.bin`,
-    type: blob.mediaType,
-    uri: `data:${blob.mediaType};base64,${blob.base64}`,
-  } as unknown as Blob);
-  form.append('source', opts.source ?? 'js');
+  // Hand-built multipart. React Native's FormData file part wants a
+  // `uri`, and its `data:` URI form throws a bare network error on
+  // iOS — this shipped untested and every JS attachment silently
+  // died. Text payloads (replay/screens NDJSON) embed directly;
+  // base64 payloads embed as base64 with the transfer-encoding
+  // header so the server knows to decode.
+  const boundary = `----sentori-${eventId}`;
+  const isText = typeof blob.text === 'string';
+  const content = isText ? (blob.text ?? '') : (blob.base64 ?? '');
+  const encodingHeader = isText ? '' : 'Content-Transfer-Encoding: base64\r\n';
+  const wireBody =
+    `--${boundary}\r\n` +
+    `Content-Disposition: form-data; name="file"; filename="${kind}.bin"\r\n` +
+    `Content-Type: ${blob.mediaType}\r\n` +
+    encodingHeader +
+    `\r\n${content}\r\n` +
+    `--${boundary}\r\n` +
+    `Content-Disposition: form-data; name="source"\r\n` +
+    `\r\n${opts.source ?? 'js'}\r\n` +
+    `--${boundary}--\r\n`;
 
   try {
     const resp = await fetch(url, {
-      body: form,
+      body: wireBody,
       headers: {
         Authorization: `Bearer ${config.token}`,
+        'Content-Type': `multipart/form-data; boundary=${boundary}`,
         'Sentori-Sdk': `react-native/${SDK_VERSION}`,
       },
       method: 'POST',