@scalebun/react-native 1.0.0 → 1.0.2

package/src/debug/commands.ts

@@ -1,597 +1,597 @@
-/**
- * ScaleBun Debug — Command Registry & Handlers
- *
- * Handles commands sent from the Desktop app to the SDK.
- * Each command has a name and a handler function.
- * Built-in commands: ping, setLogLevel, clearQueue, triggerFlush, addBreadcrumb, snapshot
- * Journey commands: journeyRecordToggle, journeyCaptureStep, journeySave, journeyRun, journeyStopRun
- */
-
-import {
-    type CommandMessage,
-    type CommandResultMessage,
-    type CommandName,
-    PROTOCOL_VERSION,
-} from './protocol';
-import type { DebugTransport } from './transport';
-import type { DebugEventStream } from './stream';
-import { logger, LogLevel } from '../core/logger/internalLogger';
-import { coreContainer } from '../core/di/container';
-import type { PersistentQueue } from '../pipeline/queue/persistentQueue';
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-type CommandHandlerFn = (
-    args: Record<string, unknown> | undefined,
-) => Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }>;
-
-// ─── Journey Manager Interface (to avoid circular deps) ─────────────────────
-
-interface IJourneyManager {
-    readonly isRecording: boolean;
-    startRecording(): void;
-    stopRecording(): void;
-    captureStep(gestureMode: string, label?: string, note?: string): Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }>;
-    saveJourney(name: string, journeyId?: string): Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }>;
-    runJourney(journeyData: any, options?: any): Promise<void>;
-    stopRun(): void;
-}
-
-// ─── Session Manager Interface (to avoid circular deps) ─────────────────────
-
-interface ISessionManager {
-    readonly isActive: boolean;
-    readonly currentSessionId: string | null;
-    startSession(metadata?: Record<string, unknown>): void;
-    endSession(reason?: 'ended' | 'timeout'): void;
-    emitEvent(type: string, opts?: Record<string, unknown>): void;
-    captureManualFrame?(): Promise<any>;
-}
-
-// ─── Command Registry ───────────────────────────────────────────────────────
-
-export class CommandRegistry {
-    private handlers = new Map<string, CommandHandlerFn>();
-    private transport: DebugTransport;
-    private stream: DebugEventStream | null = null;
-    private flushFn: (() => Promise<void>) | null = null;
-    private journeyManager: IJourneyManager | null = null;
-    private sessionManager: ISessionManager | null = null;
-    private _journeyEnabled = false;
-    private _debugReady = false;
-
-    constructor(transport: DebugTransport) {
-        this.transport = transport;
-        this._registerBuiltins();
-    }
-
-    /** Set the event stream reference (for breadcrumb command) */
-    setStream(stream: DebugEventStream): void {
-        this.stream = stream;
-    }
-
-    /** Set the flush function reference */
-    setFlushFn(fn: () => Promise<void>): void {
-        this.flushFn = fn;
-    }
-
-
-    /** Set the session manager reference */
-    setSessionManager(manager: ISessionManager): void {
-        this.sessionManager = manager;
-    }
-
-    /** Set the journey manager reference */
-    setJourneyManager(manager: IJourneyManager): void {
-        this.journeyManager = manager;
-    }
-
-    /** Set journey enabled flag */
-    setJourneyEnabled(enabled: boolean): void {
-        this._journeyEnabled = enabled;
-    }
-
-    /** Set debug ready flag */
-    setDebugReady(ready: boolean): void {
-        this._debugReady = ready;
-    }
-
-    /** Register a custom command handler */
-    register(name: string, handler: CommandHandlerFn): void {
-        this.handlers.set(name, handler);
-    }
-
-    /** Handle an incoming command from desktop. Never throws. */
-    async handleCommand(cmd: CommandMessage): Promise<void> {
-        try {
-            const handler = this.handlers.get(cmd.payload.name);
-            if (!handler) {
-                this._sendResult(cmd.payload.commandId, false, undefined, `Unknown command: ${cmd.payload.name}`);
-                return;
-            }
-
-            const result = await handler(cmd.payload.args);
-            this._sendResult(cmd.payload.commandId, result.success, result.data, result.error);
-        } catch (e) {
-            this._sendResult(
-                cmd.payload.commandId,
-                false,
-                undefined,
-                e instanceof Error ? e.message : 'Command execution failed',
-            );
-        }
-    }
-
-    // ─── Built-in Commands ──────────────────────────────────────────────────
-
-    private _registerBuiltins(): void {
-        // ping → pong
-        this.register('ping', async () => {
-            return { success: true, data: { pong: true, timestamp: Date.now() } };
-        });
-
-        // setLogLevel → update SDK internal logger level
-        this.register('setLogLevel', async (args) => {
-            const level = args?.level;
-            const levelMap: Record<string, LogLevel> = {
-                debug: LogLevel.DEBUG,
-                info: LogLevel.INFO,
-                warn: LogLevel.WARN,
-                error: LogLevel.ERROR,
-                none: LogLevel.NONE,
-            };
-
-            if (typeof level !== 'string' || !levelMap[level]) {
-                return { success: false, error: `Invalid log level: ${level}. Valid: debug, info, warn, error, none` };
-            }
-
-            logger.setLevel(levelMap[level]!);
-            return { success: true, data: { level } };
-        });
-
-        // clearQueue → clear the persistent event queue
-        this.register('clearQueue', async () => {
-            try {
-                const queue = coreContainer.get<PersistentQueue>('PersistentQueue');
-                const count = queue.length();
-                queue.clear();
-                return { success: true, data: { clearedCount: count } };
-            } catch {
-                return { success: true, data: { clearedCount: 0, note: 'Queue not initialized' } };
-            }
-        });
-
-        // triggerFlush → force flush the event queue
-        this.register('triggerFlush', async () => {
-            if (this.flushFn) {
-                await this.flushFn();
-                return { success: true, data: { flushed: true } };
-            }
-            return { success: false, error: 'Flush function not available' };
-        });
-
-        // addBreadcrumb → add a debug breadcrumb
-        this.register('addBreadcrumb', async (args) => {
-            const message = typeof args?.message === 'string' ? args.message : 'Debug breadcrumb';
-            if (this.stream) {
-                this.stream.tapBreadcrumb(message, args as Record<string, unknown>);
-            }
-            return { success: true, data: { message } };
-        });
-
-        // snapshot → capture current app state
-        this.register('snapshot', async () => {
-            let queueLength = 0;
-            try {
-                queueLength = coreContainer.get<PersistentQueue>('PersistentQueue').length();
-            } catch { /* queue not yet initialized */ }
-            return {
-                success: true,
-                data: {
-                    queueLength,
-                    timestamp: Date.now(),
-                    connectionState: this.transport.getState(),
-                },
-            };
-        });
-
-        // startReplay → routes to SessionManager or ReplaySdk
-        this.register('startReplay', async (args) => {
-            // Prefer unified SessionManager
-            if (this.sessionManager) {
-                if (this.sessionManager.isActive) {
-                    return { success: false, error: 'Session already active' };
-                }
-                this.sessionManager.startSession();
-                return { success: true, data: { sessionId: this.sessionManager.currentSessionId, unified: true } };
-            }
-            return { success: false, error: 'Session manager not initialized' };
-        });
-
-        // stopReplay → routes to SessionManager or ReplaySdk
-        this.register('stopReplay', async () => {
-            // Prefer unified SessionManager
-            if (this.sessionManager) {
-                if (!this.sessionManager.isActive) {
-                    return { success: false, error: 'No active session' };
-                }
-                this.sessionManager.endSession();
-                return { success: true, data: { unified: true } };
-            }
-            return { success: false, error: 'Session manager not initialized' };
-        });
-
-        // ─── Unified Session Commands ────────────────────────────────────
-
-        // startSession → start unified session
-        this.register('startSession', async (args) => {
-            if (!this.sessionManager) {
-                return { success: false, error: 'Session manager not initialized' };
-            }
-            // If a session is already active, end it first to ensure clean state.
-            // This prevents stale async work from a previous session leaking in.
-            if (this.sessionManager.isActive) {
-                this.sessionManager.endSession();
-            }
-            this.sessionManager.startSession(args as any);
-            return { success: true, data: { sessionId: this.sessionManager.currentSessionId } };
-        });
-
-        // stopSession → stop unified session
-        this.register('stopSession', async () => {
-            if (!this.sessionManager) {
-                return { success: false, error: 'Session manager not initialized' };
-            }
-            if (!this.sessionManager.isActive) {
-                return { success: false, error: 'No active session' };
-            }
-            this.sessionManager.endSession();
-            return { success: true };
-        });
-
-        // captureFrame → manual frame capture (Desktop Capture Step button)
-        this.register('captureFrame', async () => {
-            if (!this.sessionManager) {
-                return { success: false, error: 'Session manager not initialized' };
-            }
-            if (!this.sessionManager.isActive) {
-                return { success: false, error: 'No active session' };
-            }
-            if (this.sessionManager.captureManualFrame) {
-                try {
-                    const frame = await this.sessionManager.captureManualFrame();
-                    return { success: true, data: { triggered: true, frameId: frame?.frameId } };
-                } catch (err) {
-                    return { success: true, data: { triggered: true, captureError: err instanceof Error ? err.message : 'capture failed' } };
-                }
-            }
-            return { success: true, data: { triggered: true, note: 'captureManualFrame not available' } };
-        });
-
-        // ─── Journey Commands ────────────────────────────────────────────
-
-        // journeyRecordToggle → start/stop journey recording
-        this.register('journeyRecordToggle', async (args) => {
-            if (!this._journeyEnabled) {
-                return {
-                    success: false,
-                    data: { code: 'JOURNEY_DISABLED' },
-                    error: 'Enable journey in enableDebug({journey:{enabled:true}})',
-                };
-            }
-            if (!this._debugReady) {
-                return {
-                    success: false,
-                    data: { code: 'SDK_NOT_READY' },
-                    error: 'Wait for EVENT_DEBUG_READY',
-                };
-            }
-            if (!this.journeyManager) {
-                return {
-                    success: false,
-                    data: { code: 'JOURNEY_DISABLED' },
-                    error: 'Journey manager not initialized',
-                };
-            }
-
-            const on = args?.on as boolean;
-            if (on) {
-                this.journeyManager.startRecording();
-            } else {
-                this.journeyManager.stopRecording();
-            }
-            return { success: true, data: { recording: on } };
-        });
-
-        // journeyCaptureStep → capture a step with current gesture + screenshot
-        this.register('journeyCaptureStep', async (args) => {
-            if (!this._journeyEnabled) {
-                return {
-                    success: false,
-                    data: { code: 'JOURNEY_DISABLED' },
-                    error: 'Enable journey in enableDebug({journey:{enabled:true}})',
-                };
-            }
-            if (!this._debugReady || !this.journeyManager) {
-                return {
-                    success: false,
-                    data: { code: 'SDK_NOT_READY' },
-                    error: 'Wait for EVENT_DEBUG_READY',
-                };
-            }
-            if (!this.journeyManager.isRecording) {
-                return { success: false, error: 'Not recording — toggle record first' };
-            }
-
-            const gestureMode = (args?.gestureMode as string) || 'TAP';
-            const label = args?.label as string | undefined;
-            const note = args?.note as string | undefined;
-            return this.journeyManager.captureStep(gestureMode, label, note);
-        });
-
-        // journeySave → save the current recorded journey
-        this.register('journeySave', async (args) => {
-            if (!this._journeyEnabled || !this.journeyManager) {
-                return {
-                    success: false,
-                    data: { code: 'JOURNEY_DISABLED' },
-                    error: 'Journey not enabled',
-                };
-            }
-            const name = (args?.name as string) || 'Untitled Journey';
-            const journeyId = args?.journeyId as string | undefined;
-            return this.journeyManager.saveJourney(name, journeyId);
-        });
-
-        // journeyRun → run a saved journey
-        this.register('journeyRun', async (args) => {
-            if (!this._journeyEnabled || !this.journeyManager) {
-                return {
-                    success: false,
-                    data: { code: 'JOURNEY_DISABLED' },
-                    error: 'Journey not enabled',
-                };
-            }
-            if (!this._debugReady) {
-                return {
-                    success: false,
-                    data: { code: 'SDK_NOT_READY' },
-                    error: 'Wait for EVENT_DEBUG_READY',
-                };
-            }
-
-            const journeyData = args?.journeyData;
-            const options = args?.options;
-            // Run asynchronously — status events emitted during execution
-            this.journeyManager.runJourney(journeyData, options).catch(() => { });
-            return { success: true, data: { started: true } };
-        });
-
-        // journeyStopRun → stop a running journey
-        this.register('journeyStopRun', async () => {
-            if (!this.journeyManager) {
-                return { success: false, error: 'Journey manager not available' };
-            }
-            this.journeyManager.stopRun();
-            return { success: true };
-        });
-
-        // ─── Performance Monitoring Controls ────────────────────────────
-        this.register('startPerformanceMonitoring', async () => {
-            try {
-                const { getPerformanceFeature, getProfilerFeature } = require('./bootstrap');
-                const perf = getPerformanceFeature();
-                if (perf) {
-                    perf.startContinuousCollection();
-                }
-                const profiler = getProfilerFeature();
-                if (profiler && !profiler.isActive()) {
-                    await profiler.start();
-                }
-                return { success: true, data: { status: 'monitoring_started' } };
-            } catch (err) {
-                return { success: false, error: err instanceof Error ? err.message : 'failed to start performance monitoring' };
-            }
-        });
-
-        this.register('stopPerformanceMonitoring', async () => {
-            try {
-                const { getPerformanceFeature, getProfilerFeature } = require('./bootstrap');
-                const perf = getPerformanceFeature();
-                if (perf) {
-                    perf.stopContinuousCollection();
-                }
-                const profiler = getProfilerFeature();
-                if (profiler && profiler.isActive()) {
-                    await profiler.stop();
-                }
-                return { success: true, data: { status: 'monitoring_stopped' } };
-            } catch (err) {
-                return { success: false, error: err instanceof Error ? err.message : 'failed to stop performance monitoring' };
-            }
-        });
-
-        // ─── Performance Screenshot Capture ─────────────────────────────
-        // Captures a screenshot independently of session replay.
-        // Primary path: standalone native capture (no session needed).
-        // Fallback: session-based captureManualFrame (if session is active).
-        // Sends the captured frame via transport with 'perf-capture' source tag.
-
-        this.register('perfCaptureScreen', async (args) => {
-            const screenName = (args?.screenName as string) || 'unknown';
-            try {
-                // ─── Primary: standalone native capture (no session required) ───
-                let nativeResult: { base64: string; width: number; height: number; sizeBytes: number; format: string; timestamp: number } | null = null;
-                try {
-                    // Lazy import to avoid circular dependency
-                    const { bridgeAdapter } = require('../features/replay/bridge/adapters/bridgeAdapter');
-                    if (bridgeAdapter.isAvailable()) {
-                        nativeResult = await bridgeAdapter.captureScreenshot('perfCapture');
-                    }
-                } catch { /* no-throw */ }
-
-                if (nativeResult?.base64) {
-                    // Send via transport as session:frame event with performance provenance
-                    this._sendPerfScreenshot(screenName, nativeResult);
-                    return {
-                        success: true,
-                        data: {
-                            captured: true,
-                            source: 'native-standalone',
-                            screenName,
-                            sizeBytes: nativeResult.sizeBytes,
-                            width: nativeResult.width,
-                            height: nativeResult.height,
-                        },
-                    };
-                }
-
-                // ─── Fallback: session-based capture (requires active session) ──
-                if (this.sessionManager?.captureManualFrame) {
-                    const frame = await this.sessionManager.captureManualFrame();
-                    if (frame) {
-                        return {
-                            success: true,
-                            data: {
-                                captured: true,
-                                source: 'session-capture',
-                                frameId: frame.frameId,
-                                screenName,
-                            },
-                        };
-                    }
-                }
-
-                // ─── No capture path available ──────────────────────────────────
-                return {
-                    success: true,
-                    data: {
-                        captured: false,
-                        source: 'none',
-                        screenName,
-                        reason: 'Native capture module not available. Ensure the native module is linked.',
-                    },
-                };
-            } catch (err) {
-                return {
-                    success: false,
-                    error: err instanceof Error ? err.message : 'Screenshot capture failed',
-                };
-            }
-        });
-
-        // ─── App Control: Reload ────────────────────────────────────────
-        // Desktop → SDK: trigger app reload.
-        // Debug mode: acknowledge immediately, then DevSettings.reload() on a short delay
-        // so the command_result can flush to the transport before the JS runtime restarts.
-        // Release mode: return structured "unsupported" result.
-        this.register('reloadApp', async () => {
-            try {
-                if (__DEV__) {
-                    // Lazy-require to avoid module-scope crashes in bridgeless/new-arch
-                    const { DevSettings } = require('react-native');
-                    if (typeof DevSettings?.reload !== 'function') {
-                        return { success: false, error: 'DevSettings.reload is not available in this environment' };
-                    }
-                    // Schedule reload after a short delay so the ack flushes first
-                    setTimeout(() => {
-                        try { DevSettings.reload(); } catch { /* no-throw */ }
-                    }, 100);
-                    return { success: true, data: { action: 'reload_requested' } };
-                }
-                // Release builds: reload is not safely supported
-                return {
-                    success: false,
-                    data: { action: 'unsupported_in_release' },
-                    error: 'App reload is not supported in release builds',
-                };
-            } catch (err) {
-                return {
-                    success: false,
-                    error: err instanceof Error ? err.message : 'Reload failed',
-                };
-            }
-        });
-
-        // exportReportResult → handle export completion from desktop
-        // Desktop sends this command after processing an export:request event.
-        // Delegates to bootstrap._handleExportResult() which resolves the pending Promise.
-        this.register('exportReportResult', async (args) => {
-            try {
-                const { _handleExportResult } = require('./bootstrap');
-                _handleExportResult(args || {});
-                return { success: true, data: { handled: true } };
-            } catch (err) {
-                return {
-                    success: false,
-                    error: err instanceof Error ? err.message : 'Export result handling failed',
-                };
-            }
-        });
-    }
-
-    // ─── Perf Screenshot Transport ──────────────────────────────────────────
-
-    /**
-     * Send a captured screenshot via transport as a session:frame event.
-     * Uses explicit 'perf-capture' source tag to distinguish from replay frames.
-     */
-    private _sendPerfScreenshot(
-        screenName: string,
-        frame: { base64: string; width: number; height: number; sizeBytes: number; format: string; timestamp: number },
-    ): void {
-        try {
-            // Cast to any: session:frame is a valid wire protocol message type
-            // understood by the desktop, but not declared in the SDK's command
-            // protocol union (which only covers command/event/metric types).
-            (this.transport as any).send({
-                type: 'session:frame',
-                protocolVersion: PROTOCOL_VERSION,
-                deviceId: this.transport.deviceId,
-                sessionId: this.transport.sessionId,
-                timestamp: frame.timestamp || Date.now(),
-                sequence: this.transport.nextSequence(),
-                payload: {
-                    frameId: `perf-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`,
-                    sessionId: this.transport.sessionId,
-                    sequenceNumber: 0,
-                    screenName,
-                    trigger: 'perf-capture',
-                    format: frame.format,
-                    sizeBytes: frame.sizeBytes,
-                    width: frame.width,
-                    height: frame.height,
-                    imageData: frame.base64,
-                    source: 'perf-capture', // Explicit provenance tag
-                },
-            });
-        } catch { /* no-throw */ }
-    }
-
-    private _sendResult(
-        commandId: string,
-        success: boolean,
-        data?: Record<string, unknown>,
-        error?: string,
-    ): void {
-        try {
-            const result: CommandResultMessage = {
-                type: 'command_result',
-                protocolVersion: PROTOCOL_VERSION,
-                deviceId: this.transport.deviceId,
-                sessionId: this.transport.sessionId,
-                timestamp: Date.now(),
-                sequence: this.transport.nextSequence(),
-                payload: {
-                    commandId,
-                    success,
-                    ...(data ? { data } : {}),
-                    ...(error ? { error } : {}),
-                },
-            };
-            this.transport.send(result);
-        } catch {
-            // No-throw
-        }
-    }
-}
+/**
+ * ScaleBun Debug — Command Registry & Handlers
+ *
+ * Handles commands sent from the Desktop app to the SDK.
+ * Each command has a name and a handler function.
+ * Built-in commands: ping, setLogLevel, clearQueue, triggerFlush, addBreadcrumb, snapshot
+ * Journey commands: journeyRecordToggle, journeyCaptureStep, journeySave, journeyRun, journeyStopRun
+ */
+
+import {
+    type CommandMessage,
+    type CommandResultMessage,
+    type CommandName,
+    PROTOCOL_VERSION,
+} from './protocol';
+import type { DebugTransport } from './transport';
+import type { DebugEventStream } from './stream';
+import { logger, LogLevel } from '../core/logger/internalLogger';
+import { coreContainer } from '../core/di/container';
+import type { PersistentQueue } from '../pipeline/queue/persistentQueue';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+type CommandHandlerFn = (
+    args: Record<string, unknown> | undefined,
+) => Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }>;
+
+// ─── Journey Manager Interface (to avoid circular deps) ─────────────────────
+
+interface IJourneyManager {
+    readonly isRecording: boolean;
+    startRecording(): void;
+    stopRecording(): void;
+    captureStep(gestureMode: string, label?: string, note?: string): Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }>;
+    saveJourney(name: string, journeyId?: string): Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }>;
+    runJourney(journeyData: any, options?: any): Promise<void>;
+    stopRun(): void;
+}
+
+// ─── Session Manager Interface (to avoid circular deps) ─────────────────────
+
+interface ISessionManager {
+    readonly isActive: boolean;
+    readonly currentSessionId: string | null;
+    startSession(metadata?: Record<string, unknown>): void;
+    endSession(reason?: 'ended' | 'timeout'): void;
+    emitEvent(type: string, opts?: Record<string, unknown>): void;
+    captureManualFrame?(): Promise<any>;
+}
+
+// ─── Command Registry ───────────────────────────────────────────────────────
+
+export class CommandRegistry {
+    private handlers = new Map<string, CommandHandlerFn>();
+    private transport: DebugTransport;
+    private stream: DebugEventStream | null = null;
+    private flushFn: (() => Promise<void>) | null = null;
+    private journeyManager: IJourneyManager | null = null;
+    private sessionManager: ISessionManager | null = null;
+    private _journeyEnabled = false;
+    private _debugReady = false;
+
+    constructor(transport: DebugTransport) {
+        this.transport = transport;
+        this._registerBuiltins();
+    }
+
+    /** Set the event stream reference (for breadcrumb command) */
+    setStream(stream: DebugEventStream): void {
+        this.stream = stream;
+    }
+
+    /** Set the flush function reference */
+    setFlushFn(fn: () => Promise<void>): void {
+        this.flushFn = fn;
+    }
+
+
+    /** Set the session manager reference */
+    setSessionManager(manager: ISessionManager): void {
+        this.sessionManager = manager;
+    }
+
+    /** Set the journey manager reference */
+    setJourneyManager(manager: IJourneyManager): void {
+        this.journeyManager = manager;
+    }
+
+    /** Set journey enabled flag */
+    setJourneyEnabled(enabled: boolean): void {
+        this._journeyEnabled = enabled;
+    }
+
+    /** Set debug ready flag */
+    setDebugReady(ready: boolean): void {
+        this._debugReady = ready;
+    }
+
+    /** Register a custom command handler */
+    register(name: string, handler: CommandHandlerFn): void {
+        this.handlers.set(name, handler);
+    }
+
+    /** Handle an incoming command from desktop. Never throws. */
+    async handleCommand(cmd: CommandMessage): Promise<void> {
+        try {
+            const handler = this.handlers.get(cmd.payload.name);
+            if (!handler) {
+                this._sendResult(cmd.payload.commandId, false, undefined, `Unknown command: ${cmd.payload.name}`);
+                return;
+            }
+
+            const result = await handler(cmd.payload.args);
+            this._sendResult(cmd.payload.commandId, result.success, result.data, result.error);
+        } catch (e) {
+            this._sendResult(
+                cmd.payload.commandId,
+                false,
+                undefined,
+                e instanceof Error ? e.message : 'Command execution failed',
+            );
+        }
+    }
+
+    // ─── Built-in Commands ──────────────────────────────────────────────────
+
+    private _registerBuiltins(): void {
+        // ping → pong
+        this.register('ping', async () => {
+            return { success: true, data: { pong: true, timestamp: Date.now() } };
+        });
+
+        // setLogLevel → update SDK internal logger level
+        this.register('setLogLevel', async (args) => {
+            const level = args?.level;
+            const levelMap: Record<string, LogLevel> = {
+                debug: LogLevel.DEBUG,
+                info: LogLevel.INFO,
+                warn: LogLevel.WARN,
+                error: LogLevel.ERROR,
+                none: LogLevel.NONE,
+            };
+
+            if (typeof level !== 'string' || !levelMap[level]) {
+                return { success: false, error: `Invalid log level: ${level}. Valid: debug, info, warn, error, none` };
+            }
+
+            logger.setLevel(levelMap[level]!);
+            return { success: true, data: { level } };
+        });
+
+        // clearQueue → clear the persistent event queue
+        this.register('clearQueue', async () => {
+            try {
+                const queue = coreContainer.get<PersistentQueue>('PersistentQueue');
+                const count = queue.length();
+                queue.clear();
+                return { success: true, data: { clearedCount: count } };
+            } catch {
+                return { success: true, data: { clearedCount: 0, note: 'Queue not initialized' } };
+            }
+        });
+
+        // triggerFlush → force flush the event queue
+        this.register('triggerFlush', async () => {
+            if (this.flushFn) {
+                await this.flushFn();
+                return { success: true, data: { flushed: true } };
+            }
+            return { success: false, error: 'Flush function not available' };
+        });
+
+        // addBreadcrumb → add a debug breadcrumb
+        this.register('addBreadcrumb', async (args) => {
+            const message = typeof args?.message === 'string' ? args.message : 'Debug breadcrumb';
+            if (this.stream) {
+                this.stream.tapBreadcrumb(message, args as Record<string, unknown>);
+            }
+            return { success: true, data: { message } };
+        });
+
+        // snapshot → capture current app state
+        this.register('snapshot', async () => {
+            let queueLength = 0;
+            try {
+                queueLength = coreContainer.get<PersistentQueue>('PersistentQueue').length();
+            } catch { /* queue not yet initialized */ }
+            return {
+                success: true,
+                data: {
+                    queueLength,
+                    timestamp: Date.now(),
+                    connectionState: this.transport.getState(),
+                },
+            };
+        });
+
+        // startReplay → routes to SessionManager or ReplaySdk
+        this.register('startReplay', async (args) => {
+            // Prefer unified SessionManager
+            if (this.sessionManager) {
+                if (this.sessionManager.isActive) {
+                    return { success: false, error: 'Session already active' };
+                }
+                this.sessionManager.startSession();
+                return { success: true, data: { sessionId: this.sessionManager.currentSessionId, unified: true } };
+            }
+            return { success: false, error: 'Session manager not initialized' };
+        });
+
+        // stopReplay → routes to SessionManager or ReplaySdk
+        this.register('stopReplay', async () => {
+            // Prefer unified SessionManager
+            if (this.sessionManager) {
+                if (!this.sessionManager.isActive) {
+                    return { success: false, error: 'No active session' };
+                }
+                this.sessionManager.endSession();
+                return { success: true, data: { unified: true } };
+            }
+            return { success: false, error: 'Session manager not initialized' };
+        });
+
+        // ─── Unified Session Commands ────────────────────────────────────
+
+        // startSession → start unified session
+        this.register('startSession', async (args) => {
+            if (!this.sessionManager) {
+                return { success: false, error: 'Session manager not initialized' };
+            }
+            // If a session is already active, end it first to ensure clean state.
+            // This prevents stale async work from a previous session leaking in.
+            if (this.sessionManager.isActive) {
+                this.sessionManager.endSession();
+            }
+            this.sessionManager.startSession(args as any);
+            return { success: true, data: { sessionId: this.sessionManager.currentSessionId } };
+        });
+
+        // stopSession → stop unified session
+        this.register('stopSession', async () => {
+            if (!this.sessionManager) {
+                return { success: false, error: 'Session manager not initialized' };
+            }
+            if (!this.sessionManager.isActive) {
+                return { success: false, error: 'No active session' };
+            }
+            this.sessionManager.endSession();
+            return { success: true };
+        });
+
+        // captureFrame → manual frame capture (Desktop Capture Step button)
+        this.register('captureFrame', async () => {
+            if (!this.sessionManager) {
+                return { success: false, error: 'Session manager not initialized' };
+            }
+            if (!this.sessionManager.isActive) {
+                return { success: false, error: 'No active session' };
+            }
+            if (this.sessionManager.captureManualFrame) {
+                try {
+                    const frame = await this.sessionManager.captureManualFrame();
+                    return { success: true, data: { triggered: true, frameId: frame?.frameId } };
+                } catch (err) {
+                    return { success: true, data: { triggered: true, captureError: err instanceof Error ? err.message : 'capture failed' } };
+                }
+            }
+            return { success: true, data: { triggered: true, note: 'captureManualFrame not available' } };
+        });
+
+        // ─── Journey Commands ────────────────────────────────────────────
+
+        // journeyRecordToggle → start/stop journey recording
+        this.register('journeyRecordToggle', async (args) => {
+            if (!this._journeyEnabled) {
+                return {
+                    success: false,
+                    data: { code: 'JOURNEY_DISABLED' },
+                    error: 'Enable journey in enableDebug({journey:{enabled:true}})',
+                };
+            }
+            if (!this._debugReady) {
+                return {
+                    success: false,
+                    data: { code: 'SDK_NOT_READY' },
+                    error: 'Wait for EVENT_DEBUG_READY',
+                };
+            }
+            if (!this.journeyManager) {
+                return {
+                    success: false,
+                    data: { code: 'JOURNEY_DISABLED' },
+                    error: 'Journey manager not initialized',
+                };
+            }
+
+            const on = args?.on as boolean;
+            if (on) {
+                this.journeyManager.startRecording();
+            } else {
+                this.journeyManager.stopRecording();
+            }
+            return { success: true, data: { recording: on } };
+        });
+
+        // journeyCaptureStep → capture a step with current gesture + screenshot
+        this.register('journeyCaptureStep', async (args) => {
+            if (!this._journeyEnabled) {
+                return {
+                    success: false,
+                    data: { code: 'JOURNEY_DISABLED' },
+                    error: 'Enable journey in enableDebug({journey:{enabled:true}})',
+                };
+            }
+            if (!this._debugReady || !this.journeyManager) {
+                return {
+                    success: false,
+                    data: { code: 'SDK_NOT_READY' },
+                    error: 'Wait for EVENT_DEBUG_READY',
+                };
+            }
+            if (!this.journeyManager.isRecording) {
+                return { success: false, error: 'Not recording — toggle record first' };
+            }
+
+            const gestureMode = (args?.gestureMode as string) || 'TAP';
+            const label = args?.label as string | undefined;
+            const note = args?.note as string | undefined;
+            return this.journeyManager.captureStep(gestureMode, label, note);
+        });
+
+        // journeySave → save the current recorded journey
+        this.register('journeySave', async (args) => {
+            if (!this._journeyEnabled || !this.journeyManager) {
+                return {
+                    success: false,
+                    data: { code: 'JOURNEY_DISABLED' },
+                    error: 'Journey not enabled',
+                };
+            }
+            const name = (args?.name as string) || 'Untitled Journey';
+            const journeyId = args?.journeyId as string | undefined;
+            return this.journeyManager.saveJourney(name, journeyId);
+        });
+
+        // journeyRun → run a saved journey
+        this.register('journeyRun', async (args) => {
+            if (!this._journeyEnabled || !this.journeyManager) {
+                return {
+                    success: false,
+                    data: { code: 'JOURNEY_DISABLED' },
+                    error: 'Journey not enabled',
+                };
+            }
+            if (!this._debugReady) {
+                return {
+                    success: false,
+                    data: { code: 'SDK_NOT_READY' },
+                    error: 'Wait for EVENT_DEBUG_READY',
+                };
+            }
+
+            const journeyData = args?.journeyData;
+            const options = args?.options;
+            // Run asynchronously — status events emitted during execution
+            this.journeyManager.runJourney(journeyData, options).catch(() => { });
+            return { success: true, data: { started: true } };
+        });
+
+        // journeyStopRun → stop a running journey
+        this.register('journeyStopRun', async () => {
+            if (!this.journeyManager) {
+                return { success: false, error: 'Journey manager not available' };
+            }
+            this.journeyManager.stopRun();
+            return { success: true };
+        });
+
+        // ─── Performance Monitoring Controls ────────────────────────────
+        this.register('startPerformanceMonitoring', async () => {
+            try {
+                const { getPerformanceFeature, getProfilerFeature } = require('./bootstrap');
+                const perf = getPerformanceFeature();
+                if (perf) {
+                    perf.startContinuousCollection();
+                }
+                const profiler = getProfilerFeature();
+                if (profiler && !profiler.isActive()) {
+                    await profiler.start();
+                }
+                return { success: true, data: { status: 'monitoring_started' } };
+            } catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : 'failed to start performance monitoring' };
+            }
+        });
+
+        this.register('stopPerformanceMonitoring', async () => {
+            try {
+                const { getPerformanceFeature, getProfilerFeature } = require('./bootstrap');
+                const perf = getPerformanceFeature();
+                if (perf) {
+                    perf.stopContinuousCollection();
+                }
+                const profiler = getProfilerFeature();
+                if (profiler && profiler.isActive()) {
+                    await profiler.stop();
+                }
+                return { success: true, data: { status: 'monitoring_stopped' } };
+            } catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : 'failed to stop performance monitoring' };
+            }
+        });
+
+        // ─── Performance Screenshot Capture ─────────────────────────────
+        // Captures a screenshot independently of session replay.
+        // Primary path: standalone native capture (no session needed).
+        // Fallback: session-based captureManualFrame (if session is active).
+        // Sends the captured frame via transport with 'perf-capture' source tag.
+
+        this.register('perfCaptureScreen', async (args) => {
+            const screenName = (args?.screenName as string) || 'unknown';
+            try {
+                // ─── Primary: standalone native capture (no session required) ───
+                let nativeResult: { base64: string; width: number; height: number; sizeBytes: number; format: string; timestamp: number } | null = null;
+                try {
+                    // Lazy import to avoid circular dependency
+                    const { bridgeAdapter } = require('../features/replay/bridge/adapters/bridgeAdapter');
+                    if (bridgeAdapter.isAvailable()) {
+                        nativeResult = await bridgeAdapter.captureScreenshot('perfCapture');
+                    }
+                } catch { /* no-throw */ }
+
+                if (nativeResult?.base64) {
+                    // Send via transport as session:frame event with performance provenance
+                    this._sendPerfScreenshot(screenName, nativeResult);
+                    return {
+                        success: true,
+                        data: {
+                            captured: true,
+                            source: 'native-standalone',
+                            screenName,
+                            sizeBytes: nativeResult.sizeBytes,
+                            width: nativeResult.width,
+                            height: nativeResult.height,
+                        },
+                    };
+                }
+
+                // ─── Fallback: session-based capture (requires active session) ──
+                if (this.sessionManager?.captureManualFrame) {
+                    const frame = await this.sessionManager.captureManualFrame();
+                    if (frame) {
+                        return {
+                            success: true,
+                            data: {
+                                captured: true,
+                                source: 'session-capture',
+                                frameId: frame.frameId,
+                                screenName,
+                            },
+                        };
+                    }
+                }
+
+                // ─── No capture path available ──────────────────────────────────
+                return {
+                    success: true,
+                    data: {
+                        captured: false,
+                        source: 'none',
+                        screenName,
+                        reason: 'Native capture module not available. Ensure the native module is linked.',
+                    },
+                };
+            } catch (err) {
+                return {
+                    success: false,
+                    error: err instanceof Error ? err.message : 'Screenshot capture failed',
+                };
+            }
+        });
+
+        // ─── App Control: Reload ────────────────────────────────────────
+        // Desktop → SDK: trigger app reload.
+        // Debug mode: acknowledge immediately, then DevSettings.reload() on a short delay
+        // so the command_result can flush to the transport before the JS runtime restarts.
+        // Release mode: return structured "unsupported" result.
+        this.register('reloadApp', async () => {
+            try {
+                if (__DEV__) {
+                    // Lazy-require to avoid module-scope crashes in bridgeless/new-arch
+                    const { DevSettings } = require('react-native');
+                    if (typeof DevSettings?.reload !== 'function') {
+                        return { success: false, error: 'DevSettings.reload is not available in this environment' };
+                    }
+                    // Schedule reload after a short delay so the ack flushes first
+                    setTimeout(() => {
+                        try { DevSettings.reload(); } catch { /* no-throw */ }
+                    }, 100);
+                    return { success: true, data: { action: 'reload_requested' } };
+                }
+                // Release builds: reload is not safely supported
+                return {
+                    success: false,
+                    data: { action: 'unsupported_in_release' },
+                    error: 'App reload is not supported in release builds',
+                };
+            } catch (err) {
+                return {
+                    success: false,
+                    error: err instanceof Error ? err.message : 'Reload failed',
+                };
+            }
+        });
+
+        // exportReportResult → handle export completion from desktop
+        // Desktop sends this command after processing an export:request event.
+        // Delegates to bootstrap._handleExportResult() which resolves the pending Promise.
+        this.register('exportReportResult', async (args) => {
+            try {
+                const { _handleExportResult } = require('./bootstrap');
+                _handleExportResult(args || {});
+                return { success: true, data: { handled: true } };
+            } catch (err) {
+                return {
+                    success: false,
+                    error: err instanceof Error ? err.message : 'Export result handling failed',
+                };
+            }
+        });
+    }
+
+    // ─── Perf Screenshot Transport ──────────────────────────────────────────
+
+    /**
+     * Send a captured screenshot via transport as a session:frame event.
+     * Uses explicit 'perf-capture' source tag to distinguish from replay frames.
+     */
+    private _sendPerfScreenshot(
+        screenName: string,
+        frame: { base64: string; width: number; height: number; sizeBytes: number; format: string; timestamp: number },
+    ): void {
+        try {
+            // Cast to any: session:frame is a valid wire protocol message type
+            // understood by the desktop, but not declared in the SDK's command
+            // protocol union (which only covers command/event/metric types).
+            (this.transport as any).send({
+                type: 'session:frame',
+                protocolVersion: PROTOCOL_VERSION,
+                deviceId: this.transport.deviceId,
+                sessionId: this.transport.sessionId,
+                timestamp: frame.timestamp || Date.now(),
+                sequence: this.transport.nextSequence(),
+                payload: {
+                    frameId: `perf-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`,
+                    sessionId: this.transport.sessionId,
+                    sequenceNumber: 0,
+                    screenName,
+                    trigger: 'perf-capture',
+                    format: frame.format,
+                    sizeBytes: frame.sizeBytes,
+                    width: frame.width,
+                    height: frame.height,
+                    imageData: frame.base64,
+                    source: 'perf-capture', // Explicit provenance tag
+                },
+            });
+        } catch { /* no-throw */ }
+    }
+
+    private _sendResult(
+        commandId: string,
+        success: boolean,
+        data?: Record<string, unknown>,
+        error?: string,
+    ): void {
+        try {
+            const result: CommandResultMessage = {
+                type: 'command_result',
+                protocolVersion: PROTOCOL_VERSION,
+                deviceId: this.transport.deviceId,
+                sessionId: this.transport.sessionId,
+                timestamp: Date.now(),
+                sequence: this.transport.nextSequence(),
+                payload: {
+                    commandId,
+                    success,
+                    ...(data ? { data } : {}),
+                    ...(error ? { error } : {}),
+                },
+            };
+            this.transport.send(result);
+        } catch {
+            // No-throw
+        }
+    }
+}