@bugsession/react-native 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/trigger.js

@@ -0,0 +1,297 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTrigger = createTrigger;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+// Native modals (e.g. Expo Router `presentation: 'modal'`) are presented above the app's
+// root view, which would hide the trigger. react-native-screens' FullWindowOverlay renders
+// in a window above them and passes touches through empty areas. Optional dependency.
+let FullWindowOverlay = null;
+if (react_native_1.Platform.OS === 'ios') {
+    try {
+        FullWindowOverlay = require('react-native-screens').FullWindowOverlay ?? null;
+    }
+    catch {
+        FullWindowOverlay = null;
+    }
+}
+const tab = { width: 34, height: 76 };
+const panelWidth = 212;
+const autoHideMs = 4000;
+const barShape = [0.55, 0.8, 1, 0.8, 0.55];
+const compactBarShape = [0.8, 1, 0.8];
+const ink = '#FF3B30';
+const strokeWidth = 5;
+// Survives remounts (e.g. the trigger rendered by an error boundary) while the app is open.
+let tabPlacement = null;
+function elapsed(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000));
+    return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
+}
+function createTrigger(controller) {
+    function usePhase() {
+        return react_1.default.useSyncExternalStore(controller.subscribe, controller.getPhase, controller.getPhase);
+    }
+    function useInsets() {
+        const [insets, setInsets] = react_1.default.useState(null);
+        react_1.default.useEffect(() => { void controller.safeAreaInsets().then(setInsets).catch(() => setInsets(null)); }, []);
+        // Without native insets (older native builds, Android), assume a notch and home indicator on iOS.
+        return insets ?? { top: react_native_1.Platform.OS === 'ios' ? 54 : 24, bottom: react_native_1.Platform.OS === 'ios' ? 34 : 16 };
+    }
+    function useElapsed(phase, maxDurationSeconds) {
+        const [now, setNow] = react_1.default.useState(Date.now());
+        react_1.default.useEffect(() => {
+            if (phase.kind !== 'recording')
+                return;
+            const timer = setInterval(() => setNow(Date.now()), 500);
+            return () => clearInterval(timer);
+        }, [phase]);
+        const ms = phase.kind === 'recording' ? Math.max(0, now - phase.startedAt) : 0;
+        return { ms, nearLimit: ms > (maxDurationSeconds - 30) * 1000 };
+    }
+    function Waveform({ compact }) {
+        const shape = compact ? compactBarShape : barShape;
+        const bars = react_1.default.useRef(shape.map(() => new react_native_1.Animated.Value(0.25))).current;
+        const [live, setLive] = react_1.default.useState(false);
+        react_1.default.useEffect(() => {
+            const unsubscribe = controller.onAudioLevel(level => {
+                setLive(true);
+                react_native_1.Animated.parallel(bars.map((bar, i) => react_native_1.Animated.timing(bar, {
+                    toValue: Math.max(0.18, Math.min(1, level * shape[i] * (0.85 + Math.random() * 0.3))),
+                    duration: 90, easing: react_native_1.Easing.out(react_native_1.Easing.quad), useNativeDriver: true,
+                }))).start();
+            });
+            return () => unsubscribe?.();
+        }, [bars, shape]);
+        return (0, jsx_runtime_1.jsx)(react_native_1.View, { style: [styles.wave, compact && styles.waveCompact], accessibilityElementsHidden: true, importantForAccessibility: "no-hide-descendants", children: bars.map((bar, i) => (0, jsx_runtime_1.jsx)(react_native_1.Animated.View, { style: [styles.waveBar, compact && styles.waveBarCompact, !live && styles.waveBarIdle, { transform: [{ scaleY: bar }] }] }, i)) });
+    }
+    function RecordingDot({ size = 9 }) {
+        const pulse = react_1.default.useRef(new react_native_1.Animated.Value(1)).current;
+        react_1.default.useEffect(() => {
+            const loop = react_native_1.Animated.loop(react_native_1.Animated.sequence([
+                react_native_1.Animated.timing(pulse, { toValue: 0.35, duration: 700, useNativeDriver: true }),
+                react_native_1.Animated.timing(pulse, { toValue: 1, duration: 700, useNativeDriver: true }),
+            ]));
+            loop.start();
+            return () => loop.stop();
+        }, [pulse]);
+        return (0, jsx_runtime_1.jsx)(react_native_1.Animated.View, { style: { width: size, height: size, borderRadius: size / 2, backgroundColor: ink, opacity: pulse } });
+    }
+    /** One rotated, rounded rectangle per segment: smooth strokes without an SVG dependency. */
+    function Stroke({ points }) {
+        if (points.length === 1) {
+            const p = points[0];
+            return (0, jsx_runtime_1.jsx)(react_native_1.View, { style: [styles.segment, { left: p.x - strokeWidth / 2, top: p.y - strokeWidth / 2, width: strokeWidth }] });
+        }
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: points.slice(1).map((b, i) => {
+                const a = points[i];
+                const length = Math.hypot(b.x - a.x, b.y - a.y) + strokeWidth;
+                return (0, jsx_runtime_1.jsx)(react_native_1.View, { style: [styles.segment, {
+                            left: (a.x + b.x) / 2 - length / 2, top: (a.y + b.y) / 2 - strokeWidth / 2, width: length,
+                            transform: [{ rotate: `${Math.atan2(b.y - a.y, b.x - a.x)}rad` }],
+                        }] }, i);
+            }) });
+    }
+    /** Full-screen pen layer, active only while the tester is drawing. Strokes are part of the screen recording. */
+    function DrawingCanvas({ strokes, setStrokes }) {
+        const { width, height } = (0, react_native_1.useWindowDimensions)();
+        const current = react_1.default.useRef(null);
+        const responder = react_1.default.useMemo(() => react_native_1.PanResponder.create({
+            onStartShouldSetPanResponder: () => true,
+            onMoveShouldSetPanResponder: () => true,
+            onPanResponderGrant: event => {
+                current.current = [{ x: event.nativeEvent.pageX, y: event.nativeEvent.pageY }];
+                setStrokes(all => [...all, current.current]);
+            },
+            onPanResponderMove: event => {
+                const stroke = current.current;
+                if (!stroke)
+                    return;
+                const point = { x: event.nativeEvent.pageX, y: event.nativeEvent.pageY };
+                const last = stroke[stroke.length - 1];
+                if (Math.hypot(point.x - last.x, point.y - last.y) < 3 || stroke.length >= 400)
+                    return;
+                const next = [...stroke, point];
+                current.current = next;
+                setStrokes(all => [...all.slice(0, -1), next]);
+            },
+            onPanResponderRelease: () => {
+                const stroke = current.current;
+                current.current = null;
+                if (!stroke)
+                    return;
+                const xs = stroke.map(p => p.x), ys = stroke.map(p => p.y);
+                const x = Math.min(...xs), y = Math.min(...ys);
+                controller.annotate({
+                    x: Math.round(x), y: Math.round(y),
+                    width: Math.round(Math.max(...xs) - x), height: Math.round(Math.max(...ys) - y),
+                    screenWidth: Math.round(width), screenHeight: Math.round(height), points: stroke.length,
+                });
+            },
+        }), [width, height, setStrokes]);
+        return (0, jsx_runtime_1.jsx)(react_native_1.View, { ...responder.panHandlers, style: styles.canvas, accessibilityLabel: "Drawing area. Draw to highlight a problem.", children: strokes.map((points, i) => (0, jsx_runtime_1.jsx)(Stroke, { points: points }, i)) });
+    }
+    function PanelButton({ label, onPress, disabled, tone, accessibilityLabel }) {
+        return (0, jsx_runtime_1.jsx)(react_native_1.Pressable, { accessibilityRole: "button", accessibilityLabel: accessibilityLabel ?? label, accessibilityState: { disabled: !!disabled }, disabled: disabled, onPress: onPress, hitSlop: 4, style: [styles.panelButton, tone === 'primary' && styles.panelButtonPrimary, tone === 'danger' && styles.panelButtonDanger, disabled && styles.panelButtonDisabled], children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: [styles.panelButtonText, tone === 'primary' && styles.panelButtonTextPrimary], children: label }) });
+    }
+    /** After stopping, a short toast at the top; the recording has already ended, so it is not captured. */
+    function StatusToast({ phase }) {
+        const insets = useInsets();
+        const appear = react_1.default.useRef(new react_native_1.Animated.Value(0)).current;
+        const visible = phase.kind === 'uploading' || phase.kind === 'sent' || phase.kind === 'failed';
+        const [shown, setShown] = react_1.default.useState(phase);
+        react_1.default.useEffect(() => { if (visible)
+            setShown(phase); }, [phase, visible]);
+        react_1.default.useEffect(() => {
+            react_native_1.Animated.spring(appear, { toValue: visible ? 1 : 0, useNativeDriver: true, bounciness: 5, speed: 14 }).start();
+        }, [visible, appear]);
+        let content = null;
+        if (shown.kind === 'uploading')
+            content = (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(react_native_1.ActivityIndicator, { size: "small", color: "#FFFFFF" }), (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.toastText, children: "Sending report\u2026" })] });
+        else if (shown.kind === 'sent')
+            content = (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(react_native_1.View, { style: [styles.badge, styles.badgeSuccess], children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.badgeText, children: "\u2713" }) }), (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.toastText, children: "Report sent" })] });
+        else if (shown.kind === 'failed')
+            content = (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(react_native_1.View, { style: [styles.badge, styles.badgeError], children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.badgeText, children: "!" }) }), (0, jsx_runtime_1.jsxs)(react_native_1.Text, { style: styles.toastText, numberOfLines: 2, children: ["Not sent: ", shown.message] })] });
+        return (0, jsx_runtime_1.jsx)(react_native_1.Animated.View, { pointerEvents: "none", accessibilityLiveRegion: "polite", style: [styles.toastLayer, {
+                    top: insets.top + 8, opacity: appear,
+                    transform: [{ translateY: appear.interpolate({ inputRange: [0, 1], outputRange: [-16, 0] }) }],
+                }], children: content && (0, jsx_runtime_1.jsx)(react_native_1.View, { style: styles.toast, children: content }) });
+    }
+    return function Trigger({ position = 'bottom-right', offset = 96, draggable = true, style, accessibilityLabel, children, onError, maxDurationSeconds = 150 }) {
+        const phase = usePhase();
+        const insets = useInsets();
+        const { width, height } = (0, react_native_1.useWindowDimensions)();
+        const { ms, nearLimit } = useElapsed(phase, maxDurationSeconds);
+        const [expanded, setExpanded] = react_1.default.useState(false);
+        const [drawing, setDrawing] = react_1.default.useState(false);
+        const [strokes, setStrokes] = react_1.default.useState([]);
+        const minTop = insets.top + 8;
+        const maxTop = Math.max(minTop, height - insets.bottom - tab.height - 8);
+        const clampTop = react_1.default.useCallback((top) => Math.max(minTop, Math.min(top, maxTop)), [minTop, maxTop]);
+        const [placement, setPlacement] = react_1.default.useState(() => tabPlacement ?? {
+            side: position.includes('left') ? 'left' : 'right',
+            top: position.includes('top') ? minTop + offset : height - insets.bottom - tab.height - offset,
+        });
+        const top = clampTop(placement.top);
+        const drag = react_1.default.useRef(new react_native_1.Animated.ValueXY()).current;
+        const dragStart = react_1.default.useRef({ side: placement.side, top });
+        dragStart.current = { side: placement.side, top };
+        const recording = phase.kind === 'recording';
+        const starting = phase.kind === 'starting';
+        // Auto-stop at the limit, and reset the controls when a recording ends.
+        react_1.default.useEffect(() => {
+            if (recording && ms >= maxDurationSeconds * 1000)
+                void controller.toggle();
+        }, [recording, ms, maxDurationSeconds]);
+        react_1.default.useEffect(() => {
+            if (!recording) {
+                setExpanded(false);
+                setDrawing(false);
+                setStrokes([]);
+            }
+        }, [recording]);
+        // The options panel hides itself so it stays out of the video as much as possible.
+        react_1.default.useEffect(() => {
+            if (!expanded || drawing)
+                return;
+            const timer = setTimeout(() => setExpanded(false), autoHideMs);
+            return () => clearTimeout(timer);
+        }, [expanded, drawing]);
+        const responder = react_1.default.useMemo(() => react_native_1.PanResponder.create({
+            onStartShouldSetPanResponder: () => false,
+            onMoveShouldSetPanResponder: (_, gesture) => draggable && Math.hypot(gesture.dx, gesture.dy) > 7,
+            onPanResponderMove: (_, gesture) => drag.setValue({ x: gesture.dx, y: clampTop(dragStart.current.top + gesture.dy) - dragStart.current.top }),
+            onPanResponderRelease: (_, gesture) => {
+                const startX = dragStart.current.side === 'right' ? width - tab.width : 0;
+                const next = { side: (startX + gesture.dx + tab.width / 2 > width / 2 ? 'right' : 'left'), top: clampTop(dragStart.current.top + gesture.dy) };
+                tabPlacement = next;
+                setPlacement(next);
+                drag.setValue({ x: 0, y: 0 });
+            },
+            onPanResponderTerminate: () => drag.setValue({ x: 0, y: 0 }),
+        }), [draggable, drag, width, clampTop]);
+        const onTab = async () => {
+            if (recording) {
+                setExpanded(open => !open || drawing);
+                return;
+            }
+            try {
+                await controller.toggle();
+            }
+            catch (error) {
+                controller.fail(error);
+                onError?.(error);
+            }
+        };
+        const stop = () => { setExpanded(false); setDrawing(false); setStrokes([]); void controller.toggle(); };
+        const side = placement.side;
+        const showTab = phase.kind === 'idle' || starting || recording;
+        const panelTop = Math.max(minTop, Math.min(top - 12, height - insets.bottom - 8 - (drawing ? 150 : 170)));
+        const panelEdge = { [side]: tab.width + 6 };
+        let tabContent;
+        if (starting)
+            tabContent = (0, jsx_runtime_1.jsx)(react_native_1.ActivityIndicator, { size: "small", color: "#FFFFFF" });
+        else if (recording)
+            tabContent = (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(RecordingDot, { size: 8 }), (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: [styles.tabTime, nearLimit && styles.warning], children: elapsed(ms) }), (0, jsx_runtime_1.jsx)(Waveform, { compact: true })] });
+        else
+            tabContent = children ?? (0, jsx_runtime_1.jsx)(react_native_1.View, { style: styles.recordRing, children: (0, jsx_runtime_1.jsx)(react_native_1.View, { style: styles.recordDot }) });
+        const layer = (0, jsx_runtime_1.jsxs)(react_native_1.View, { pointerEvents: "box-none", style: styles.layer, children: [drawing && recording && (0, jsx_runtime_1.jsx)(DrawingCanvas, { strokes: strokes, setStrokes: setStrokes }), showTab && (0, jsx_runtime_1.jsx)(react_native_1.Animated.View, { ...(draggable ? responder.panHandlers : {}), style: [styles.tabPosition, {
+                            top, [side]: 0, transform: drag.getTranslateTransform(),
+                        }], children: (0, jsx_runtime_1.jsx)(react_native_1.Pressable, { accessibilityRole: "button", accessibilityLabel: accessibilityLabel ?? (recording ? `Recording, ${Math.floor(ms / 1000)} seconds. Show recording options.` : 'Record a bug report'), accessibilityHint: recording ? undefined : 'Records the screen and your voice.', accessibilityState: { busy: starting, expanded: recording ? expanded : undefined }, disabled: starting, onPress: () => { void onTab(); }, style: [styles.tab, side === 'right' ? styles.tabRight : styles.tabLeft, recording && styles.tabRecording, style], children: tabContent }) }), recording && expanded && (0, jsx_runtime_1.jsxs)(react_native_1.View, { style: [styles.panel, panelEdge, { top: panelTop }], children: [(0, jsx_runtime_1.jsxs)(react_native_1.View, { style: styles.panelHeader, children: [(0, jsx_runtime_1.jsx)(RecordingDot, {}), (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: [styles.panelTime, nearLimit && styles.warning], children: elapsed(ms) }), (0, jsx_runtime_1.jsx)(Waveform, {})] }), drawing ? (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.panelHint, children: "Draw on the screen to highlight the problem." }), (0, jsx_runtime_1.jsxs)(react_native_1.View, { style: styles.panelRow, children: [(0, jsx_runtime_1.jsx)(PanelButton, { label: "Undo", disabled: !strokes.length, onPress: () => setStrokes(all => all.slice(0, -1)) }), (0, jsx_runtime_1.jsx)(PanelButton, { label: "Clear", disabled: !strokes.length, onPress: () => setStrokes([]) })] }), (0, jsx_runtime_1.jsx)(PanelButton, { label: "Done", tone: "primary", onPress: () => { setDrawing(false); setStrokes([]); setExpanded(false); } })] }) : (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(PanelButton, { label: "\u270E Draw on screen", onPress: () => setDrawing(true) }), (0, jsx_runtime_1.jsx)(PanelButton, { label: "\u25A0 Stop & send", tone: "danger", accessibilityLabel: "Stop recording and send the report", onPress: stop })] })] }), (0, jsx_runtime_1.jsx)(StatusToast, { phase: phase })] });
+        return FullWindowOverlay
+            ? (0, jsx_runtime_1.jsx)(FullWindowOverlay, { unstable_accessibilityContainerViewIsModal: false, children: layer })
+            : layer;
+    };
+}
+const styles = react_native_1.StyleSheet.create({
+    layer: { ...react_native_1.StyleSheet.absoluteFill, zIndex: 9999, elevation: 9999 },
+    tabPosition: { position: 'absolute' },
+    tab: {
+        width: tab.width, height: tab.height, alignItems: 'center', justifyContent: 'center', gap: 5,
+        backgroundColor: 'rgba(16,17,20,0.92)', borderWidth: react_native_1.StyleSheet.hairlineWidth, borderColor: 'rgba(255,255,255,0.16)',
+        shadowColor: '#000', shadowOpacity: 0.25, shadowRadius: 8, shadowOffset: { width: 0, height: 3 }, elevation: 10,
+    },
+    tabRight: { borderTopLeftRadius: 14, borderBottomLeftRadius: 14, borderRightWidth: 0 },
+    tabLeft: { borderTopRightRadius: 14, borderBottomRightRadius: 14, borderLeftWidth: 0 },
+    tabRecording: { borderColor: 'rgba(255,59,48,0.5)' },
+    tabTime: { color: '#FFFFFF', fontSize: 10, fontWeight: '700', fontVariant: ['tabular-nums'] },
+    recordRing: { width: 22, height: 22, borderRadius: 11, borderWidth: 2, borderColor: 'rgba(255,255,255,0.9)', alignItems: 'center', justifyContent: 'center' },
+    recordDot: { width: 11, height: 11, borderRadius: 5.5, backgroundColor: ink },
+    warning: { color: '#FFB340' },
+    panel: {
+        position: 'absolute', width: panelWidth, gap: 8, padding: 12, borderRadius: 18,
+        backgroundColor: 'rgba(16,17,20,0.96)', borderWidth: react_native_1.StyleSheet.hairlineWidth, borderColor: 'rgba(255,255,255,0.14)',
+        shadowColor: '#000', shadowOpacity: 0.3, shadowRadius: 14, shadowOffset: { width: 0, height: 6 }, elevation: 14,
+    },
+    panelHeader: { flexDirection: 'row', alignItems: 'center', gap: 8, marginBottom: 2 },
+    panelTime: { color: '#FFFFFF', fontSize: 16, fontWeight: '700', fontVariant: ['tabular-nums'], flex: 1 },
+    panelHint: { color: 'rgba(255,255,255,0.7)', fontSize: 12, lineHeight: 16 },
+    panelRow: { flexDirection: 'row', gap: 8 },
+    panelButton: { flex: 1, alignItems: 'center', paddingVertical: 10, paddingHorizontal: 12, borderRadius: 12, backgroundColor: 'rgba(255,255,255,0.12)' },
+    panelButtonPrimary: { backgroundColor: '#FFFFFF' },
+    panelButtonDanger: { backgroundColor: ink },
+    panelButtonDisabled: { opacity: 0.4 },
+    panelButtonText: { color: '#FFFFFF', fontSize: 14, fontWeight: '700' },
+    panelButtonTextPrimary: { color: '#000000' },
+    canvas: { ...react_native_1.StyleSheet.absoluteFill, borderWidth: 3, borderColor: 'rgba(255,59,48,0.55)' },
+    segment: { position: 'absolute', height: strokeWidth, borderRadius: strokeWidth / 2, backgroundColor: ink },
+    toastLayer: { position: 'absolute', left: 0, right: 0, alignItems: 'center' },
+    toast: {
+        flexDirection: 'row', alignItems: 'center', gap: 10, maxWidth: 340, paddingHorizontal: 16, paddingVertical: 10, borderRadius: 22,
+        backgroundColor: 'rgba(16,17,20,0.96)', shadowColor: '#000', shadowOpacity: 0.3, shadowRadius: 12, shadowOffset: { width: 0, height: 5 }, elevation: 14,
+    },
+    toastText: { color: '#FFFFFF', fontSize: 15, fontWeight: '600', flexShrink: 1 },
+    wave: { flexDirection: 'row', alignItems: 'center', gap: 3, height: 18 },
+    waveCompact: { gap: 2, height: 12 },
+    waveBar: { width: 3, height: 18, borderRadius: 1.5, backgroundColor: '#FF6B61' },
+    waveBarCompact: { width: 2, height: 12, borderRadius: 1 },
+    waveBarIdle: { backgroundColor: 'rgba(255,255,255,0.45)' },
+    badge: { width: 22, height: 22, borderRadius: 11, alignItems: 'center', justifyContent: 'center' },
+    badgeSuccess: { backgroundColor: '#30D158' },
+    badgeError: { backgroundColor: '#FF453A' },
+    badgeText: { color: '#000000', fontSize: 13, fontWeight: '800' },
+});

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@bugsession/react-native",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "peerDependencies": {
     "react": ">=18.3.1 <20",
