@scalebun-release/react-native 2.5.0

package/src/debug/redaction.ts

@@ -0,0 +1,483 @@
+/**
+ * ScaleBun Debug — Security Redaction & PII Detection
+ *
+ * Ensures sensitive data is never sent over the debug transport.
+ * All functions return new objects (never mutate originals).
+ * All functions are no-throw safe.
+ */
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const REDACTED = '[REDACTED]';
+
+// ─── Safety limits (SB-25 / SB-27) ───────────────────────────────────────────
+// The PII scanner runs synchronously on the JS thread inside the app's own
+// fetch()/XHR call. Left unbounded it is both a ReDoS vector (a large body of
+// alphanumeric text can make regex matching cost seconds — an Android ANR) and
+// a payload-amplification / exfiltration channel (one warning object per match).
+// These bounds keep every scan linear and its output small.
+
+/** Never scan more than this many characters — truncate before matching. */
+const MAX_SCAN_INPUT_CHARS = 16 * 1024;
+/** Abandon a scan once it has spent this long on the JS thread. */
+const SCAN_TIME_BUDGET_MS = 10;
+/** Never emit more than this many PII warnings for a single event. */
+const MAX_PII_WARNINGS = 20;
+/** Never pattern-scrub a string value longer than this (bounded work). */
+const MAX_STRING_SCRUB_CHARS = 64 * 1024;
+
+/** Headers that must always be redacted (case-insensitive) */
+const SENSITIVE_HEADERS = new Set([
+    'authorization',
+    'cookie',
+    'set-cookie',
+    'x-api-key',
+    'x-auth-token',
+    'proxy-authorization',
+]);
+
+/**
+ * PII detection patterns.
+ *
+ * SB-25: patterns must be free of catastrophic backtracking. The email pattern
+ * uses non-overlapping character classes with bounded quantifiers so it cannot
+ * backtrack quadratically on adversarial input like `'a'.repeat(N) + '@' + …`.
+ * All quantifiers here are bounded; combined with the input cap above this keeps
+ * matching linear in input size.
+ */
+const PII_PATTERNS: Array<{ name: string; pattern: RegExp }> = [
+    { name: 'email', pattern: /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63}){0,8}\.[A-Za-z]{2,24}/g },
+    { name: 'phone', pattern: /\+?\d{1,3}[-.\s]?\(?\d{2,4}\)?[-.\s]?\d{3,4}[-.\s]?\d{3,4}/g },
+    { name: 'ssn', pattern: /\b\d{3}-\d{2}-\d{4}\b/g },
+    { name: 'credit_card', pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g },
+    { name: 'iban', pattern: /\b[A-Z]{2}\d{2}[A-Z0-9]{10,30}\b/g },
+    { name: 'jwt', pattern: /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/g },
+    { name: 'ip_address', pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g },
+];
+
+/**
+ * Value patterns used to scrub secrets out of raw string bodies (SB-02).
+ * These are applied to string values (including parsed-out JSON string leaves
+ * and non-JSON bodies) where a denylisted key name is not available. All are
+ * bounded / anchored to avoid backtracking.
+ */
+const VALUE_SCRUB_PATTERNS: Array<{ name: string; pattern: RegExp; luhn?: boolean }> = [
+    { name: 'jwt', pattern: /eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}/g },
+    { name: 'email', pattern: /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63}){0,8}\.[A-Za-z]{2,24}/g },
+    { name: 'iban', pattern: /\b[A-Z]{2}\d{2}[A-Z0-9]{10,30}\b/g },
+    { name: 'credit_card', pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{2,7}\b/g, luhn: true },
+];
+
+/** Keys in request/response bodies that likely contain sensitive data */
+const SENSITIVE_BODY_KEYS = new Set([
+    'password',
+    'passwd',
+    'secret',
+    'token',
+    'access_token',
+    'refresh_token',
+    'id_token',
+    'api_key',
+    'apiKey',
+    'private_key',
+    'privateKey',
+    'credit_card',
+    'creditCard',
+    'ccnumber',
+    'cardnumber',
+    'card_number',
+    'pan',
+    'cvv',
+    'cvc',
+    'ssn',
+    'social_security',
+    'nationalid',
+    'national_id',
+    'iban',
+    'otp',
+    'pin',
+    'totp',
+    'mfa',
+    'mnemonic',
+    'seed',
+]);
+
+// ─── Header Redaction ───────────────────────────────────────────────────────
+
+/**
+ * Redact sensitive HTTP headers. Returns a new object with redacted values.
+ * Original headers object is not mutated.
+ */
+export function redactHeaders(
+    headers: Record<string, string> | undefined,
+): Record<string, string> {
+    if (!headers) return {};
+    const result: Record<string, string> = {};
+    try {
+        for (const [key, value] of Object.entries(headers)) {
+            if (SENSITIVE_HEADERS.has(key.toLowerCase())) {
+                result[key] = REDACTED;
+            } else {
+                result[key] = value;
+            }
+        }
+    } catch {
+        // If iteration fails, return empty — never throw
+    }
+    return result;
+}
+
+// ─── Body Redaction ─────────────────────────────────────────────────────────
+
+/** Normalize a key for denylist comparison: lowercase, strip separators. */
+function _normalizeKey(key: string): string {
+    return key.toLowerCase().replace(/[_\-\s]/g, '');
+}
+
+/** Normalized denylist so `access_token`, `accessToken` and `Access-Token` all match. */
+const NORMALIZED_SENSITIVE_KEYS = new Set(
+    Array.from(SENSITIVE_BODY_KEYS, _normalizeKey),
+);
+
+function _isSensitiveKey(key: string): boolean {
+    return NORMALIZED_SENSITIVE_KEYS.has(_normalizeKey(key));
+}
+
+/** Passes the Luhn checksum — used to avoid over-redacting random 16-digit ids. */
+function _luhnValid(digits: string): boolean {
+    const s = digits.replace(/[^\d]/g, '');
+    if (s.length < 12 || s.length > 19) return false;
+    let sum = 0;
+    let alt = false;
+    for (let i = s.length - 1; i >= 0; i--) {
+        let d = s.charCodeAt(i) - 48;
+        if (alt) {
+            d *= 2;
+            if (d > 9) d -= 9;
+        }
+        sum += d;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+}
+
+/**
+ * Scrub structured secrets (JWT, email, IBAN, Luhn-valid card) out of a raw
+ * string value where no denylisted key name is available (SB-02). Bounded work:
+ * the string is capped and every pattern is anchored/bounded.
+ */
+function _scrubSecretsInString(value: string): string {
+    if (value.length > MAX_STRING_SCRUB_CHARS) {
+        value = value.slice(0, MAX_STRING_SCRUB_CHARS);
+    }
+    let out = value;
+    try {
+        for (const { pattern, luhn } of VALUE_SCRUB_PATTERNS) {
+            pattern.lastIndex = 0;
+            out = out.replace(pattern, m => (luhn && !_luhnValid(m) ? m : REDACTED));
+        }
+    } catch {
+        // Never throw — return whatever scrubbing produced so far.
+    }
+    return out;
+}
+
+/**
+ * Deep-redact sensitive keys in a body object. Returns a new object.
+ * Handles nested objects and arrays. Never throws.
+ *
+ * SB-02: string bodies (what JSON.stringify produces — i.e. essentially every
+ * React Native network body) are no longer passed through untouched. If a string
+ * parses as JSON it is deep-redacted and re-serialized; otherwise structured
+ * secrets in the string are scrubbed. This closes the "6 of 9 seeded secrets
+ * survived" leak while leaving non-sensitive metadata intact.
+ */
+export function redactBody(body: unknown, maxDepth = 10): unknown {
+    try {
+        return _redactValue(body, 0, maxDepth);
+    } catch {
+        return REDACTED;
+    }
+}
+
+function _redactValue(value: unknown, depth: number, maxDepth: number): unknown {
+    if (depth > maxDepth) return '[MAX_DEPTH]';
+    if (value === null || value === undefined) return value;
+
+    if (typeof value === 'string') {
+        return _redactString(value, depth, maxDepth);
+    }
+
+    if (Array.isArray(value)) {
+        return value.map(item => _redactValue(item, depth + 1, maxDepth));
+    }
+
+    if (typeof value === 'object') {
+        const result: Record<string, unknown> = {};
+        for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+            if (_isSensitiveKey(key)) {
+                result[key] = REDACTED;
+            } else {
+                result[key] = _redactValue(val, depth + 1, maxDepth);
+            }
+        }
+        return result;
+    }
+
+    return value;
+}
+
+/**
+ * Redact a string value. If it looks like a JSON object/array, parse it, redact
+ * by key, and re-serialize so a serialized body such as
+ * `{"password":"...","otp":"..."}` is scrubbed. Otherwise scrub structured
+ * secrets out of the raw text.
+ */
+function _redactString(value: string, depth: number, maxDepth: number): string {
+    const trimmed = value.trimStart();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(value);
+            if (parsed !== null && typeof parsed === 'object') {
+                const redacted = _redactValue(parsed, depth + 1, maxDepth);
+                return JSON.stringify(redacted);
+            }
+        } catch {
+            // Not valid JSON — fall through to pattern scrubbing.
+        }
+    }
+    return _scrubSecretsInString(value);
+}
+
+// ─── PII Scanning ───────────────────────────────────────────────────────────
+
+export interface PIIWarning {
+    type: string;
+    match: string;
+    /** Where in the data the PII was found */
+    location: string;
+}
+
+/**
+ * Bounded scan context shared across one logical scan (SB-25 / SB-27). Enforces
+ * a wall-clock budget and a warning cap while accumulating per-type counts so the
+ * final output can report `{ email: 5000 }` instead of 5000 fragment objects.
+ */
+interface ScanContext {
+    warnings: PIIWarning[];
+    byType: Record<string, number>;
+    deadline: number;
+    truncated: boolean;
+    total: number;
+}
+
+function _newScanContext(): ScanContext {
+    return {
+        warnings: [],
+        byType: {},
+        deadline: Date.now() + SCAN_TIME_BUDGET_MS,
+        truncated: false,
+        total: 0,
+    };
+}
+
+function _pushWarning(ctx: ScanContext, type: string, rawMatch: string, location: string): void {
+    ctx.total += 1;
+    ctx.byType[type] = (ctx.byType[type] ?? 0) + 1;
+    if (ctx.warnings.length < MAX_PII_WARNINGS) {
+        ctx.warnings.push({ type, match: _maskPII(rawMatch), location });
+    } else {
+        ctx.truncated = true;
+    }
+}
+
+/**
+ * Finalize a scan: append a single summary entry carrying per-type counts when
+ * anything was dropped, so consumers see the full magnitude without the SDK
+ * shipping every matched fragment (SB-27).
+ */
+function _finalizeScan(ctx: ScanContext): PIIWarning[] {
+    if (ctx.truncated) {
+        ctx.warnings.push({
+            type: '_summary',
+            match: `truncated: ${ctx.total} matches`,
+            location: `counts:${JSON.stringify(ctx.byType)}`,
+        });
+    }
+    return ctx.warnings;
+}
+
+function _scanTextInto(text: string, location: string, ctx: ScanContext): void {
+    // SB-25: cap the input before any regex runs, so matching cost is bounded
+    // regardless of the (attacker-controlled) body size.
+    const input = text.length > MAX_SCAN_INPUT_CHARS ? text.slice(0, MAX_SCAN_INPUT_CHARS) : text;
+    try {
+        for (const { name, pattern } of PII_PATTERNS) {
+            pattern.lastIndex = 0;
+            let match = pattern.exec(input);
+            while (match) {
+                _pushWarning(ctx, name, match[0], location);
+                // SB-25: abandon the scan if it has exceeded its time budget.
+                if (Date.now() > ctx.deadline) {
+                    ctx.truncated = true;
+                    return;
+                }
+                if (pattern.lastIndex === match.index) pattern.lastIndex++; // guard zero-width
+                match = pattern.exec(input);
+            }
+        }
+    } catch {
+        // Never throw — keep whatever was found so far.
+    }
+}
+
+/**
+ * Scan a string for PII patterns. Returns a bounded list of warnings.
+ * Never throws.
+ */
+export function scanForPII(text: string, location = 'unknown'): PIIWarning[] {
+    const ctx = _newScanContext();
+    _scanTextInto(text, location, ctx);
+    return _finalizeScan(ctx);
+}
+
+/**
+ * Scan an object deeply for PII. Returns a bounded list of warnings.
+ * Never throws.
+ */
+export function scanObjectForPII(
+    obj: unknown,
+    basePath = '',
+    maxDepth = 10,
+): PIIWarning[] {
+    const ctx = _newScanContext();
+    try {
+        _scanObjectInto(obj, basePath, 0, maxDepth, ctx);
+    } catch {
+        // Never throw
+    }
+    return _finalizeScan(ctx);
+}
+
+function _scanObjectInto(
+    value: unknown,
+    path: string,
+    depth: number,
+    maxDepth: number,
+    ctx: ScanContext,
+): void {
+    if (depth > maxDepth || value === null || value === undefined) return;
+    if (ctx.truncated || Date.now() > ctx.deadline) {
+        ctx.truncated = true;
+        return;
+    }
+
+    if (typeof value === 'string') {
+        _scanTextInto(value, path, ctx);
+        return;
+    }
+
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            if (ctx.truncated) return;
+            _scanObjectInto(value[i], `${path}[${i}]`, depth + 1, maxDepth, ctx);
+        }
+        return;
+    }
+
+    if (typeof value === 'object') {
+        for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+            if (ctx.truncated) return;
+            _scanObjectInto(val, path ? `${path}.${key}` : key, depth + 1, maxDepth, ctx);
+        }
+    }
+}
+
+/**
+ * Mask PII for display — show first/last chars only.
+ * e.g. "john@example.com" -> "jo***com"
+ */
+function _maskPII(value: string): string {
+    if (value.length <= 4) return '***';
+    return value.slice(0, 2) + '***' + value.slice(-3);
+}
+
+// ─── URL Redaction ──────────────────────────────────────────────────────────
+
+/**
+ * Redact query parameters that may contain tokens/secrets.
+ * Never throws.
+ */
+export function redactUrl(url: string): string {
+    try {
+        const sensitiveParams = new Set([
+            'token', 'access_token', 'refresh_token',
+            'api_key', 'apiKey', 'key', 'secret', 'password',
+        ]);
+
+        const parsed = new URL(url);
+        for (const param of sensitiveParams) {
+            if (parsed.searchParams.has(param)) {
+                parsed.searchParams.set(param, REDACTED);
+            }
+        }
+        return parsed.toString();
+    } catch {
+        // If URL parsing fails, return as-is
+        return url;
+    }
+}
+
+// ─── Full Redaction Pipeline ────────────────────────────────────────────────
+
+export interface RedactedNetworkEvent {
+    url: string;
+    method: string;
+    status: number;
+    duration: number;
+    requestHeaders: Record<string, string>;
+    responseHeaders: Record<string, string>;
+    requestBody: unknown;
+    responseBody: unknown;
+    piiWarnings: PIIWarning[];
+}
+
+/**
+ * Apply full redaction pipeline to a network event.
+ */
+export function redactNetworkEvent(event: {
+    url?: string;
+    method?: string;
+    status?: number;
+    duration?: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: unknown;
+    responseBody?: unknown;
+}): RedactedNetworkEvent {
+    // One bounded context for the whole event so the aggregate warning count and
+    // scan time stay capped across url + request + response (SB-25 / SB-27).
+    const ctx = _newScanContext();
+    if (event.url) {
+        _scanTextInto(event.url, 'url', ctx);
+    }
+    if (event.requestBody) {
+        _scanObjectInto(event.requestBody, 'requestBody', 0, 10, ctx);
+    }
+    if (event.responseBody) {
+        _scanObjectInto(event.responseBody, 'responseBody', 0, 10, ctx);
+    }
+    const piiWarnings = _finalizeScan(ctx);
+
+    return {
+        url: event.url ? redactUrl(event.url) : '',
+        method: event.method ?? 'GET',
+        status: event.status ?? 0,
+        duration: event.duration ?? 0,
+        requestHeaders: redactHeaders(event.requestHeaders),
+        responseHeaders: redactHeaders(event.responseHeaders),
+        requestBody: redactBody(event.requestBody),
+        responseBody: redactBody(event.responseBody),
+        piiWarnings,
+    };
+}

