@scalebun/react-native 1.0.1 → 1.0.2

package/src/features/journey/journeyManager.ts

@@ -1,466 +1,466 @@
-/**
- * ScaleBun SDK — Journey Manager
- *
- * Core orchestrator for journey recording and running.
- * Coordinates gesture buffer, nav detector, screenshot helper,
- * and transport to implement the full journey lifecycle.
- */
-
-import type { DebugTransport } from '../../debug/transport';
-import type {
-    JourneyConfig,
-    JourneyStep,
-    SavedJourney,
-    GestureMode,
-    StepStatus,
-    DebugReadyPayload,
-} from './journeyTypes';
-import { DEFAULT_JOURNEY_CONFIG } from './journeyTypes';
-import { GestureBuffer } from './gestureBuffer';
-import { GestureDetector } from './gestureDetector';
-import { NavDetector } from './navDetector';
-import { ScreenshotHelper } from './screenshotHelper';
-import { findTarget } from './targetRegistry';
-import { PROTOCOL_VERSION } from '../../debug/protocol';
-
-// ─── Journey Event Names ────────────────────────────────────────────────────
-
-const JOURNEY_EVENTS = {
-    DEBUG_READY: 'journey:debug_ready',
-    CURRENT_SCREEN: 'journey:current_screen',
-    RECORDING_STATE: 'journey:recording_state',
-    STEP_RECORDED: 'journey:step_recorded',
-    JOURNEY_SAVED: 'journey:saved',
-    RUN_STARTED: 'journey:run_started',
-    RUN_STEP_STATUS: 'journey:run_step_status',
-    RUN_FINISHED: 'journey:run_finished',
-    IMAGE_CHUNK: 'journey:image_chunk',
-} as const;
-
-// ─── Journey Manager ────────────────────────────────────────────────────────
-
-export class JourneyManager {
-    private transport: DebugTransport;
-    private config: Required<JourneyConfig>;
-    private gestureBuffer: GestureBuffer;
-    private gestureDetector: GestureDetector;
-    private navDetector: NavDetector;
-    private screenshotHelper: ScreenshotHelper;
-
-    // Recording state
-    private _isRecording = false;
-    private _journeyTempId = '';
-    private _steps: JourneyStep[] = [];
-    private _stepIndex = 0;
-
-    // Running state
-    private _isRunning = false;
-    private _runId = '';
-    private _stopRunFlag = false;
-
-    // Singleton guard
-    private static _instance: JourneyManager | null = null;
-
-    constructor(transport: DebugTransport, config?: JourneyConfig) {
-        this.transport = transport;
-        this.config = {
-            enabled: config?.enabled ?? DEFAULT_JOURNEY_CONFIG.enabled,
-            autoStart: config?.autoStart ?? DEFAULT_JOURNEY_CONFIG.autoStart,
-            screenshots: { ...DEFAULT_JOURNEY_CONFIG.screenshots, ...config?.screenshots },
-            gestures: { ...DEFAULT_JOURNEY_CONFIG.gestures, ...config?.gestures },
-            nav: { ...DEFAULT_JOURNEY_CONFIG.nav, ...config?.nav },
-        };
-
-        this.gestureBuffer = new GestureBuffer(this.config.gestures.bufferSize);
-        this.gestureDetector = new GestureDetector(this.gestureBuffer);
-        this.navDetector = new NavDetector();
-        this.screenshotHelper = new ScreenshotHelper(this.config.screenshots);
-    }
-
-    /** Singleton factory — idempotent */
-    static getInstance(transport: DebugTransport, config?: JourneyConfig): JourneyManager {
-        if (!JourneyManager._instance) {
-            JourneyManager._instance = new JourneyManager(transport, config);
-        }
-        return JourneyManager._instance;
-    }
-
-    /** Reset singleton (for teardown) */
-    static resetInstance(): void {
-        if (JourneyManager._instance) {
-            JourneyManager._instance.teardown();
-            JourneyManager._instance = null;
-        }
-    }
-
-    // ─── Accessors ──────────────────────────────────────────────────────
-
-    get isRecording(): boolean { return this._isRecording; }
-    get isRunning(): boolean { return this._isRunning; }
-    get steps(): JourneyStep[] { return this._steps; }
-    get currentScreen(): string { return this.navDetector.currentScreen; }
-    get detector(): GestureDetector { return this.gestureDetector; }
-    get nav(): NavDetector { return this.navDetector; }
-    get screenshot(): ScreenshotHelper { return this.screenshotHelper; }
-
-    // ─── Initialization ─────────────────────────────────────────────────
-
-    /** Initialize the journey system. Called by ScaleBunDebugRoot on mount. */
-    initialize(rootRef?: any): void {
-        // Install gesture detection
-        this.gestureDetector.install();
-
-        // Install nav detection
-        this.navDetector.install(this.config.nav);
-
-        // Set screenshot root ref
-        if (rootRef) {
-            this.screenshotHelper.setRootRef(rootRef);
-        }
-
-        // Subscribe to nav changes to emit to desktop
-        this.navDetector.onScreenChange((screenName, stack) => {
-            this._emitEvent(JOURNEY_EVENTS.CURRENT_SCREEN, { screenName, stack });
-            // Also push NAV gesture into buffer
-            this.gestureDetector.handleNavigation(screenName);
-        });
-
-        // Emit DEBUG_READY
-        this._emitDebugReady();
-
-        // Auto-start if configured
-        if (this.config.autoStart) {
-            this.startRecording();
-        }
-    }
-
-    // ─── Recording ──────────────────────────────────────────────────────
-
-    startRecording(): void {
-        if (this._isRecording) return;
-
-        this._isRecording = true;
-        this._journeyTempId = this._generateId();
-        this._steps = [];
-        this._stepIndex = 0;
-
-        console.warn('[ScaleBun Journey] Recording started:', this._journeyTempId);
-
-        this._emitEvent(JOURNEY_EVENTS.RECORDING_STATE, {
-            on: true,
-            journeyTempId: this._journeyTempId,
-        });
-    }
-
-    stopRecording(): void {
-        if (!this._isRecording) return;
-
-        this._isRecording = false;
-        console.warn('[ScaleBun Journey] Recording stopped:', this._journeyTempId, `(${this._steps.length} steps)`);
-
-        this._emitEvent(JOURNEY_EVENTS.RECORDING_STATE, {
-            on: false,
-            journeyTempId: this._journeyTempId,
-        });
-    }
-
-    /** Capture a step — matches gesture from buffer + takes screenshot */
-    async captureStep(
-        gestureMode: string,
-        label?: string,
-        note?: string,
-    ): Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }> {
-        if (!this._isRecording) {
-            return { success: false, error: 'Not recording' };
-        }
-
-        const mode = gestureMode as GestureMode;
-
-        // 1. Match gesture from buffer
-        const matchedGesture = this.gestureBuffer.matchRecent(
-            mode,
-            this.config.gestures.matchWindowMs,
-        );
-
-        // 2. Take screenshot
-        const { result: screenshotResult, error: screenshotError } =
-            await this.screenshotHelper.capture();
-
-        // 3. Build step
-        const step: JourneyStep = {
-            stepIndex: this._stepIndex++,
-            gestureType: mode,
-            target: matchedGesture?.target,
-            screenName: this.navDetector.currentScreen,
-            timestamp: Date.now(),
-            label,
-            note,
-        };
-
-        if (!matchedGesture) {
-            step.captureOnly = true;
-            step.captureOnlyReason = `No ${mode} gesture found in last ${this.config.gestures.matchWindowMs}ms`;
-        }
-
-        // 4. Attach screenshot metadata + send image
-        let screenshotId: string | undefined;
-        if (screenshotResult) {
-            screenshotId = this._generateId();
-            step.screenshotId = screenshotId;
-            step.screenshotMeta = {
-                width: screenshotResult.width,
-                height: screenshotResult.height,
-                mime: screenshotResult.mime,
-                byteSize: screenshotResult.byteSize,
-            };
-
-            // Send image as separate event (chunked for large images)
-            this._emitEvent(JOURNEY_EVENTS.IMAGE_CHUNK, {
-                imageId: screenshotId,
-                stepIndex: step.stepIndex,
-                base64: screenshotResult.base64,
-                mime: screenshotResult.mime,
-                width: screenshotResult.width,
-                height: screenshotResult.height,
-                byteSize: screenshotResult.byteSize,
-            });
-        } else if (screenshotError) {
-            step.note = (step.note ? step.note + ' | ' : '') + `Screenshot: ${screenshotError}`;
-        }
-
-        // 5. Store and emit
-        this._steps.push(step);
-
-        this._emitEvent(JOURNEY_EVENTS.STEP_RECORDED, {
-            journeyTempId: this._journeyTempId,
-            step,
-        });
-
-        return {
-            success: true,
-            data: {
-                stepIndex: step.stepIndex,
-                gestureType: step.gestureType,
-                screenName: step.screenName,
-                hasScreenshot: !!screenshotResult,
-                captureOnly: step.captureOnly ?? false,
-                captureOnlyReason: step.captureOnlyReason,
-            },
-        };
-    }
-
-    // ─── Save Journey ───────────────────────────────────────────────────
-
-    async saveJourney(
-        name: string,
-        journeyId?: string,
-    ): Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }> {
-        const id = journeyId || this._generateId();
-
-        let screenWidth = 0, screenHeight = 0, platformOS = 'unknown';
-        try {
-            const RN = require('react-native');
-            const dims = RN.Dimensions.get('window');
-            screenWidth = dims.width;
-            screenHeight = dims.height;
-            platformOS = RN.Platform.OS;
-        } catch { /* no-throw */ }
-
-        const journey: SavedJourney = {
-            journeyId: id,
-            name,
-            createdAt: Date.now(),
-            updatedAt: Date.now(),
-            steps: [...this._steps],
-            metadata: {
-                platform: platformOS,
-                screenWidth,
-                screenHeight,
-                navMode: this.navDetector.navMode,
-            },
-        };
-
-        this._emitEvent(JOURNEY_EVENTS.JOURNEY_SAVED, {
-            journeyId: id,
-            name,
-            journey,
-        });
-
-        return {
-            success: true,
-            data: { journeyId: id, name, stepCount: this._steps.length },
-        };
-    }
-
-    // ─── Run Journey ────────────────────────────────────────────────────
-
-    async runJourney(journeyData: any, options?: any): Promise<void> {
-        if (this._isRunning) return;
-
-        const journey = journeyData as SavedJourney;
-        if (!journey?.steps?.length) return;
-
-        this._isRunning = true;
-        this._stopRunFlag = false;
-        this._runId = this._generateId();
-
-        const speed = options?.speed ?? 1;
-        const stepByStep = options?.stepByStep ?? false;
-        const startTime = Date.now();
-
-        this._emitEvent(JOURNEY_EVENTS.RUN_STARTED, {
-            journeyId: journey.journeyId,
-            runId: this._runId,
-        });
-
-        let passed = 0, failed = 0, skipped = 0;
-
-        for (let i = 0; i < journey.steps.length; i++) {
-            if (this._stopRunFlag) break;
-
-            const step = journey.steps[i];
-            let status: StepStatus = 'PENDING';
-            let reason = '';
-
-            try {
-                if (step.gestureType === 'NAV') {
-                    // Try navigation
-                    status = 'PASS';
-                    reason = 'NAV step acknowledged';
-                } else if (step.target?.testId && findTarget(step.target.testId)) {
-                    // Deterministic execution via registered target
-                    const target = findTarget(step.target.testId)!;
-                    if (step.gestureType === 'TAP' && target.press) {
-                        target.press();
-                        status = 'PASS';
-                    } else if (step.gestureType === 'TYPE' && target.setValue) {
-                        target.setValue('replay-text');
-                        status = 'PASS';
-                    } else if (step.gestureType === 'SCROLL' && target.scrollTo) {
-                        target.scrollTo({ y: 100, animated: true });
-                        status = 'PASS';
-                    } else {
-                        status = 'SKIP';
-                        reason = `SKIPPED_UNRESOLVED: No handler for ${step.gestureType} on target ${step.target.testId}`;
-                    }
-                } else {
-                    // No deterministic target — best-effort
-                    status = 'SKIP';
-                    reason = `SKIPPED_UNRESOLVED: No registered target for step ${i}`;
-                }
-            } catch (e: any) {
-                status = 'FAIL';
-                reason = e?.message || 'Step execution error';
-            }
-
-            // Capture screenshot after step
-            let screenshotId: string | undefined;
-            const { result: ss } = await this.screenshotHelper.capture();
-            if (ss) {
-                screenshotId = this._generateId();
-                this._emitEvent(JOURNEY_EVENTS.IMAGE_CHUNK, {
-                    imageId: screenshotId,
-                    stepIndex: i,
-                    base64: ss.base64,
-                    mime: ss.mime,
-                    width: ss.width,
-                    height: ss.height,
-                    byteSize: ss.byteSize,
-                });
-            }
-
-            // Verify screen name match
-            if (status === 'PASS' && step.screenName !== 'UnknownScreen') {
-                if (this.navDetector.currentScreen !== step.screenName) {
-                    reason = `Screen mismatch: expected ${step.screenName}, got ${this.navDetector.currentScreen}`;
-                    // Don't fail — just note it
-                }
-            }
-
-            if (status === 'PASS') passed++;
-            else if (status === 'FAIL') failed++;
-            else skipped++;
-
-            this._emitEvent(JOURNEY_EVENTS.RUN_STEP_STATUS, {
-                runId: this._runId,
-                stepIndex: i,
-                status,
-                reason: reason || undefined,
-                screenshotId,
-                screenshotMeta: ss ? { width: ss.width, height: ss.height, mime: ss.mime, byteSize: ss.byteSize } : undefined,
-            });
-
-            // Delay between steps (respecting speed)
-            if (i < journey.steps.length - 1 && !stepByStep) {
-                await new Promise(resolve => setTimeout(resolve, 1000 / speed));
-            }
-        }
-
-        const durationMs = Date.now() - startTime;
-
-        this._emitEvent(JOURNEY_EVENTS.RUN_FINISHED, {
-            runId: this._runId,
-            summary: {
-                total: journey.steps.length,
-                passed,
-                failed,
-                skipped,
-                durationMs,
-            },
-        });
-
-        this._isRunning = false;
-    }
-
-    stopRun(): void {
-        this._stopRunFlag = true;
-    }
-
-    // ─── Teardown ───────────────────────────────────────────────────────
-
-    teardown(): void {
-        this.stopRecording();
-        this.stopRun();
-        this.gestureDetector.teardown();
-        this.navDetector.teardown();
-        this.gestureBuffer.clear();
-    }
-
-    // ─── Internal ───────────────────────────────────────────────────────
-
-    private _emitDebugReady(): void {
-        const payload: DebugReadyPayload = {
-            journeyEnabled: this.config.enabled,
-            canScreenshot: this.screenshotHelper.canCapture,
-            navMode: this.navDetector.navMode,
-            sdkVersion: '0.1.0',
-        };
-        this._emitEvent(JOURNEY_EVENTS.DEBUG_READY, payload as unknown as Record<string, unknown>);
-    }
-
-    private _emitEvent(name: string, data: Record<string, unknown>): void {
-        try {
-            const msg = {
-                type: 'event' as const,
-                protocolVersion: PROTOCOL_VERSION,
-                deviceId: this.transport.deviceId,
-                sessionId: this.transport.sessionId,
-                timestamp: Date.now(),
-                sequence: this.transport.nextSequence(),
-                payload: {
-                    id: this._generateId(),
-                    category: 'journey' as const,
-                    name,
-                    data,
-                },
-            };
-            this.transport.send(msg as any);
-        } catch {
-            // No-throw
-        }
-    }
-
-    private _generateId(): string {
-        return `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`;
-    }
-}
+/**
+ * ScaleBun SDK — Journey Manager
+ *
+ * Core orchestrator for journey recording and running.
+ * Coordinates gesture buffer, nav detector, screenshot helper,
+ * and transport to implement the full journey lifecycle.
+ */
+
+import type { DebugTransport } from '../../debug/transport';
+import type {
+    JourneyConfig,
+    JourneyStep,
+    SavedJourney,
+    GestureMode,
+    StepStatus,
+    DebugReadyPayload,
+} from './journeyTypes';
+import { DEFAULT_JOURNEY_CONFIG } from './journeyTypes';
+import { GestureBuffer } from './gestureBuffer';
+import { GestureDetector } from './gestureDetector';
+import { NavDetector } from './navDetector';
+import { ScreenshotHelper } from './screenshotHelper';
+import { findTarget } from './targetRegistry';
+import { PROTOCOL_VERSION } from '../../debug/protocol';
+
+// ─── Journey Event Names ────────────────────────────────────────────────────
+
+const JOURNEY_EVENTS = {
+    DEBUG_READY: 'journey:debug_ready',
+    CURRENT_SCREEN: 'journey:current_screen',
+    RECORDING_STATE: 'journey:recording_state',
+    STEP_RECORDED: 'journey:step_recorded',
+    JOURNEY_SAVED: 'journey:saved',
+    RUN_STARTED: 'journey:run_started',
+    RUN_STEP_STATUS: 'journey:run_step_status',
+    RUN_FINISHED: 'journey:run_finished',
+    IMAGE_CHUNK: 'journey:image_chunk',
+} as const;
+
+// ─── Journey Manager ────────────────────────────────────────────────────────
+
+export class JourneyManager {
+    private transport: DebugTransport;
+    private config: Required<JourneyConfig>;
+    private gestureBuffer: GestureBuffer;
+    private gestureDetector: GestureDetector;
+    private navDetector: NavDetector;
+    private screenshotHelper: ScreenshotHelper;
+
+    // Recording state
+    private _isRecording = false;
+    private _journeyTempId = '';
+    private _steps: JourneyStep[] = [];
+    private _stepIndex = 0;
+
+    // Running state
+    private _isRunning = false;
+    private _runId = '';
+    private _stopRunFlag = false;
+
+    // Singleton guard
+    private static _instance: JourneyManager | null = null;
+
+    constructor(transport: DebugTransport, config?: JourneyConfig) {
+        this.transport = transport;
+        this.config = {
+            enabled: config?.enabled ?? DEFAULT_JOURNEY_CONFIG.enabled,
+            autoStart: config?.autoStart ?? DEFAULT_JOURNEY_CONFIG.autoStart,
+            screenshots: { ...DEFAULT_JOURNEY_CONFIG.screenshots, ...config?.screenshots },
+            gestures: { ...DEFAULT_JOURNEY_CONFIG.gestures, ...config?.gestures },
+            nav: { ...DEFAULT_JOURNEY_CONFIG.nav, ...config?.nav },
+        };
+
+        this.gestureBuffer = new GestureBuffer(this.config.gestures.bufferSize);
+        this.gestureDetector = new GestureDetector(this.gestureBuffer);
+        this.navDetector = new NavDetector();
+        this.screenshotHelper = new ScreenshotHelper(this.config.screenshots);
+    }
+
+    /** Singleton factory — idempotent */
+    static getInstance(transport: DebugTransport, config?: JourneyConfig): JourneyManager {
+        if (!JourneyManager._instance) {
+            JourneyManager._instance = new JourneyManager(transport, config);
+        }
+        return JourneyManager._instance;
+    }
+
+    /** Reset singleton (for teardown) */
+    static resetInstance(): void {
+        if (JourneyManager._instance) {
+            JourneyManager._instance.teardown();
+            JourneyManager._instance = null;
+        }
+    }
+
+    // ─── Accessors ──────────────────────────────────────────────────────
+
+    get isRecording(): boolean { return this._isRecording; }
+    get isRunning(): boolean { return this._isRunning; }
+    get steps(): JourneyStep[] { return this._steps; }
+    get currentScreen(): string { return this.navDetector.currentScreen; }
+    get detector(): GestureDetector { return this.gestureDetector; }
+    get nav(): NavDetector { return this.navDetector; }
+    get screenshot(): ScreenshotHelper { return this.screenshotHelper; }
+
+    // ─── Initialization ─────────────────────────────────────────────────
+
+    /** Initialize the journey system. Called by ScaleBunDebugRoot on mount. */
+    initialize(rootRef?: any): void {
+        // Install gesture detection
+        this.gestureDetector.install();
+
+        // Install nav detection
+        this.navDetector.install(this.config.nav);
+
+        // Set screenshot root ref
+        if (rootRef) {
+            this.screenshotHelper.setRootRef(rootRef);
+        }
+
+        // Subscribe to nav changes to emit to desktop
+        this.navDetector.onScreenChange((screenName, stack) => {
+            this._emitEvent(JOURNEY_EVENTS.CURRENT_SCREEN, { screenName, stack });
+            // Also push NAV gesture into buffer
+            this.gestureDetector.handleNavigation(screenName);
+        });
+
+        // Emit DEBUG_READY
+        this._emitDebugReady();
+
+        // Auto-start if configured
+        if (this.config.autoStart) {
+            this.startRecording();
+        }
+    }
+
+    // ─── Recording ──────────────────────────────────────────────────────
+
+    startRecording(): void {
+        if (this._isRecording) return;
+
+        this._isRecording = true;
+        this._journeyTempId = this._generateId();
+        this._steps = [];
+        this._stepIndex = 0;
+
+        console.warn('[ScaleBun Journey] Recording started:', this._journeyTempId);
+
+        this._emitEvent(JOURNEY_EVENTS.RECORDING_STATE, {
+            on: true,
+            journeyTempId: this._journeyTempId,
+        });
+    }
+
+    stopRecording(): void {
+        if (!this._isRecording) return;
+
+        this._isRecording = false;
+        console.warn('[ScaleBun Journey] Recording stopped:', this._journeyTempId, `(${this._steps.length} steps)`);
+
+        this._emitEvent(JOURNEY_EVENTS.RECORDING_STATE, {
+            on: false,
+            journeyTempId: this._journeyTempId,
+        });
+    }
+
+    /** Capture a step — matches gesture from buffer + takes screenshot */
+    async captureStep(
+        gestureMode: string,
+        label?: string,
+        note?: string,
+    ): Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }> {
+        if (!this._isRecording) {
+            return { success: false, error: 'Not recording' };
+        }
+
+        const mode = gestureMode as GestureMode;
+
+        // 1. Match gesture from buffer
+        const matchedGesture = this.gestureBuffer.matchRecent(
+            mode,
+            this.config.gestures.matchWindowMs,
+        );
+
+        // 2. Take screenshot
+        const { result: screenshotResult, error: screenshotError } =
+            await this.screenshotHelper.capture();
+
+        // 3. Build step
+        const step: JourneyStep = {
+            stepIndex: this._stepIndex++,
+            gestureType: mode,
+            target: matchedGesture?.target,
+            screenName: this.navDetector.currentScreen,
+            timestamp: Date.now(),
+            label,
+            note,
+        };
+
+        if (!matchedGesture) {
+            step.captureOnly = true;
+            step.captureOnlyReason = `No ${mode} gesture found in last ${this.config.gestures.matchWindowMs}ms`;
+        }
+
+        // 4. Attach screenshot metadata + send image
+        let screenshotId: string | undefined;
+        if (screenshotResult) {
+            screenshotId = this._generateId();
+            step.screenshotId = screenshotId;
+            step.screenshotMeta = {
+                width: screenshotResult.width,
+                height: screenshotResult.height,
+                mime: screenshotResult.mime,
+                byteSize: screenshotResult.byteSize,
+            };
+
+            // Send image as separate event (chunked for large images)
+            this._emitEvent(JOURNEY_EVENTS.IMAGE_CHUNK, {
+                imageId: screenshotId,
+                stepIndex: step.stepIndex,
+                base64: screenshotResult.base64,
+                mime: screenshotResult.mime,
+                width: screenshotResult.width,
+                height: screenshotResult.height,
+                byteSize: screenshotResult.byteSize,
+            });
+        } else if (screenshotError) {
+            step.note = (step.note ? step.note + ' | ' : '') + `Screenshot: ${screenshotError}`;
+        }
+
+        // 5. Store and emit
+        this._steps.push(step);
+
+        this._emitEvent(JOURNEY_EVENTS.STEP_RECORDED, {
+            journeyTempId: this._journeyTempId,
+            step,
+        });
+
+        return {
+            success: true,
+            data: {
+                stepIndex: step.stepIndex,
+                gestureType: step.gestureType,
+                screenName: step.screenName,
+                hasScreenshot: !!screenshotResult,
+                captureOnly: step.captureOnly ?? false,
+                captureOnlyReason: step.captureOnlyReason,
+            },
+        };
+    }
+
+    // ─── Save Journey ───────────────────────────────────────────────────
+
+    async saveJourney(
+        name: string,
+        journeyId?: string,
+    ): Promise<{ success: boolean; data?: Record<string, unknown>; error?: string }> {
+        const id = journeyId || this._generateId();
+
+        let screenWidth = 0, screenHeight = 0, platformOS = 'unknown';
+        try {
+            const RN = require('react-native');
+            const dims = RN.Dimensions.get('window');
+            screenWidth = dims.width;
+            screenHeight = dims.height;
+            platformOS = RN.Platform.OS;
+        } catch { /* no-throw */ }
+
+        const journey: SavedJourney = {
+            journeyId: id,
+            name,
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+            steps: [...this._steps],
+            metadata: {
+                platform: platformOS,
+                screenWidth,
+                screenHeight,
+                navMode: this.navDetector.navMode,
+            },
+        };
+
+        this._emitEvent(JOURNEY_EVENTS.JOURNEY_SAVED, {
+            journeyId: id,
+            name,
+            journey,
+        });
+
+        return {
+            success: true,
+            data: { journeyId: id, name, stepCount: this._steps.length },
+        };
+    }
+
+    // ─── Run Journey ────────────────────────────────────────────────────
+
+    async runJourney(journeyData: any, options?: any): Promise<void> {
+        if (this._isRunning) return;
+
+        const journey = journeyData as SavedJourney;
+        if (!journey?.steps?.length) return;
+
+        this._isRunning = true;
+        this._stopRunFlag = false;
+        this._runId = this._generateId();
+
+        const speed = options?.speed ?? 1;
+        const stepByStep = options?.stepByStep ?? false;
+        const startTime = Date.now();
+
+        this._emitEvent(JOURNEY_EVENTS.RUN_STARTED, {
+            journeyId: journey.journeyId,
+            runId: this._runId,
+        });
+
+        let passed = 0, failed = 0, skipped = 0;
+
+        for (let i = 0; i < journey.steps.length; i++) {
+            if (this._stopRunFlag) break;
+
+            const step = journey.steps[i];
+            let status: StepStatus = 'PENDING';
+            let reason = '';
+
+            try {
+                if (step.gestureType === 'NAV') {
+                    // Try navigation
+                    status = 'PASS';
+                    reason = 'NAV step acknowledged';
+                } else if (step.target?.testId && findTarget(step.target.testId)) {
+                    // Deterministic execution via registered target
+                    const target = findTarget(step.target.testId)!;
+                    if (step.gestureType === 'TAP' && target.press) {
+                        target.press();
+                        status = 'PASS';
+                    } else if (step.gestureType === 'TYPE' && target.setValue) {
+                        target.setValue('replay-text');
+                        status = 'PASS';
+                    } else if (step.gestureType === 'SCROLL' && target.scrollTo) {
+                        target.scrollTo({ y: 100, animated: true });
+                        status = 'PASS';
+                    } else {
+                        status = 'SKIP';
+                        reason = `SKIPPED_UNRESOLVED: No handler for ${step.gestureType} on target ${step.target.testId}`;
+                    }
+                } else {
+                    // No deterministic target — best-effort
+                    status = 'SKIP';
+                    reason = `SKIPPED_UNRESOLVED: No registered target for step ${i}`;
+                }
+            } catch (e: any) {
+                status = 'FAIL';
+                reason = e?.message || 'Step execution error';
+            }
+
+            // Capture screenshot after step
+            let screenshotId: string | undefined;
+            const { result: ss } = await this.screenshotHelper.capture();
+            if (ss) {
+                screenshotId = this._generateId();
+                this._emitEvent(JOURNEY_EVENTS.IMAGE_CHUNK, {
+                    imageId: screenshotId,
+                    stepIndex: i,
+                    base64: ss.base64,
+                    mime: ss.mime,
+                    width: ss.width,
+                    height: ss.height,
+                    byteSize: ss.byteSize,
+                });
+            }
+
+            // Verify screen name match
+            if (status === 'PASS' && step.screenName !== 'UnknownScreen') {
+                if (this.navDetector.currentScreen !== step.screenName) {
+                    reason = `Screen mismatch: expected ${step.screenName}, got ${this.navDetector.currentScreen}`;
+                    // Don't fail — just note it
+                }
+            }
+
+            if (status === 'PASS') passed++;
+            else if (status === 'FAIL') failed++;
+            else skipped++;
+
+            this._emitEvent(JOURNEY_EVENTS.RUN_STEP_STATUS, {
+                runId: this._runId,
+                stepIndex: i,
+                status,
+                reason: reason || undefined,
+                screenshotId,
+                screenshotMeta: ss ? { width: ss.width, height: ss.height, mime: ss.mime, byteSize: ss.byteSize } : undefined,
+            });
+
+            // Delay between steps (respecting speed)
+            if (i < journey.steps.length - 1 && !stepByStep) {
+                await new Promise(resolve => setTimeout(resolve, 1000 / speed));
+            }
+        }
+
+        const durationMs = Date.now() - startTime;
+
+        this._emitEvent(JOURNEY_EVENTS.RUN_FINISHED, {
+            runId: this._runId,
+            summary: {
+                total: journey.steps.length,
+                passed,
+                failed,
+                skipped,
+                durationMs,
+            },
+        });
+
+        this._isRunning = false;
+    }
+
+    stopRun(): void {
+        this._stopRunFlag = true;
+    }
+
+    // ─── Teardown ───────────────────────────────────────────────────────
+
+    teardown(): void {
+        this.stopRecording();
+        this.stopRun();
+        this.gestureDetector.teardown();
+        this.navDetector.teardown();
+        this.gestureBuffer.clear();
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    private _emitDebugReady(): void {
+        const payload: DebugReadyPayload = {
+            journeyEnabled: this.config.enabled,
+            canScreenshot: this.screenshotHelper.canCapture,
+            navMode: this.navDetector.navMode,
+            sdkVersion: '0.1.0',
+        };
+        this._emitEvent(JOURNEY_EVENTS.DEBUG_READY, payload as unknown as Record<string, unknown>);
+    }
+
+    private _emitEvent(name: string, data: Record<string, unknown>): void {
+        try {
+            const msg = {
+                type: 'event' as const,
+                protocolVersion: PROTOCOL_VERSION,
+                deviceId: this.transport.deviceId,
+                sessionId: this.transport.sessionId,
+                timestamp: Date.now(),
+                sequence: this.transport.nextSequence(),
+                payload: {
+                    id: this._generateId(),
+                    category: 'journey' as const,
+                    name,
+                    data,
+                },
+            };
+            this.transport.send(msg as any);
+        } catch {
+            // No-throw
+        }
+    }
+
+    private _generateId(): string {
+        return `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`;
+    }
+}