@bugsession/react-native 0.1.0-beta.3 → 0.1.0-beta.5

package/src/index.tsx

@@ -1,9 +1,12 @@
 import React from 'react';
-import { Animated, PanResponder, Pressable, StyleSheet, Text, View, useWindowDimensions, type PressableProps, type StyleProp, type ViewStyle, Platform } from 'react-native';
-import { Collector, instrumentFetch, safeText, safeUrl, SessionClock } from './core';
+import { Dimensions, Pressable, StyleSheet, Text, View, type PressableProps, Platform } from 'react-native';
+import { createTrigger, type IndicatorPhase } from './trigger';
+export type { Annotation, BugSessionTriggerProps, IndicatorPhase } from './trigger';
+import { Collector, ignoreRequests, instrumentFetch, instrumentXhr, safeText, safeUrl, SessionClock, Telemetry, type Evidence } from './core';
+import { createCapture } from './touches';
 import { alignNativeRecording, type NativeCaptureAdapter } from './capture';
 export type { NativeCaptureAdapter } from './capture';
-export { Collector, SessionClock, safeText, safeUrl } from './core';
+export { Collector, SessionClock, Telemetry, safeText, safeUrl } from './core';
 
 export type AudioAdapter = {
   prepare(): Promise<void>;
@@ -11,31 +14,81 @@ export type AudioAdapter = {
   stop(): Promise<string | null>;
   upload(url: string, uri: string, headers?: Record<string, string>): Promise<void>;
 };
-export type BugSessionOptions = { recorderUrl: string; recorderToken?: string; audio?: AudioAdapter; capture?: NativeCaptureAdapter; device: Record<string, unknown>; application: Record<string, unknown> };
-export type BugSessionTriggerProps = {
-  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-  offset?: number;
-  draggable?: boolean;
-  style?: StyleProp<ViewStyle>;
-  accessibilityLabel?: string;
-  children?: React.ReactNode;
-  onError?: (error: unknown) => void;
+export type BugSessionOptions = {
+  recorderUrl: string;
+  recorderToken?: string;
+  audio?: AudioAdapter;
+  capture?: NativeCaptureAdapter;
+  device: Record<string, unknown>;
+  application: Record<string, unknown>;
+  /**
+   * Seconds of app events (logs, errors, network metadata, actions, navigation; never video or audio)
+   * kept in memory before a recording starts and attached to it. Defaults to 60, max 300; 0 disables.
+   */
+  preRecordSeconds?: number;
+  /**
+   * Seconds of app events still collected after the tester stops, while the video uploads,
+   * so a request or error that lands just after Stop is kept. Defaults to 5, max 30; 0 disables.
+   */
+  postRecordSeconds?: number;
 };
+export type BugSessionErrorBoundaryProps = { error: Error; retry: () => void | Promise<void> };
 type ErrorUtilsType = { getGlobalHandler(): (e: Error, fatal?: boolean) => void; setGlobalHandler(handler: (e: Error, fatal?: boolean) => void): void };
-const globals = globalThis as typeof globalThis & { ErrorUtils?: ErrorUtilsType };
+type RejectionTracker = { allRejections: boolean; onUnhandled(id: number, rejection: unknown): void; onHandled(id: number): void };
+const globals = globalThis as typeof globalThis & {
+  ErrorUtils?: ErrorUtilsType;
+  HermesInternal?: { enablePromiseRejectionTracker?(options: RejectionTracker): void };
+};
 let options: BugSessionOptions;
 let collector: Collector | null = null;
+const telemetry = new Telemetry();
+let installed = false;
+let preRecordEvents: Evidence[] = [];
+const MAX_POST_RECORD_SECONDS = 30;
 let session: { id: string; videoStartMs: number; audioStartMs: number; uncertaintyMs: number; captureBackend: 'adb' | 'replaykit' | 'mediaprojection'; nativeOffsetMs?: number; nativeUncertaintyMs?: number } | null = null;
 let state: 'idle' | 'starting' | 'recording' | 'stopping' = 'idle';
-let restore: (() => void) | null = null;
 let currentScreen = 'Home';
 let rawFetch: typeof fetch;
-let triggerPosition: { left: number; top: number } | null = null;
-const triggerSize = 58;
-function clampTriggerPosition(point: { left: number; top: number }, width: number, height: number) {
+// Status shown by the trigger's indicator; also reflects start()/stop() called directly by the app.
+let phase: IndicatorPhase = { kind: 'idle' };
+let phaseTimer: ReturnType<typeof setTimeout> | undefined;
+const phaseListeners = new Set<() => void>();
+function setPhase(next: IndicatorPhase) {
+  phase = next;
+  clearTimeout(phaseTimer);
+  if (next.kind === 'sent' || next.kind === 'failed') phaseTimer = setTimeout(() => setPhase({ kind: 'idle' }), next.kind === 'sent' ? 3000 : 6000);
+  phaseListeners.forEach(listener => listener());
+}
+function compact(values: Record<string, unknown>) {
+  return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined && value !== null && value !== ''));
+}
+/**
+ * App and device facts for the recording's metadata. Native values (bundle id, hardware
+ * model) come from the capture module when available; values passed to configure() win.
+ */
+async function recordingContext() {
+  const constants = (Platform.constants ?? {}) as Record<string, unknown>;
+  const rn = constants.reactNativeVersion as { major: number; minor: number; patch: number } | undefined;
+  const screen = Dimensions.get('screen');
+  let locale: string | undefined;
+  let timeZone: string | undefined;
+  try { ({ locale, timeZone } = Intl.DateTimeFormat().resolvedOptions()); } catch { /* Intl unavailable */ }
+  const device: Record<string, unknown> = {
+    platform: Platform.OS,
+    osVersion: Platform.OS === 'android' ? constants.Release : String(Platform.Version),
+    screen: { width: Math.round(screen.width), height: Math.round(screen.height), scale: screen.scale },
+    locale, timeZone,
+    ...(Platform.OS === 'android' ? { model: constants.Model, manufacturer: constants.Manufacturer } : { idiom: constants.interfaceIdiom }),
+  };
+  const application: Record<string, unknown> = {
+    reactNative: rn ? `${rn.major}.${rn.minor}.${rn.patch}` : undefined,
+    jsEngine: globals.HermesInternal ? 'hermes' : 'jsc',
+    buildType: __DEV__ ? 'development' : 'release',
+  };
+  const native = await options.capture?.appContext?.().catch(() => null) ?? null;
   return {
-    left: Math.max(0, Math.min(point.left, Math.max(0, width - triggerSize))),
-    top: Math.max(0, Math.min(point.top, Math.max(0, height - triggerSize))),
+    device: compact({ ...device, ...native?.device, ...options.device }),
+    application: compact({ ...application, ...native?.application, ...options.application }),
   };
 }
 function authHeaders(): Record<string, string> {
@@ -58,38 +111,76 @@ async function request(path: string, data?: unknown) {
   if (!response.ok) throw new Error(`Recorder ${response.status}: ${await response.text()}`);
   return response.json();
 }
-function install(c: Collector) {
-  const originalFetch = globalThis.fetch;
-  const wrappedFetch = instrumentFetch(rawFetch, c);
-  globalThis.fetch = wrappedFetch;
-  const originals = { log: console.log, warn: console.warn, error: console.error };
-  for (const level of ['log', 'warn', 'error'] as const) {
+// Installed once at configure() for the app's lifetime, so events from before a
+// recording starts can be attached to it (see Telemetry).
+function install() {
+  installed = true;
+  // The recorder itself, and in development Metro's own symbolication and log requests.
+  ignoreRequests(url => (!!options && url.startsWith(options.recorderUrl)) || (__DEV__ && /\/(symbolicate|logs)(\?|$)/.test(url)));
+  globalThis.fetch = instrumentFetch(rawFetch, telemetry);
+  instrumentXhr((globalThis as { XMLHttpRequest?: Parameters<typeof instrumentXhr>[0] }).XMLHttpRequest, telemetry);
+  for (const level of ['log', 'info', 'debug', 'warn', 'error'] as const) {
+    const original = console[level];
     console[level] = (...args: unknown[]) => {
-      c.add(level === 'error' ? 'error' : 'log', { level, message: args.map(safeText).join(' '), source: 'console', stack: args.find(a => a instanceof Error)?.stack ? safeText((args.find(a => a instanceof Error) as Error).stack) : undefined });
-      originals[level](...args);
+      if (telemetry.active && !(level === 'error' && repeatsCapturedError(args))) {
+        const error = args.find((a): a is Error => a instanceof Error);
+        telemetry.add(level === 'error' ? 'error' : 'log', { level, message: args.map(safeText).join(' '), source: 'console', stack: error?.stack ? safeText(error.stack) : undefined, screen: currentScreen });
+      }
+      original(...args);
     };
   }
   const utils = globals.ErrorUtils;
   const handler = utils?.getGlobalHandler();
-  const onError = (error: Error, fatal?: boolean) => {
+  if (utils && handler) utils.setGlobalHandler((error, fatal) => {
     captureError(error, fatal ? 'fatal' : 'uncaught');
-    handler?.(error, fatal);
-  };
-  if (utils && handler) utils.setGlobalHandler(onError);
-  return () => {
-    if (globalThis.fetch === wrappedFetch) globalThis.fetch = originalFetch;
-    for (const level of ['log', 'warn', 'error'] as const) console[level] = originals[level];
-    if (utils?.getGlobalHandler() === onError && handler) utils.setGlobalHandler(handler);
-  };
+    handler(error, fatal);
+  });
+  // React Native only tracks unhandled rejections in development, and reports them
+  // through ExceptionsManager rather than the global handler. Track them in every
+  // build, and keep React Native's development behavior (LogBox) by forwarding.
+  globals.HermesInternal?.enablePromiseRejectionTracker?.({
+    allRejections: true,
+    onUnhandled: (id, rejection) => {
+      captureError(rejection instanceof Error ? rejection : new Error(rejectionMessage(rejection)), 'unhandled-rejection');
+      if (__DEV__) handler?.(new Error(`Uncaught (in promise, id: ${id}): "${rejectionMessage(rejection)}"`), false);
+    },
+    onHandled: id => {
+      if (__DEV__) console.warn(`Promise rejection handled (id: ${id})`);
+    },
+  });
+}
+function rejectionMessage(rejection: unknown) {
+  if (rejection instanceof Error) return rejection.toString();
+  if (typeof rejection === 'string') return rejection;
+  try { return JSON.stringify(rejection) ?? String(rejection); } catch { return String(rejection); }
+}
+// React Native also prints captured errors (such as unhandled rejections in development)
+// through console.error; those repeats are skipped for a moment after capture.
+const recentErrors: { message: string; at: number }[] = [];
+function repeatsCapturedError(args: unknown[]) {
+  const now = Date.now();
+  while (recentErrors.length && now - recentErrors[0].at > 2000) recentErrors.shift();
+  if (!recentErrors.length) return false;
+  const printed = args.map(a => a instanceof Error ? a.message : typeof a === 'string' ? a : '').join(' ');
+  return recentErrors.some(e => e.message.length > 8 && printed.includes(e.message));
 }
 function captureError(error: unknown, source = 'boundary') {
-  collector?.add('error', { source, message: safeText(error), stack: error instanceof Error ? safeText(error.stack ?? '') : undefined, screen: currentScreen });
+  if (!telemetry.active) return;
+  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
+  if (message && repeatsCapturedError([message])) return;
+  if (message) recentErrors.push({ message: message.slice(0, 200), at: Date.now() });
+  telemetry.add('error', { source, message: safeText(error), stack: error instanceof Error ? safeText(error.stack ?? '') : undefined, screen: currentScreen });
 }
 
 export const BugSession = {
   configure(config: BugSessionOptions) {
     if (state !== 'idle') throw new Error('Cannot configure an active BugSession');
     options = { ...config, recorderUrl: config.recorderUrl.replace(/\/$/, '') };
+    telemetry.configure((config.preRecordSeconds ?? 60) * 1000);
+    if (!installed) {
+      rawFetch = globalThis.fetch.bind(globalThis);
+      install();
+    }
   },
   get status() { return state; },
   async start() {
@@ -99,7 +190,7 @@ export const BugSession = {
     if (Platform.OS === 'android' && !options.audio) throw new Error('Android needs a microphone adapter');
     if (state !== 'idle') throw new Error(`BugSession is ${state}`);
     state = 'starting';
-    rawFetch = globalThis.fetch.bind(globalThis);
+    setPhase({ kind: 'starting' });
     let createdId: string | null = null;
     let audioStarted = false;
     const isIOS = Platform.OS === 'ios';
@@ -112,7 +203,8 @@ export const BugSession = {
       const best = await calibrate(clock, async () => (await request('/clock')).monoMs);
       collector = new Collector(clock);
       const captureBackend = isIOS ? 'replaykit' : useNativeCapture ? 'mediaprojection' : 'adb';
-      const result = await request('/sessions/start', { device: options.device, application: options.application, captureBackend, startedAt: new Date(Date.now() - clock.now()).toISOString() });
+      const context = await recordingContext();
+      const result = await request('/sessions/start', { device: context.device, application: context.application, captureBackend, startedAt: new Date(Date.now() - clock.now()).toISOString() });
       createdId = result.id;
       const nativeStart = useNativeCapture ? await options.capture!.start() : undefined;
       const audioStartMs = clock.now();
@@ -126,24 +218,42 @@ export const BugSession = {
         uncertaintyMs: best.rtt / 2, captureBackend,
         ...(nativeClock ? { nativeOffsetMs: nativeClock.offset, nativeUncertaintyMs: nativeClock.rtt / 2 } : {}),
       };
-      restore = install(collector);
+      preRecordEvents = telemetry.begin(collector);
       state = 'recording';
+      setPhase({ kind: 'recording', startedAt: Date.now() });
       collector.add('navigation', { from: null, to: currentScreen });
       return session.id;
     } catch (error) {
       if (useNativeCapture) await options.capture?.cancel().catch(() => {});
       if (audioStarted) await options.audio!.stop().catch(() => null);
       if (createdId) await request(`/sessions/${createdId}/abort`, {}).catch(() => {});
-      collector = null; session = null; state = 'idle'; throw error;
+      telemetry.end(); preRecordEvents = [];
+      collector = null; session = null; state = 'idle';
+      setPhase({ kind: 'failed', message: safeText(error) });
+      throw error;
     }
   },
   async stop() {
     if (state !== 'recording' || !session || !collector) throw new Error('No recording is active');
     state = 'stopping';
+    setPhase({ kind: 'uploading' });
     const c = collector;
     const active = session;
     c.add('session-stop', {});
-    restore?.(); restore = null;
+    const stoppedAtMs = c.clock.now();
+    const postRecordMs = Math.max(0, Math.min(options.postRecordSeconds ?? 5, MAX_POST_RECORD_SECONDS)) * 1000;
+    // Sent separately from `events` so recorders that predate pre/post-record support ignore them.
+    const before = preRecordEvents;
+    preRecordEvents = [];
+    // App events keep flowing to this session while media uploads; anything after Stop is
+    // reported separately as post-recording evidence.
+    const split = () => {
+      telemetry.end();
+      return {
+        events: c.events.filter(e => e.timestampMs <= stoppedAtMs),
+        after: c.events.filter(e => e.timestampMs > stoppedAtMs && e.timestampMs <= stoppedAtMs + postRecordMs).slice(0, 1000).map(e => ({ ...e, postRecording: true })),
+      };
+    };
     try {
       let media: Record<string, unknown>;
       if (active.captureBackend === 'replaykit') {
@@ -169,25 +279,67 @@ export const BugSession = {
         await options.audio!.upload(`${options.recorderUrl}/sessions/${active.id}/audio`, uri, authHeaders());
         media = { ...active, audioEndMs };
       }
-      return await request(`/sessions/${active.id}/stop`, {
-        durationMs: c.clock.now(), events: c.events, droppedEvents: c.dropped,
+      const remainingMs = stoppedAtMs + postRecordMs - c.clock.now();
+      if (remainingMs > 0) await new Promise(resolve => setTimeout(resolve, remainingMs));
+      const { events, after } = split();
+      const result = await request(`/sessions/${active.id}/stop`, {
+        durationMs: stoppedAtMs, events, droppedEvents: c.dropped, preRecordEvents: before,
+        ...(after.length ? { postRecordEvents: after } : {}),
         media,
       });
+      setPhase({ kind: 'sent' });
+      return result;
     } catch (error) {
       if (active.captureBackend !== 'adb') await options.capture!.cancel().catch(() => {});
       // Release the device recorder, but preserve partial files for recovery.
-      await request(`/sessions/${active.id}/abort`, { reason: safeText(error), events: c.events, media: active, durationMs: c.clock.now() }).catch(() => {});
+      const { events, after } = split();
+      await request(`/sessions/${active.id}/abort`, { reason: safeText(error), events, preRecordEvents: before, ...(after.length ? { postRecordEvents: after } : {}), media: active, durationMs: stoppedAtMs }).catch(() => {});
+      setPhase({ kind: 'failed', message: safeText(error) });
       throw error;
-    } finally { collector = null; session = null; state = 'idle'; }
+    } finally { telemetry.end(); collector = null; session = null; state = 'idle'; }
   },
   trackAction(action: { name: string; screen?: string }) {
-    collector?.add('action', { target: safeText(action.name), screen: safeText(action.screen ?? currentScreen) });
+    if (telemetry.active) telemetry.add('action', { target: safeText(action.name), screen: safeText(action.screen ?? currentScreen) });
   },
   trackNavigation(screen: string) {
-    if (currentScreen !== screen) collector?.add('navigation', { from: currentScreen, to: screen });
+    if (currentScreen !== screen && telemetry.active) telemetry.add('navigation', { from: currentScreen, to: screen });
     currentScreen = screen;
   },
   captureError,
+  /**
+   * Wrap the app once (inside the navigator's container, around your screens) to record
+   * every tap automatically: position, current screen and the element's label when available.
+   */
+  Capture: createCapture(() => telemetry.active ? tap => {
+    telemetry.add('action', { target: safeText(tap.label ?? `Tap at (${tap.x}, ${tap.y})`), screen: currentScreen, x: tap.x, y: tap.y, auto: true });
+  } : null),
+  Trigger: createTrigger({
+    getPhase: () => phase,
+    subscribe(listener) { phaseListeners.add(listener); return () => { phaseListeners.delete(listener); }; },
+    async toggle() {
+      if (state === 'recording') await BugSession.stop();
+      else if (state === 'idle') await BugSession.start();
+    },
+    fail(error) { if (phase.kind !== 'failed') setPhase({ kind: 'failed', message: safeText(error) }); },
+    onAudioLevel: listener => options?.capture?.onAudioLevel?.(listener) ?? null,
+    safeAreaInsets: async () => options?.capture?.safeAreaInsets ? options.capture.safeAreaInsets() : null,
+    annotate(annotation) { if (state === 'recording') telemetry.add('annotation', { ...annotation, screen: currentScreen }); },
+  }),
+  /**
+   * Expo Router error boundary that reports render errors (which never reach the
+   * global error handler). In a route or layout file:
+   * `export const ErrorBoundary = BugSession.ErrorBoundary;`
+   */
+  ErrorBoundary({ error, retry }: BugSessionErrorBoundaryProps) {
+    React.useEffect(() => { captureError(error, 'render'); }, [error]);
+    return <View style={styles.boundary}>
+      <Text style={styles.boundaryTitle}>Something went wrong</Text>
+      <Text style={styles.boundaryMessage}>{error.message}</Text>
+      <Pressable accessibilityRole="button" onPress={() => { void retry(); }} style={styles.boundaryRetry}>
+        <Text style={styles.boundaryRetryText}>Try again</Text>
+      </Pressable>
+    </View>;
+  },
   /** Use with NavigationContainer.onStateChange for non-Expo React Navigation apps. */
   navigationListener(ref: { getCurrentRoute(): { name: string } | undefined }) {
     return () => { const route = ref.getCurrentRoute(); if (route) BugSession.trackNavigation(route.name); };
@@ -195,84 +347,12 @@ export const BugSession = {
   Touchable({ name, screen, onPress, ...props }: PressableProps & { name: string; screen?: string }) {
     return <Pressable {...props} onPress={e => { BugSession.trackAction({ name, screen }); onPress?.(e); }} />;
   },
-  Trigger({ position = 'bottom-right', offset = 24, draggable = true, style, accessibilityLabel, children, onError }: BugSessionTriggerProps) {
-    const { width, height } = useWindowDimensions();
-    const [point, setPoint] = React.useState(() => triggerPosition
-      ? clampTriggerPosition(triggerPosition, width, height)
-      : clampTriggerPosition({
-        left: position.includes('right') ? width - triggerSize - offset : offset,
-        top: position.includes('bottom') ? height - triggerSize - offset : offset,
-      }, width, height));
-    const pointRef = React.useRef(point);
-    pointRef.current = point;
-    const drag = React.useRef<Animated.ValueXY | null>(null);
-    if (!drag.current) drag.current = new Animated.ValueXY();
-    const dragStart = React.useRef(point);
-    React.useEffect(() => {
-      const next = clampTriggerPosition(pointRef.current, width, height);
-      pointRef.current = next;
-      setPoint(next);
-      if (triggerPosition) triggerPosition = next;
-      drag.current?.setValue({ x: 0, y: 0 });
-    }, [width, height]);
-    const responder = React.useMemo(() => PanResponder.create({
-      onStartShouldSetPanResponder: () => false,
-      onMoveShouldSetPanResponder: (_, gesture) => draggable && Math.hypot(gesture.dx, gesture.dy) > 7,
-      onPanResponderGrant: () => { dragStart.current = pointRef.current; },
-      onPanResponderMove: (_, gesture) => {
-        const next = clampTriggerPosition({ left: dragStart.current.left + gesture.dx, top: dragStart.current.top + gesture.dy }, width, height);
-        drag.current?.setValue({ x: next.left - dragStart.current.left, y: next.top - dragStart.current.top });
-      },
-      onPanResponderRelease: (_, gesture) => {
-        const next = clampTriggerPosition({ left: dragStart.current.left + gesture.dx, top: dragStart.current.top + gesture.dy }, width, height);
-        triggerPosition = next;
-        pointRef.current = next;
-        setPoint(next);
-        drag.current?.setValue({ x: 0, y: 0 });
-      },
-      onPanResponderTerminate: (_, gesture) => {
-        const next = clampTriggerPosition({ left: dragStart.current.left + gesture.dx, top: dragStart.current.top + gesture.dy }, width, height);
-        triggerPosition = next;
-        pointRef.current = next;
-        setPoint(next);
-        drag.current?.setValue({ x: 0, y: 0 });
-      },
-    }), [draggable, width, height]);
-    const [busy, setBusy] = React.useState(false);
-    const recording = state === 'recording';
-    const toggle = async () => {
-      if (busy) return;
-      setBusy(true);
-      try {
-        if (state === 'recording') await BugSession.stop();
-        else await BugSession.start();
-      } catch (error) { onError?.(error); }
-      finally { setBusy(false); }
-    };
-    return <View pointerEvents="box-none" style={styles.triggerLayer}>
-      <Animated.View {...(draggable ? responder.panHandlers : {})} style={[styles.triggerPosition, { left: point.left, top: point.top, transform: drag.current?.getTranslateTransform() }]}>
-        <Pressable
-          accessibilityRole="button"
-          accessibilityLabel={accessibilityLabel ?? (recording ? 'Stop BugSession recording' : 'Start BugSession recording')}
-          accessibilityHint={draggable ? 'Drag to move the BugSession button' : undefined}
-          accessibilityState={{ busy, selected: recording }}
-          disabled={busy}
-          onPress={() => { void toggle(); }}
-          style={[styles.trigger, recording && styles.triggerRecording, style]}
-        >
-          {children ?? <><Text style={styles.triggerMark}>b</Text><View style={[styles.triggerDot, recording && styles.triggerDotRecording]} /></>}
-        </Pressable>
-      </Animated.View>
-    </View>;
-  },
 };
 
 const styles = StyleSheet.create({
-  triggerLayer: { ...StyleSheet.absoluteFill, zIndex: 9999 },
-  triggerPosition: { position: 'absolute' },
-  trigger: { width: 58, height: 58, borderRadius: 29, backgroundColor: '#173B34', alignItems: 'center', justifyContent: 'center', elevation: 8, shadowColor: '#000', shadowOpacity: 0.24, shadowRadius: 8, shadowOffset: { width: 0, height: 4 } },
-  triggerRecording: { backgroundColor: '#B9382F' },
-  triggerMark: { color: '#F4F4EC', fontSize: 31, fontWeight: '800', lineHeight: 38 },
-  triggerDot: { position: 'absolute', right: 9, bottom: 9, width: 10, height: 10, borderRadius: 5, backgroundColor: '#D8F36A', borderWidth: 1, borderColor: '#173B34' },
-  triggerDotRecording: { backgroundColor: '#FFF', borderColor: '#B9382F' },
+  boundary: { flex: 1, justifyContent: 'center', padding: 24, gap: 12, backgroundColor: '#FFFFFF' },
+  boundaryTitle: { fontSize: 22, fontWeight: '700', color: '#111111' },
+  boundaryMessage: { fontSize: 15, color: '#555555' },
+  boundaryRetry: { alignSelf: 'flex-start', paddingVertical: 10, paddingHorizontal: 16, borderRadius: 8, backgroundColor: '#173B34' },
+  boundaryRetryText: { color: '#F4F4EC', fontWeight: '700' },
 });

package/src/tap-label.ts

@@ -0,0 +1,69 @@
+/** Pure helpers for automatic tap capture; no React Native imports so they can be unit tested. */
+type Fiber = { memoizedProps?: Record<string, unknown> | null; return?: Fiber | null; child?: Fiber | null; sibling?: Fiber | null };
+
+const LABEL_DEPTH = 12;
+const PRESSABLE_DEPTH = 4;
+const DESCENDANT_BUDGET = 40;
+
+function text(value: unknown): string | undefined {
+  if (typeof value === 'string' || typeof value === 'number') return String(value).trim() || undefined;
+  if (Array.isArray(value)) {
+    const joined = value.map(text).filter(Boolean).join(' ');
+    return joined || undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Best-effort name for the touched element: walks up from the touched host component
+ * reading accessibility labels, test IDs, titles and visible text. Never reads input
+ * values. React internals differ between renderers, so every failure yields undefined.
+ */
+export function tapLabel(event: unknown): string | undefined {
+  try {
+    const native = event as { _targetInst?: Fiber; target?: { __internalInstanceHandle?: Fiber } } | null;
+    const target = native?._targetInst ?? native?.target?.__internalInstanceHandle;
+    let fiber: Fiber | null | undefined = target;
+    for (let depth = 0; fiber && depth < LABEL_DEPTH; depth++, fiber = fiber.return) {
+      const label = ownLabel(fiber.memoizedProps);
+      if (label) return label.slice(0, 80);
+      // A tap on a button's padding targets the button itself; its text is inside it.
+      if (depth < PRESSABLE_DEPTH && pressable(fiber.memoizedProps)) {
+        const inner = descendantText(fiber.child);
+        if (inner) return inner.slice(0, 80);
+      }
+    }
+  } catch { /* renderer internals unavailable */ }
+  return undefined;
+}
+
+function ownLabel(props: Record<string, unknown> | null | undefined): string | undefined {
+  if (!props || typeof props !== 'object') return undefined;
+  return text(props.accessibilityLabel) ?? text(props['aria-label']) ?? text(props.title)
+    ?? (typeof props.placeholder === 'string' ? props.placeholder : undefined)
+    ?? (props.editable === undefined && props.value === undefined ? text(props.children) : undefined)
+    ?? text(props.testID);
+}
+
+function pressable(props: Record<string, unknown> | null | undefined) {
+  if (!props || typeof props !== 'object') return false;
+  const role = props.accessibilityRole ?? props.role;
+  return typeof props.onPress === 'function' || typeof props.onClick === 'function' || role === 'button' || role === 'link'
+    || typeof props.onResponderRelease === 'function';
+}
+
+/** First readable text inside a pressable, breadth-first and bounded; never input values. */
+function descendantText(first: Fiber | null | undefined): string | undefined {
+  const queue: Fiber[] = [];
+  for (let f = first; f; f = f.sibling) queue.push(f);
+  for (let visited = 0; queue.length && visited < DESCENDANT_BUDGET; visited++) {
+    const fiber = queue.shift()!;
+    const props = fiber.memoizedProps;
+    if (props && typeof props === 'object' && props.editable === undefined && props.value === undefined) {
+      const label = text(props.accessibilityLabel) ?? text(props.children);
+      if (label) return label;
+    }
+    for (let f = fiber.child; f; f = f.sibling) queue.push(f);
+  }
+  return undefined;
+}

package/src/touches.tsx

@@ -0,0 +1,37 @@
+import React, { useRef } from 'react';
+import { StyleSheet, View, type ViewProps } from 'react-native';
+import { tapLabel } from './tap-label';
+
+export type TapSink = (tap: { label?: string; x: number; y: number }) => void;
+
+const TAP_MAX_MOVE = 10;
+const TAP_MAX_MS = 800;
+/**
+ * Wraps the app once and records every tap (position, screen and the element's label
+ * when one can be read), so testers' steps appear in the timeline without per-button code.
+ * It only observes touches; it never becomes the responder or blocks gestures.
+ */
+export function createCapture(sink: () => TapSink | null) {
+  return function Capture({ children, style, ...props }: ViewProps & { children?: React.ReactNode }) {
+    const start = useRef<{ x: number; y: number; at: number } | null>(null);
+    return <View {...props} style={[styles.fill, style]}
+      onTouchStartCapture={e => {
+        props.onTouchStartCapture?.(e);
+        start.current = e.nativeEvent.touches.length > 1 ? null : { x: e.nativeEvent.pageX, y: e.nativeEvent.pageY, at: Date.now() };
+      }}
+      onTouchEndCapture={e => {
+        props.onTouchEndCapture?.(e);
+        const began = start.current;
+        start.current = null;
+        const add = sink();
+        if (!began || !add) return;
+        const { pageX, pageY } = e.nativeEvent;
+        if (Math.hypot(pageX - began.x, pageY - began.y) > TAP_MAX_MOVE || Date.now() - began.at > TAP_MAX_MS) return;
+        add({ label: tapLabel(e), x: Math.round(pageX), y: Math.round(pageY) });
+      }}>
+      {children}
+    </View>;
+  };
+}
+
+const styles = StyleSheet.create({ fill: { flex: 1 } });