package/src/debug/replayWiring.ts

@@ -0,0 +1,148 @@
+/**
+ * ScaleBun Debug — Replay Wiring
+ *
+ * Handles ReplaySdk initialization with desktop transport,
+ * and deferred native capture wiring into SessionManager.
+ */
+
+import { ReplaySdk } from '../features/replay/public/api';
+import type { ReplayConfig } from '../features/replay/public/types';
+import type { DebugTransport } from './transport';
+import type { SessionManager as SessionManagerType } from '../features/session/SessionManager';
+import { logger } from '../core/logger/internalLogger';
+import { resolvePlatformOS } from '../core/context/device';
+
+// ─── State ──────────────────────────────────────────────────────────────────
+
+let _replaySdkInitialized = false;
+let _nativeCaptureWired = false;
+
+// ─── ReplaySdk Init ─────────────────────────────────────────────────────────
+
+/**
+ * Initialize ReplaySdk with desktop transport for dual-mode streaming.
+ * Non-fatal — logs warning on failure.
+ */
+export function initReplaySdk(
+    replayConfig: Partial<ReplayConfig> | undefined,
+    transport: DebugTransport,
+): void {
+    if (replayConfig === undefined) {
+        __DEV__ && logger.debug('Replay feature disabled — skipping replay-sdk init');
+        return;
+    }
+    try {
+        ReplaySdk.init(replayConfig, { debugTransport: transport }).then(() => {
+            _replaySdkInitialized = true;
+            __DEV__ && logger.info('Replay SDK initialized with desktop transport');
+        }).catch((err: any) => {
+            logger.warn('Replay SDK init failed (non-fatal):', err?.message);
+        });
+    } catch (recErr: any) {
+        logger.warn('Replay SDK init failed (non-fatal):', recErr?.message);
+    }
+}
+
+// ─── Native Capture Wiring ──────────────────────────────────────────────────
+
+/**
+ * Wire native screenshot bridge into SessionManager.
+ * Uses deferred init with idempotent guard, retry, and no duplicate binding.
+ */
+export function wireNativeCaptureDeferred(
+    getSessionManager: () => SessionManagerType | null,
+): void {
+    if (_nativeCaptureWired) {
+        __DEV__ && logger.debug('[AutoCapture] Already wired — skipping');
+        return;
+    }
+
+    const attempt = (retryCount: number) => {
+        try {
+            if (_nativeCaptureWired) return;
+            const sessionManager = getSessionManager();
+            if (!sessionManager) {
+                if (retryCount < 1) {
+                    setTimeout(() => attempt(retryCount + 1), 1500);
+                }
+                return;
+            }
+
+            // Try bridgeAdapter first (higher quality)
+            try {
+                const { bridgeAdapter } = require('../features/replay/bridge/adapters/bridgeAdapter');
+                const { Dimensions, Platform } = require('react-native');
+
+                if (bridgeAdapter.isAvailable()) {
+                    const nativeBridgeCapture = async (
+                        _sessionId: string,
+                        _reason: string,
+                        _quality: any,
+                    ) => {
+                        try {
+                            const result = await bridgeAdapter.captureScreenshot(_reason || 'session');
+                            if (!result?.base64) return null;
+
+                            const { width, height } = Dimensions.get('window');
+                            return {
+                                base64: result.base64,
+                                width: result.width || Math.round(width),
+                                height: result.height || Math.round(height),
+                                byteSize: result.sizeBytes || Math.round(result.base64.length * 0.75),
+                                format: (result.format ?? 'jpeg') as string,
+                                frameHash: (result as any).frameHash as string | undefined,
+                                platform: resolvePlatformOS() as 'android' | 'ios',
+                            };
+                        } catch {
+                            return null;
+                        }
+                    };
+
+                    if (typeof (sessionManager as any).setNativeCapture === 'function') {
+                        (sessionManager as any).setNativeCapture(nativeBridgeCapture);
+                        _nativeCaptureWired = true;
+                        __DEV__ && logger.info('[AutoCapture] ✅ Native bridge capture wired (bridgeAdapter)');
+                        return;
+                    }
+                }
+            } catch {
+                // bridgeAdapter not available — fall through to NativeModules
+            }
+
+            // Fallback: SessionManager was already created with nativeCapture
+            _nativeCaptureWired = true;
+            __DEV__ && logger.info('[AutoCapture] ✅ Native capture available via SessionManager bootstrap');
+
+        } catch (err: any) {
+            logger.warn('[AutoCapture] Wiring failed:', err?.message);
+            if (retryCount < 1) {
+                setTimeout(() => attempt(retryCount + 1), 1500);
+            }
+        }
+    };
+
+    setTimeout(() => attempt(0), 500);
+}
+
+// ─── Getters ────────────────────────────────────────────────────────────────
+
+export function isReplaySdkInitialized(): boolean {
+    return _replaySdkInitialized;
+}
+
+export function getReplaySdk(): typeof ReplaySdk {
+    return ReplaySdk;
+}
+
+// ─── Teardown / Reset ───────────────────────────────────────────────────────
+
+export function teardownReplay(): void {
+    if (_replaySdkInitialized) {
+        ReplaySdk.destroy().catch(() => { /* no-throw */ });
+    }
+}
+
+export function resetReplayState(): void {
+    _replaySdkInitialized = false;
+    _nativeCaptureWired = false;
+}

