@scalebun/react-native 1.0.0 → 1.0.2

package/src/debug/stream.ts

@@ -1,561 +1,561 @@
-/**
- * ScaleBun Debug — Event Stream Tap
- *
- * Subscribes to SDK internal events and streams them to the debug transport.
- * Taps into:
- *   - PersistentQueue (mirrors pipeline envelopes)
- *   - InternalLogger (SDK log messages)
- *   - Console (console.log/warn/error)
- *
- * All hooks are non-invasive and no-throw safe.
- */
-
-import { type DebugTransport } from './transport';
-import { type EventMessage, type LogLevel, PROTOCOL_VERSION } from './protocol';
-import { type Envelope } from '../pipeline/envelope/envelope';
-import { redactNetworkEvent, scanObjectForPII } from './redaction';
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-type EnvelopeCategory = 'log' | 'network' | 'navigation' | 'lifecycle' | 'crash' | 'breadcrumb' | 'custom';
-
-interface StreamConfig {
-    /** Whether to capture console.log/warn/error. Default: true */
-    captureConsole?: boolean;
-    /** Whether to capture SDK internal logs. Default: true */
-    captureSDKLogs?: boolean;
-    /** Whether to redact network events. Default: true */
-    redactNetwork?: boolean;
-}
-
-// ─── Event Stream ───────────────────────────────────────────────────────────
-
-export class DebugEventStream {
-    private transport: DebugTransport;
-    private config: Required<StreamConfig>;
-    private originalConsole: {
-        log: typeof console.log;
-        warn: typeof console.warn;
-        error: typeof console.error;
-        info: typeof console.info;
-        debug: typeof console.debug;
-    };
-    private consoleInstalled = false;
-    private teardownFns: Array<() => void> = [];
-    /** Provider for current screen name — injected at setup from screen tracker */
-    private screenProvider: (() => string | null) | null = null;
-    /**
-     * Provider for the RECORDING session ID (`ses-xxx`).
-     * Injected from bootstrap via setRecordingSessionProvider() after the
-     * SessionManager is created. Returns null when no recording is active.
-     *
-     * This is the single read point for `recordingSessionId` across all event
-     * construction paths in this file — do NOT read it anywhere else.
-     */
-    private recordingSessionProvider: (() => string | null) | null = null;
-
-    constructor(transport: DebugTransport, config: StreamConfig = {}) {
-        this.transport = transport;
-        this.config = {
-            captureConsole: true,
-            captureSDKLogs: true,
-            redactNetwork: true,
-            ...config,
-        };
-        // Store original console methods
-        this.originalConsole = {
-            log: console.log,
-            warn: console.warn,
-            error: console.error,
-            info: console.info,
-            debug: console.debug,
-        };
-    }
-
-    /** Set the screen provider for network/event enrichment */
-    setScreenProvider(provider: () => string | null): void {
-        this.screenProvider = provider;
-    }
-
-    /**
-     * Set the recording session ID provider.
-     * Must be called after SessionManager is created in bootstrap.
-     * The provider reads SessionManager.recordingSessionId — the single
-     * source of truth for whether a recording is active.
-     */
-    setRecordingSessionProvider(provider: () => string | null): void {
-        this.recordingSessionProvider = provider;
-    }
-
-    // ─── Public API ─────────────────────────────────────────────────────────
-
-    /** Install all stream taps */
-    install(): void {
-        if (this.config.captureConsole) {
-            this._installConsoleTap();
-        }
-        this._installNetworkTap();
-    }
-
-    /** Send an envelope from the SDK pipeline to the debug stream */
-    tapEnvelope(envelope: Envelope): void {
-        try {
-            const category = this._mapEnvelopeCategory(envelope);
-            const data = category === 'network' && this.config.redactNetwork
-                ? redactNetworkEvent(envelope.payload ?? {})
-                : envelope.payload;
-
-            // Scan non-network events for PII
-            let piiWarnings: Array<{ type: string; match: string; location: string }> = [];
-            if (category !== 'network' && data) {
-                piiWarnings = scanObjectForPII(data, `event.${envelope.type}`);
-            }
-
-            const recordingSessionId = this._getRecordingSessionId();
-            const eventMsg: EventMessage = {
-                type: 'event',
-                protocolVersion: PROTOCOL_VERSION,
-                deviceId: this.transport.deviceId,
-                sessionId: this.transport.sessionId,
-                timestamp: envelope.timestamp || Date.now(),
-                sequence: this.transport.nextSequence(),
-                payload: {
-                    id: envelope.id || this._generateId(),
-                    category,
-                    name: envelope.payload?.name || envelope.type,
-                    data: {
-                        ...data,
-                        ...(piiWarnings.length > 0 ? { _piiWarnings: piiWarnings } : {}),
-                        // Stamp recording session ID so the desktop can correlate
-                        // this event to the active recording without relying on
-                        // the transport sessionId (debug-xxx vs ses-xxx duality).
-                        // null when no recording is active; absent for legacy SDKs.
-                        ...(recordingSessionId !== null ? { recordingSessionId } : {}),
-                    },
-                    level: this._inferLogLevel(envelope),
-                    tags: this._inferTags(envelope),
-                },
-            };
-
-            this.transport.send(eventMsg);
-        } catch {
-            // No-throw: silently drop if event processing fails
-        }
-    }
-
-    /** Send a log event directly (for SDK internal logger integration) */
-    tapLog(level: LogLevel, message: string, args: unknown[] = []): void {
-        try {
-            const eventMsg: EventMessage = {
-                type: 'event',
-                protocolVersion: PROTOCOL_VERSION,
-                deviceId: this.transport.deviceId,
-                sessionId: this.transport.sessionId,
-                timestamp: Date.now(),
-                sequence: this.transport.nextSequence(),
-                payload: {
-                    id: this._generateId(),
-                    category: 'log',
-                    name: `sdk.${level}`,
-                    data: {
-                        message,
-                        args: args.map(a => this._safeSerialize(a)),
-                        source: 'sdk',
-                    },
-                    level,
-                },
-            };
-
-            this.transport.send(eventMsg);
-        } catch {
-            // No-throw
-        }
-    }
-
-    /** Send a custom breadcrumb event */
-    tapBreadcrumb(message: string, data?: Record<string, unknown>): void {
-        try {
-            const eventMsg: EventMessage = {
-                type: 'event',
-                protocolVersion: PROTOCOL_VERSION,
-                deviceId: this.transport.deviceId,
-                sessionId: this.transport.sessionId,
-                timestamp: Date.now(),
-                sequence: this.transport.nextSequence(),
-                payload: {
-                    id: this._generateId(),
-                    category: 'breadcrumb',
-                    name: message,
-                    data,
-                },
-            };
-
-            this.transport.send(eventMsg);
-        } catch {
-            // No-throw
-        }
-    }
-
-    /** Uninstall all taps and restore original behavior */
-    teardown(): void {
-        this._restoreConsole();
-        for (const fn of this.teardownFns) {
-            try { fn(); } catch { /* no-throw */ }
-        }
-        this.teardownFns = [];
-    }
-
-    // ─── Console Tap ───────────────────────────────────────────────────────
-
-    private _installConsoleTap(): void {
-        if (this.consoleInstalled) return;
-        this.consoleInstalled = true;
-
-        const levelMap: Array<[keyof typeof this.originalConsole, LogLevel]> = [
-            ['debug', 'debug'],
-            ['log', 'info'],
-            ['info', 'info'],
-            ['warn', 'warn'],
-            ['error', 'error'],
-        ];
-
-        for (const [method, level] of levelMap) {
-            const original = this.originalConsole[method];
-            (console as any)[method] = (...args: unknown[]) => {
-                const firstArg = args[0];
-                const isSdkLog = typeof firstArg === 'string' &&
-                    (firstArg.startsWith('[ReplaySdk]') || firstArg.startsWith('[ScaleBun'));
-
-                if (isSdkLog) {
-                    if (this.config.captureSDKLogs) {
-                        this.tapLog(level, args.map(a => this._safeSerialize(a)).join(' '));
-                    }
-                    // Do not call original — prevents Expo/RN error overlay from
-                    // triggering on SDK-internal errors when native binary is stale.
-                    return;
-                }
-
-                // Always call original for non-SDK logs
-                original.apply(console, args);
-
-                // Send console output to desktop
-                try {
-                    const eventMsg: EventMessage = {
-                        type: 'event',
-                        protocolVersion: PROTOCOL_VERSION,
-                        deviceId: this.transport.deviceId,
-                        sessionId: this.transport.sessionId,
-                        timestamp: Date.now(),
-                        sequence: this.transport.nextSequence(),
-                        payload: {
-                            id: this._generateId(),
-                            category: 'log',
-                            name: `console.${method}`,
-                            data: {
-                                message: args.map(a => this._safeSerialize(a)).join(' '),
-                                args: args.map(a => this._safeSerialize(a)),
-                                source: 'console',
-                            },
-                            level,
-                        },
-                    };
-
-                    this.transport.send(eventMsg);
-                } catch {
-                    // No-throw — never break console
-                }
-            };
-        }
-    }
-
-    // ─── Network Interception ─────────────────────────────────────────
-    //
-    // In React Native, `fetch` is backed by native code. Replacing
-    // `globalThis.fetch` with a JS wrapper BREAKS the native bridge and
-    // causes "Network request failed" for all requests.
-    //
-    // Instead, we intercept XMLHttpRequest which is the underlying
-    // mechanism for ALL networking in RN (fetch included). This way
-    // we capture every network request without breaking anything.
-    //
-
-    private _installNetworkTap(): void {
-        if (typeof XMLHttpRequest === 'undefined') return;
-
-        const self = this;
-        const OrigXHR = XMLHttpRequest;
-        const origOpen = OrigXHR.prototype.open;
-        const origSend = OrigXHR.prototype.send;
-        const origSetRequestHeader = OrigXHR.prototype.setRequestHeader;
-
-        // Patch open() to capture method & URL
-        OrigXHR.prototype.open = function (this: XMLHttpRequest, method: string, url: string | URL, ...rest: any[]) {
-            const urlStr = typeof url === 'string' ? url : url.toString();
-
-            (this as any).__scalebun_method = method.toUpperCase();
-            (this as any).__scalebun_url = urlStr;
-            (this as any).__scalebun_reqHeaders = {};
-
-            // Skip internal/debugger URLs
-            if (urlStr.includes(':9333') || urlStr.includes(':8081') ||
-                urlStr.includes('debugger') || urlStr.includes('symbolicate') ||
-                urlStr.includes('hot') || urlStr.includes('/logs')) {
-                (this as any).__scalebun_skip = true;
-            }
-
-            return origOpen.apply(this, [method, url, ...rest] as any);
-        };
-
-        // Patch setRequestHeader() to capture request headers
-        OrigXHR.prototype.setRequestHeader = function (this: XMLHttpRequest, name: string, value: string) {
-            try {
-                if ((this as any).__scalebun_reqHeaders && !(this as any).__scalebun_skip) {
-                    (this as any).__scalebun_reqHeaders[name] = value;
-                }
-            } catch { /* no-throw */ }
-            return origSetRequestHeader.apply(this, [name, value]);
-        };
-
-        // Patch send() to capture request body and listen for response
-        OrigXHR.prototype.send = function (this: XMLHttpRequest, body?: any) {
-            // Skip internal URLs
-            if ((this as any).__scalebun_skip) {
-                return origSend.apply(this, [body] as any);
-            }
-
-            const startTime = Date.now();
-            const url: string = (this as any).__scalebun_url || '';
-            const method: string = (this as any).__scalebun_method || 'GET';
-            const reqHeaders: Record<string, string> = { ...((this as any).__scalebun_reqHeaders || {}) };
-
-            // Capture request body
-            let requestBody: string | undefined;
-            try {
-                if (body && typeof body === 'string') {
-                    requestBody = body.substring(0, 4096);
-                } else if (body) {
-                    requestBody = '[Binary/FormData]';
-                }
-            } catch { /* no-throw */ }
-
-            // Listen for completion
-            this.addEventListener('loadend', function () {
-                try {
-                    const duration = Date.now() - startTime;
-                    const status = this.status;  // 200, 404, 500, etc.
-                    const statusText = this.statusText || '';
-
-                    // Parse response headers
-                    const resHeaders: Record<string, string> = {};
-                    try {
-                        const rawHeaders = this.getAllResponseHeaders();
-                        if (rawHeaders) {
-                            rawHeaders.split('\r\n').forEach(line => {
-                                if (!line) return;
-                                const sep = line.indexOf(': ');
-                                if (sep > 0) {
-                                    resHeaders[line.substring(0, sep).toLowerCase()] = line.substring(sep + 2);
-                                }
-                            });
-                        }
-                    } catch { /* no-throw */ }
-
-                    // Capture response body
-                    let responseBody: string | undefined;
-                    let responseSize = 0;
-                    try {
-                        if (this.responseType === '' || this.responseType === 'text') {
-                            const text = this.responseText;
-                            if (text) {
-                                responseSize = text.length;
-                                responseBody = text.substring(0, 4096);
-                            }
-                        } else if (this.responseType === 'json' && this.response) {
-                            const json = JSON.stringify(this.response);
-                            responseSize = json.length;
-                            responseBody = json.substring(0, 4096);
-                        }
-                    } catch { /* no-throw */ }
-
-                    // Fallback size from content-length header
-                    if (!responseSize) {
-                        const cl = resHeaders['content-length'];
-                        if (cl) responseSize = parseInt(cl, 10) || 0;
-                    }
-
-                    self._sendNetworkEvent({
-                        url, method, status, statusText, duration,
-                        requestHeaders: reqHeaders, responseHeaders: resHeaders,
-                        requestBody, responseBody, responseSize,
-                    });
-                } catch { /* no-throw — never break XHR */ }
-            });
-
-            // Listen for errors (network-level failures)
-            this.addEventListener('error', function () {
-                try {
-                    const duration = Date.now() - startTime;
-                    self._sendNetworkEvent({
-                        url, method, status: 0, statusText: '', duration,
-                        requestHeaders: reqHeaders, responseHeaders: {},
-                        requestBody, responseSize: 0,
-                        error: 'Network error',
-                    });
-                } catch { /* no-throw */ }
-            });
-
-            // Listen for timeouts
-            this.addEventListener('timeout', function () {
-                try {
-                    const duration = Date.now() - startTime;
-                    self._sendNetworkEvent({
-                        url, method, status: 0, statusText: '', duration,
-                        requestHeaders: reqHeaders, responseHeaders: {},
-                        requestBody, responseSize: 0,
-                        error: 'Request timed out',
-                    });
-                } catch { /* no-throw */ }
-            });
-
-            return origSend.apply(this, [body] as any);
-        };
-
-        this.teardownFns.push(() => {
-            OrigXHR.prototype.open = origOpen;
-            OrigXHR.prototype.send = origSend;
-            OrigXHR.prototype.setRequestHeader = origSetRequestHeader;
-        });
-    }
-
-
-
-    // ─── Network Event Helper ───────────────────────────────────────────
-
-    private _sendNetworkEvent(params: {
-        url: string; method: string; status: number; statusText: string;
-        duration: number; requestHeaders: Record<string, string>;
-        responseHeaders: Record<string, string>;
-        requestBody?: string; responseBody?: string;
-        responseSize: number; error?: string;
-    }): void {
-        try {
-            // Skip internal WS connections (our own debug transport)
-            if (params.url.includes(':9333') || params.url.includes('debugger')) return;
-
-            // Capture current screen at event emission time
-            const currentScreen = this.screenProvider?.() ?? undefined;
-
-            // Stamp the recording session ID so the desktop can directly
-            // correlate this network event to the active recording session.
-            // Null when no recording is active; the desktop's fallback logic
-            // handles legacy SDKs that omit this field.
-            const recordingSessionId = this._getRecordingSessionId();
-
-            const eventMsg: EventMessage = {
-                type: 'event',
-                protocolVersion: PROTOCOL_VERSION,
-                deviceId: this.transport.deviceId,
-                sessionId: this.transport.sessionId,
-                timestamp: Date.now(),
-                sequence: this.transport.nextSequence(),
-                payload: {
-                    id: this._generateId(),
-                    category: 'network',
-                    name: '$network_request',
-                    data: {
-                        url: params.url,
-                        method: params.method,
-                        status: params.status,
-                        statusText: params.statusText,
-                        duration: params.duration,
-                        requestHeaders: params.requestHeaders,
-                        responseHeaders: params.responseHeaders,
-                        requestBody: params.requestBody,
-                        responseBody: params.responseBody,
-                        responseSize: params.responseSize,
-                        ...(params.error ? { error: params.error } : {}),
-                        // SDK-provided screen context for correlation
-                        ...(currentScreen ? { screen: currentScreen } : {}),
-                        // Recording session ID — canonical correlation field
-                        ...(recordingSessionId !== null ? { recordingSessionId } : {}),
-                    },
-                    level: params.status >= 400 ? 'error' : params.status >= 300 ? 'warn' : 'info',
-                    tags: ['network', params.method.toLowerCase()],
-                },
-            };
-            this.transport.send(eventMsg);
-        } catch {
-            // No-throw
-        }
-    }
-
-    private _restoreConsole(): void {
-        if (!this.consoleInstalled) return;
-        console.log = this.originalConsole.log;
-        console.warn = this.originalConsole.warn;
-        console.error = this.originalConsole.error;
-        console.info = this.originalConsole.info;
-        console.debug = this.originalConsole.debug;
-        this.consoleInstalled = false;
-    }
-
-    // ─── Helpers ──────────────────────────────────────────────────────────
-
-    private _mapEnvelopeCategory(envelope: Envelope): EnvelopeCategory {
-        const name = envelope.payload?.name || '';
-        if (envelope.type === 'crash' || name === '$crash') return 'crash';
-        if (name === '$network_request') return 'network';
-        if (name === '$navigation' || name === '$screen_view') return 'navigation';
-        if (name === '$app_state_change' || name === '$session_start') return 'lifecycle';
-        if (envelope.type === 'log') return 'log';
-        return 'custom';
-    }
-
-    private _inferLogLevel(envelope: Envelope): LogLevel | undefined {
-        const name = envelope.payload?.name || '';
-        if (name === '$crash') return 'error';
-        if (envelope.type === 'crash') return 'error';
-        return undefined;
-    }
-
-    private _inferTags(envelope: Envelope): string[] {
-        const tags: string[] = [];
-        const name = envelope.payload?.name || '';
-        if (name.startsWith('$')) tags.push('system');
-        if (envelope.type) tags.push(envelope.type);
-        return tags;
-    }
-
-    private _generateId(): string {
-        return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
-    }
-
-    /**
-     * Read the current recording session ID from the injected provider.
-     * Returns null when: no provider set, or no recording active.
-     * This is the ONLY place in this file that reads recordingSessionId.
-     */
-    private _getRecordingSessionId(): string | null {
-        try {
-            return this.recordingSessionProvider?.() ?? null;
-        } catch {
-            return null;
-        }
-    }
-
-    private _safeSerialize(value: unknown): unknown {
-        try {
-            if (value === null || value === undefined) return value;
-            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-                return value;
-            }
-            if (value instanceof Error) {
-                return { message: value.message, stack: value.stack, name: value.name };
-            }
-            // Try JSON round-trip for safe serialization
-            return JSON.parse(JSON.stringify(value));
-        } catch {
-            return String(value);
-        }
-    }
-}
+/**
+ * ScaleBun Debug — Event Stream Tap
+ *
+ * Subscribes to SDK internal events and streams them to the debug transport.
+ * Taps into:
+ *   - PersistentQueue (mirrors pipeline envelopes)
+ *   - InternalLogger (SDK log messages)
+ *   - Console (console.log/warn/error)
+ *
+ * All hooks are non-invasive and no-throw safe.
+ */
+
+import { type DebugTransport } from './transport';
+import { type EventMessage, type LogLevel, PROTOCOL_VERSION } from './protocol';
+import { type Envelope } from '../pipeline/envelope/envelope';
+import { redactNetworkEvent, scanObjectForPII } from './redaction';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+type EnvelopeCategory = 'log' | 'network' | 'navigation' | 'lifecycle' | 'crash' | 'breadcrumb' | 'custom';
+
+interface StreamConfig {
+    /** Whether to capture console.log/warn/error. Default: true */
+    captureConsole?: boolean;
+    /** Whether to capture SDK internal logs. Default: true */
+    captureSDKLogs?: boolean;
+    /** Whether to redact network events. Default: true */
+    redactNetwork?: boolean;
+}
+
+// ─── Event Stream ───────────────────────────────────────────────────────────
+
+export class DebugEventStream {
+    private transport: DebugTransport;
+    private config: Required<StreamConfig>;
+    private originalConsole: {
+        log: typeof console.log;
+        warn: typeof console.warn;
+        error: typeof console.error;
+        info: typeof console.info;
+        debug: typeof console.debug;
+    };
+    private consoleInstalled = false;
+    private teardownFns: Array<() => void> = [];
+    /** Provider for current screen name — injected at setup from screen tracker */
+    private screenProvider: (() => string | null) | null = null;
+    /**
+     * Provider for the RECORDING session ID (`ses-xxx`).
+     * Injected from bootstrap via setRecordingSessionProvider() after the
+     * SessionManager is created. Returns null when no recording is active.
+     *
+     * This is the single read point for `recordingSessionId` across all event
+     * construction paths in this file — do NOT read it anywhere else.
+     */
+    private recordingSessionProvider: (() => string | null) | null = null;
+
+    constructor(transport: DebugTransport, config: StreamConfig = {}) {
+        this.transport = transport;
+        this.config = {
+            captureConsole: true,
+            captureSDKLogs: true,
+            redactNetwork: true,
+            ...config,
+        };
+        // Store original console methods
+        this.originalConsole = {
+            log: console.log,
+            warn: console.warn,
+            error: console.error,
+            info: console.info,
+            debug: console.debug,
+        };
+    }
+
+    /** Set the screen provider for network/event enrichment */
+    setScreenProvider(provider: () => string | null): void {
+        this.screenProvider = provider;
+    }
+
+    /**
+     * Set the recording session ID provider.
+     * Must be called after SessionManager is created in bootstrap.
+     * The provider reads SessionManager.recordingSessionId — the single
+     * source of truth for whether a recording is active.
+     */
+    setRecordingSessionProvider(provider: () => string | null): void {
+        this.recordingSessionProvider = provider;
+    }
+
+    // ─── Public API ─────────────────────────────────────────────────────────
+
+    /** Install all stream taps */
+    install(): void {
+        if (this.config.captureConsole) {
+            this._installConsoleTap();
+        }
+        this._installNetworkTap();
+    }
+
+    /** Send an envelope from the SDK pipeline to the debug stream */
+    tapEnvelope(envelope: Envelope): void {
+        try {
+            const category = this._mapEnvelopeCategory(envelope);
+            const data = category === 'network' && this.config.redactNetwork
+                ? redactNetworkEvent(envelope.payload ?? {})
+                : envelope.payload;
+
+            // Scan non-network events for PII
+            let piiWarnings: Array<{ type: string; match: string; location: string }> = [];
+            if (category !== 'network' && data) {
+                piiWarnings = scanObjectForPII(data, `event.${envelope.type}`);
+            }
+
+            const recordingSessionId = this._getRecordingSessionId();
+            const eventMsg: EventMessage = {
+                type: 'event',
+                protocolVersion: PROTOCOL_VERSION,
+                deviceId: this.transport.deviceId,
+                sessionId: this.transport.sessionId,
+                timestamp: envelope.timestamp || Date.now(),
+                sequence: this.transport.nextSequence(),
+                payload: {
+                    id: envelope.id || this._generateId(),
+                    category,
+                    name: envelope.payload?.name || envelope.type,
+                    data: {
+                        ...data,
+                        ...(piiWarnings.length > 0 ? { _piiWarnings: piiWarnings } : {}),
+                        // Stamp recording session ID so the desktop can correlate
+                        // this event to the active recording without relying on
+                        // the transport sessionId (debug-xxx vs ses-xxx duality).
+                        // null when no recording is active; absent for legacy SDKs.
+                        ...(recordingSessionId !== null ? { recordingSessionId } : {}),
+                    },
+                    level: this._inferLogLevel(envelope),
+                    tags: this._inferTags(envelope),
+                },
+            };
+
+            this.transport.send(eventMsg);
+        } catch {
+            // No-throw: silently drop if event processing fails
+        }
+    }
+
+    /** Send a log event directly (for SDK internal logger integration) */
+    tapLog(level: LogLevel, message: string, args: unknown[] = []): void {
+        try {
+            const eventMsg: EventMessage = {
+                type: 'event',
+                protocolVersion: PROTOCOL_VERSION,
+                deviceId: this.transport.deviceId,
+                sessionId: this.transport.sessionId,
+                timestamp: Date.now(),
+                sequence: this.transport.nextSequence(),
+                payload: {
+                    id: this._generateId(),
+                    category: 'log',
+                    name: `sdk.${level}`,
+                    data: {
+                        message,
+                        args: args.map(a => this._safeSerialize(a)),
+                        source: 'sdk',
+                    },
+                    level,
+                },
+            };
+
+            this.transport.send(eventMsg);
+        } catch {
+            // No-throw
+        }
+    }
+
+    /** Send a custom breadcrumb event */
+    tapBreadcrumb(message: string, data?: Record<string, unknown>): void {
+        try {
+            const eventMsg: EventMessage = {
+                type: 'event',
+                protocolVersion: PROTOCOL_VERSION,
+                deviceId: this.transport.deviceId,
+                sessionId: this.transport.sessionId,
+                timestamp: Date.now(),
+                sequence: this.transport.nextSequence(),
+                payload: {
+                    id: this._generateId(),
+                    category: 'breadcrumb',
+                    name: message,
+                    data,
+                },
+            };
+
+            this.transport.send(eventMsg);
+        } catch {
+            // No-throw
+        }
+    }
+
+    /** Uninstall all taps and restore original behavior */
+    teardown(): void {
+        this._restoreConsole();
+        for (const fn of this.teardownFns) {
+            try { fn(); } catch { /* no-throw */ }
+        }
+        this.teardownFns = [];
+    }
+
+    // ─── Console Tap ───────────────────────────────────────────────────────
+
+    private _installConsoleTap(): void {
+        if (this.consoleInstalled) return;
+        this.consoleInstalled = true;
+
+        const levelMap: Array<[keyof typeof this.originalConsole, LogLevel]> = [
+            ['debug', 'debug'],
+            ['log', 'info'],
+            ['info', 'info'],
+            ['warn', 'warn'],
+            ['error', 'error'],
+        ];
+
+        for (const [method, level] of levelMap) {
+            const original = this.originalConsole[method];
+            (console as any)[method] = (...args: unknown[]) => {
+                const firstArg = args[0];
+                const isSdkLog = typeof firstArg === 'string' &&
+                    (firstArg.startsWith('[ReplaySdk]') || firstArg.startsWith('[ScaleBun'));
+
+                if (isSdkLog) {
+                    if (this.config.captureSDKLogs) {
+                        this.tapLog(level, args.map(a => this._safeSerialize(a)).join(' '));
+                    }
+                    // Do not call original — prevents Expo/RN error overlay from
+                    // triggering on SDK-internal errors when native binary is stale.
+                    return;
+                }
+
+                // Always call original for non-SDK logs
+                original.apply(console, args);
+
+                // Send console output to desktop
+                try {
+                    const eventMsg: EventMessage = {
+                        type: 'event',
+                        protocolVersion: PROTOCOL_VERSION,
+                        deviceId: this.transport.deviceId,
+                        sessionId: this.transport.sessionId,
+                        timestamp: Date.now(),
+                        sequence: this.transport.nextSequence(),
+                        payload: {
+                            id: this._generateId(),
+                            category: 'log',
+                            name: `console.${method}`,
+                            data: {
+                                message: args.map(a => this._safeSerialize(a)).join(' '),
+                                args: args.map(a => this._safeSerialize(a)),
+                                source: 'console',
+                            },
+                            level,
+                        },
+                    };
+
+                    this.transport.send(eventMsg);
+                } catch {
+                    // No-throw — never break console
+                }
+            };
+        }
+    }
+
+    // ─── Network Interception ─────────────────────────────────────────
+    //
+    // In React Native, `fetch` is backed by native code. Replacing
+    // `globalThis.fetch` with a JS wrapper BREAKS the native bridge and
+    // causes "Network request failed" for all requests.
+    //
+    // Instead, we intercept XMLHttpRequest which is the underlying
+    // mechanism for ALL networking in RN (fetch included). This way
+    // we capture every network request without breaking anything.
+    //
+
+    private _installNetworkTap(): void {
+        if (typeof XMLHttpRequest === 'undefined') return;
+
+        const self = this;
+        const OrigXHR = XMLHttpRequest;
+        const origOpen = OrigXHR.prototype.open;
+        const origSend = OrigXHR.prototype.send;
+        const origSetRequestHeader = OrigXHR.prototype.setRequestHeader;
+
+        // Patch open() to capture method & URL
+        OrigXHR.prototype.open = function (this: XMLHttpRequest, method: string, url: string | URL, ...rest: any[]) {
+            const urlStr = typeof url === 'string' ? url : url.toString();
+
+            (this as any).__scalebun_method = method.toUpperCase();
+            (this as any).__scalebun_url = urlStr;
+            (this as any).__scalebun_reqHeaders = {};
+
+            // Skip internal/debugger URLs
+            if (urlStr.includes(':9333') || urlStr.includes(':8081') ||
+                urlStr.includes('debugger') || urlStr.includes('symbolicate') ||
+                urlStr.includes('hot') || urlStr.includes('/logs')) {
+                (this as any).__scalebun_skip = true;
+            }
+
+            return origOpen.apply(this, [method, url, ...rest] as any);
+        };
+
+        // Patch setRequestHeader() to capture request headers
+        OrigXHR.prototype.setRequestHeader = function (this: XMLHttpRequest, name: string, value: string) {
+            try {
+                if ((this as any).__scalebun_reqHeaders && !(this as any).__scalebun_skip) {
+                    (this as any).__scalebun_reqHeaders[name] = value;
+                }
+            } catch { /* no-throw */ }
+            return origSetRequestHeader.apply(this, [name, value]);
+        };
+
+        // Patch send() to capture request body and listen for response
+        OrigXHR.prototype.send = function (this: XMLHttpRequest, body?: any) {
+            // Skip internal URLs
+            if ((this as any).__scalebun_skip) {
+                return origSend.apply(this, [body] as any);
+            }
+
+            const startTime = Date.now();
+            const url: string = (this as any).__scalebun_url || '';
+            const method: string = (this as any).__scalebun_method || 'GET';
+            const reqHeaders: Record<string, string> = { ...((this as any).__scalebun_reqHeaders || {}) };
+
+            // Capture request body
+            let requestBody: string | undefined;
+            try {
+                if (body && typeof body === 'string') {
+                    requestBody = body.substring(0, 4096);
+                } else if (body) {
+                    requestBody = '[Binary/FormData]';
+                }
+            } catch { /* no-throw */ }
+
+            // Listen for completion
+            this.addEventListener('loadend', function () {
+                try {
+                    const duration = Date.now() - startTime;
+                    const status = this.status;  // 200, 404, 500, etc.
+                    const statusText = this.statusText || '';
+
+                    // Parse response headers
+                    const resHeaders: Record<string, string> = {};
+                    try {
+                        const rawHeaders = this.getAllResponseHeaders();
+                        if (rawHeaders) {
+                            rawHeaders.split('\r\n').forEach(line => {
+                                if (!line) return;
+                                const sep = line.indexOf(': ');
+                                if (sep > 0) {
+                                    resHeaders[line.substring(0, sep).toLowerCase()] = line.substring(sep + 2);
+                                }
+                            });
+                        }
+                    } catch { /* no-throw */ }
+
+                    // Capture response body
+                    let responseBody: string | undefined;
+                    let responseSize = 0;
+                    try {
+                        if (this.responseType === '' || this.responseType === 'text') {
+                            const text = this.responseText;
+                            if (text) {
+                                responseSize = text.length;
+                                responseBody = text.substring(0, 4096);
+                            }
+                        } else if (this.responseType === 'json' && this.response) {
+                            const json = JSON.stringify(this.response);
+                            responseSize = json.length;
+                            responseBody = json.substring(0, 4096);
+                        }
+                    } catch { /* no-throw */ }
+
+                    // Fallback size from content-length header
+                    if (!responseSize) {
+                        const cl = resHeaders['content-length'];
+                        if (cl) responseSize = parseInt(cl, 10) || 0;
+                    }
+
+                    self._sendNetworkEvent({
+                        url, method, status, statusText, duration,
+                        requestHeaders: reqHeaders, responseHeaders: resHeaders,
+                        requestBody, responseBody, responseSize,
+                    });
+                } catch { /* no-throw — never break XHR */ }
+            });
+
+            // Listen for errors (network-level failures)
+            this.addEventListener('error', function () {
+                try {
+                    const duration = Date.now() - startTime;
+                    self._sendNetworkEvent({
+                        url, method, status: 0, statusText: '', duration,
+                        requestHeaders: reqHeaders, responseHeaders: {},
+                        requestBody, responseSize: 0,
+                        error: 'Network error',
+                    });
+                } catch { /* no-throw */ }
+            });
+
+            // Listen for timeouts
+            this.addEventListener('timeout', function () {
+                try {
+                    const duration = Date.now() - startTime;
+                    self._sendNetworkEvent({
+                        url, method, status: 0, statusText: '', duration,
+                        requestHeaders: reqHeaders, responseHeaders: {},
+                        requestBody, responseSize: 0,
+                        error: 'Request timed out',
+                    });
+                } catch { /* no-throw */ }
+            });
+
+            return origSend.apply(this, [body] as any);
+        };
+
+        this.teardownFns.push(() => {
+            OrigXHR.prototype.open = origOpen;
+            OrigXHR.prototype.send = origSend;
+            OrigXHR.prototype.setRequestHeader = origSetRequestHeader;
+        });
+    }
+
+
+
+    // ─── Network Event Helper ───────────────────────────────────────────
+
+    private _sendNetworkEvent(params: {
+        url: string; method: string; status: number; statusText: string;
+        duration: number; requestHeaders: Record<string, string>;
+        responseHeaders: Record<string, string>;
+        requestBody?: string; responseBody?: string;
+        responseSize: number; error?: string;
+    }): void {
+        try {
+            // Skip internal WS connections (our own debug transport)
+            if (params.url.includes(':9333') || params.url.includes('debugger')) return;
+
+            // Capture current screen at event emission time
+            const currentScreen = this.screenProvider?.() ?? undefined;
+
+            // Stamp the recording session ID so the desktop can directly
+            // correlate this network event to the active recording session.
+            // Null when no recording is active; the desktop's fallback logic
+            // handles legacy SDKs that omit this field.
+            const recordingSessionId = this._getRecordingSessionId();
+
+            const eventMsg: EventMessage = {
+                type: 'event',
+                protocolVersion: PROTOCOL_VERSION,
+                deviceId: this.transport.deviceId,
+                sessionId: this.transport.sessionId,
+                timestamp: Date.now(),
+                sequence: this.transport.nextSequence(),
+                payload: {
+                    id: this._generateId(),
+                    category: 'network',
+                    name: '$network_request',
+                    data: {
+                        url: params.url,
+                        method: params.method,
+                        status: params.status,
+                        statusText: params.statusText,
+                        duration: params.duration,
+                        requestHeaders: params.requestHeaders,
+                        responseHeaders: params.responseHeaders,
+                        requestBody: params.requestBody,
+                        responseBody: params.responseBody,
+                        responseSize: params.responseSize,
+                        ...(params.error ? { error: params.error } : {}),
+                        // SDK-provided screen context for correlation
+                        ...(currentScreen ? { screen: currentScreen } : {}),
+                        // Recording session ID — canonical correlation field
+                        ...(recordingSessionId !== null ? { recordingSessionId } : {}),
+                    },
+                    level: params.status >= 400 ? 'error' : params.status >= 300 ? 'warn' : 'info',
+                    tags: ['network', params.method.toLowerCase()],
+                },
+            };
+            this.transport.send(eventMsg);
+        } catch {
+            // No-throw
+        }
+    }
+
+    private _restoreConsole(): void {
+        if (!this.consoleInstalled) return;
+        console.log = this.originalConsole.log;
+        console.warn = this.originalConsole.warn;
+        console.error = this.originalConsole.error;
+        console.info = this.originalConsole.info;
+        console.debug = this.originalConsole.debug;
+        this.consoleInstalled = false;
+    }
+
+    // ─── Helpers ──────────────────────────────────────────────────────────
+
+    private _mapEnvelopeCategory(envelope: Envelope): EnvelopeCategory {
+        const name = envelope.payload?.name || '';
+        if (envelope.type === 'crash' || name === '$crash') return 'crash';
+        if (name === '$network_request') return 'network';
+        if (name === '$navigation' || name === '$screen_view') return 'navigation';
+        if (name === '$app_state_change' || name === '$session_start') return 'lifecycle';
+        if (envelope.type === 'log') return 'log';
+        return 'custom';
+    }
+
+    private _inferLogLevel(envelope: Envelope): LogLevel | undefined {
+        const name = envelope.payload?.name || '';
+        if (name === '$crash') return 'error';
+        if (envelope.type === 'crash') return 'error';
+        return undefined;
+    }
+
+    private _inferTags(envelope: Envelope): string[] {
+        const tags: string[] = [];
+        const name = envelope.payload?.name || '';
+        if (name.startsWith('$')) tags.push('system');
+        if (envelope.type) tags.push(envelope.type);
+        return tags;
+    }
+
+    private _generateId(): string {
+        return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    }
+
+    /**
+     * Read the current recording session ID from the injected provider.
+     * Returns null when: no provider set, or no recording active.
+     * This is the ONLY place in this file that reads recordingSessionId.
+     */
+    private _getRecordingSessionId(): string | null {
+        try {
+            return this.recordingSessionProvider?.() ?? null;
+        } catch {
+            return null;
+        }
+    }
+
+    private _safeSerialize(value: unknown): unknown {
+        try {
+            if (value === null || value === undefined) return value;
+            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                return value;
+            }
+            if (value instanceof Error) {
+                return { message: value.message, stack: value.stack, name: value.name };
+            }
+            // Try JSON round-trip for safe serialization
+            return JSON.parse(JSON.stringify(value));
+        } catch {
+            return String(value);
+        }
+    }
+}