-    "react-native": ">=0.76.0 <0.89"
+    "react-native": ">=0.76.0 <0.89",
+    "react-native-screens": ">=4.0.0"
   },
   "description": "Opt-in React Native runtime evidence SDK",
   "license": "UNLICENSED",
@@ -42,5 +43,10 @@
   "homepage": "https://github.com/Anis-Ghliss/bugsession/tree/main/packages/react-native#readme",
   "bugs": {
     "url": "https://github.com/Anis-Ghliss/bugsession/issues"
+  },
+  "peerDependenciesMeta": {
+    "react-native-screens": {
+      "optional": true
+    }
   }
 }

package/src/capture.ts

@@ -12,6 +12,12 @@ export type NativeCaptureAdapter = {
   stop(): Promise<NativeRecording>;
   cancel(): Promise<void>;
   upload(url: string, uri: string, headers?: Record<string, string>): Promise<void>;
+  /** Optional: live microphone level (0-1) for the recording indicator. Returns an unsubscribe function. */
+  onAudioLevel?(listener: (level: number) => void): () => void;
+  /** Optional: safe-area insets in points, used to place the recording controls above the home indicator. */
+  safeAreaInsets?(): Promise<{ top: number; bottom: number } | null>;
+  /** Optional: native app and device facts merged into each recording's metadata. */
+  appContext?(): Promise<{ application: Record<string, unknown>; device: Record<string, unknown> } | null>;
 };
 export function alignNativeRecording(recording: NativeRecording, offsetMs: number, uncertaintyMs: number) {
   const videoStartMs = recording.firstVideoNativeMs + offsetMs;

package/src/core.ts

@@ -20,17 +20,81 @@ export class SessionClock {
   private epoch: number;
   constructor(private source = () => performance.now()) { this.epoch = source(); }
   now() { return Math.max(0, this.source() - this.epoch); }
+  /** Monotonic source reading at which this clock reads zero. */
+  get origin() { return this.epoch; }
 }
 export class Collector {
   events: Evidence[] = [];
   dropped = 0;
   constructor(public clock = new SessionClock(), private limit = 5000) {}
   add(type: string, data: Record<string, unknown>) {
+    this.addAt(type, data, this.clock.now());
+  }
+  addAt(type: string, data: Record<string, unknown>, timestampMs: number) {
     if (this.events.length >= this.limit) { this.dropped++; return; }
-    this.events.push({ ...data, type, timestampMs: this.clock.now() });
+    this.events.push({ ...data, type, timestampMs });
   }
 }
-export function instrumentFetch(original: typeof fetch, collector: Collector): typeof fetch {
+
+export type TelemetrySink = { add(type: string, data: Record<string, unknown>): void; clock: { now(): number } };
+export const MAX_PRE_RECORD_MS = 300_000;
+
+/**
+ * Routes app events to the active session, or, between sessions, into a bounded
+ * in-memory buffer of the last `preRecordMs`. The buffer never leaves the device
+ * unless a recording starts. Timestamps are kept on one app-lifetime clock and
+ * converted to the session clock, so requests spanning the start stay consistent.
+ */
+export class Telemetry implements TelemetrySink {
+  readonly clock: SessionClock;
+  private buffer: Evidence[] = [];
+  private session: { collector: Collector; offsetMs: number } | null = null;
+  private preRecordMs: number;
+  constructor(preRecordMs = 60_000, private maxBuffered = 500, source = () => performance.now()) {
+    this.clock = new SessionClock(source);
+    this.preRecordMs = Math.max(0, Math.min(preRecordMs, MAX_PRE_RECORD_MS));
+  }
+  /** False when nothing would be kept, so callers can skip formatting work. */
+  get active() { return !!this.session || this.preRecordMs > 0; }
+  configure(preRecordMs: number, maxBuffered = this.maxBuffered) {
+    this.preRecordMs = Math.max(0, Math.min(preRecordMs, MAX_PRE_RECORD_MS));
+    this.maxBuffered = maxBuffered;
+    this.prune(this.clock.now());
+  }
+  add(type: string, data: Record<string, unknown>) {
+    const now = this.clock.now();
+    if (this.session) {
+      const { collector, offsetMs } = this.session;
+      collector.addAt(type, shiftRequestTime(data, offsetMs), now - offsetMs);
+      return;
+    }
+    if (this.preRecordMs <= 0) return;
+    this.buffer.push({ ...data, type, timestampMs: now });
+    this.prune(now);
+  }
+  /** Routes events to `collector` and returns the buffered events on its clock (negative times). */
+  begin(collector: Collector): Evidence[] {
+    const offsetMs = collector.clock.origin - this.clock.origin;
+    this.prune(this.clock.now());
+    const before = this.buffer.map(e => ({ ...shiftRequestTime(e, offsetMs), timestampMs: e.timestampMs - offsetMs, preRecording: true }));
+    this.buffer = [];
+    this.session = { collector, offsetMs };
+    return before;
+  }
+  end() { this.session = null; }
+  private prune(now: number) {
+    const cutoff = now - this.preRecordMs;
+    let drop = 0;
+    while (drop < this.buffer.length && this.buffer[drop].timestampMs < cutoff) drop++;
+    drop = Math.max(drop, this.buffer.length - this.maxBuffered);
+    if (drop > 0) this.buffer.splice(0, drop);
+  }
+}
+function shiftRequestTime<T extends Record<string, unknown>>(data: T, offsetMs: number): T {
+  return typeof data.requestTimestampMs === 'number' ? { ...data, requestTimestampMs: data.requestTimestampMs - offsetMs } : data;
+}
+
+export function instrumentFetch(original: typeof fetch, collector: TelemetrySink): typeof fetch {
   return (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
     const url = safeUrl(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
     const method = (init?.method ?? (typeof input === 'object' && 'method' in input ? input.method : 'GET')).toUpperCase();