package/src/debug/screenTracking.ts

@@ -0,0 +1,55 @@
+/**
+ * ScaleBun Debug — Screen Tracking
+ *
+ * Module-level screen state tracking and auto screen detection wiring.
+ * Feeds screen changes to SessionManager, PerformanceFeature, ProfilerFeature.
+ */
+
+import { AutoScreenDetector } from '../features/navigation/AutoScreenDetector';
+import type { PerformanceFeature } from '../features/performance/PerformanceFeature';
+import type { ProfilerFeature } from '../features/profiler/ProfilerFeature';
+import type { SessionManager as SessionManagerType } from '../features/session/SessionManager';
+import { logger } from '../core/logger/internalLogger';
+
+// ─── Screen State ───────────────────────────────────────────────────────────
+
+let _trackedScreen: string | null = null;
+
+/** Update the tracked screen — called by navigation detectors */
+export function setTrackedScreen(screen: string | null): void {
+    _trackedScreen = screen;
+}
+
+/** Get the current tracked screen — used by event stream enrichment */
+export function getTrackedScreen(): string | null {
+    return _trackedScreen;
+}
+
+// ─── Auto Screen Detection ──────────────────────────────────────────────────
+
+/**
+ * Start auto screen detection and wire callbacks to all subsystems.
+ */
+export function startAutoScreenDetection(): AutoScreenDetector | null {
+    try {
+        const detector = AutoScreenDetector.getInstance();
+
+        // The core SDK path (SDKBootstrapper) owns starting the detector and
+        // wiring it to SessionManager and PerformanceFeature.
+        // This debug/screenTracking module now only mirrors the screen state
+        // to the local debug stream breadcrumbs.
+        detector.onScreenChange((screenName, source) => {
+            // Update cross-cutting screen tracker
+            setTrackedScreen(screenName);
+            __DEV__ && logger.debug(`[AutoScreenDebug] Screen mirrored → '${screenName}' (source: ${source})`);
+        });
+
+        // Ensure it's started in case debug connects before SDKBootstrapper finishes
+        detector.start();
+        __DEV__ && logger.info('[AutoScreen] Auto screen detection debug-mirror started');
+        return detector;
+    } catch (err: any) {
+        logger.warn('[AutoScreen] Failed to start debug-mirror:', err?.message);
+        return null;
+    }
+}