@scalebun/react-native 1.0.2 → 1.0.4

package/src/features/journey/ScaleBunDebugRoot.tsx

@@ -1,726 +1,727 @@
-/**
- * ScaleBun SDK — ScaleBunDebugRoot
- *
- * Root wrapper component that provides:
- * 1. Native screenshot capture wiring (via bridgeAdapter)
- * 2. Navigation detection integration
- * 3. Lightweight gesture capture layer
- * 4. Emits EVENT_DEBUG_READY on mount
- *
- * Usage in demo app:
- *   <ScaleBunDebugRoot>
- *     <App />
- *   </ScaleBunDebugRoot>
- *
- * Also provides:
- *   <ScaleBunScreen name="..." /> — Screen beacon component
- *   useScaleBunScreen("name")    — Screen beacon hook
- *
- * IMPORTANT: All heavy imports (JourneyManager, etc.) are LAZY
- * to avoid pulling in native module dependencies at load time.
- */
-
-import React, {
-    useEffect,
-    useRef,
-    createContext,
-    useContext,
-    type ReactNode,
-} from 'react';
-import { View, NativeEventEmitter, NativeModules } from 'react-native';
-import { emitAutomaticEvent } from '../../analytics/automaticEvents';
-import { resolveTouchTarget, describeTouchTarget } from './touchTarget';
-
-// ─── Lazy imports to avoid native module cascade at load time ────────────────
-// We only import TYPE references at the top level; actual modules are require()'d
-// inside effects or callbacks, which run AFTER the native runtime is initialized.
-
-let _bootstrap: typeof import('../../debug/bootstrap') | null = null;
-function getBootstrap() {
-    if (!_bootstrap) {
-        _bootstrap = require('../../debug/bootstrap');
-    }
-    return _bootstrap;
-}
-
-// ─── Context for Journey Manager ────────────────────────────────────────────
-
-const JourneyContext = createContext<any>(null);
-
-// ─── ScaleBunDebugRoot ───────────────────────────────────────────────────────────
-
-interface ScaleBunDebugRootProps {
-    children: ReactNode;
-    /** Optional: pass a React Navigation ref for auto-detection */
-    navigationRef?: any;
-    /** Internal bridge used by ScaleBunProvider's zero-instrumentation event lane. */
-    captureAutomaticInteractions?: boolean;
-    /** Avoid the legacy-wrapper warning when composed by ScaleBunProvider. */
-    suppressDeprecationWarning?: boolean;
-}
-
-export function ScaleBunDebugRoot({
-    children,
-    navigationRef,
-    captureAutomaticInteractions = false,
-    suppressDeprecationWarning = false,
-}: ScaleBunDebugRootProps) {
-    const rootRef = useRef<View>(null);
-    const managerRef = useRef<any>(null);
-    const initializedRef = useRef(false);
-
-    useEffect(() => {
-        // Guard: only initialize once
-        if (initializedRef.current) return;
-
-        // Deprecation notice (once per mount)
-        if (!suppressDeprecationWarning) {
-            console.warn(
-                '[ScaleBun] <ScaleBunDebugRoot> is no longer required for standard SDK usage. ' +
-                'Use <ScaleBunProvider> for initialization, Engage, automatic events, ' +
-                'touch tracking, and journey features in one wrapper. ' +
-                'See: https://docs.scalebun.com/migration/v2',
-            );
-        }
-
-        // LAZY: load bootstrap module only inside effect (after native runtime ready)
-        let bs: ReturnType<typeof getBootstrap>;
-        try {
-            bs = getBootstrap();
-        } catch (e: any) {
-            console.warn('[ScaleBunDebugRoot] Failed to load bootstrap:', e?.message);
-            return;
-        }
-
-        if (!bs) return;
-
-        const isDebugEnabled = bs.isDebugEnabled();
-        let transport: any = null;
-        let journeyConfig: any = { enabled: false };
-
-        if (!isDebugEnabled) {
-            // This is expected when ScaleBunDebugRoot is composed internally by
-            // ScaleBunProvider. Keep the diagnostic for direct legacy usage, but
-            // do not surface a LogBox warning in normal application mode.
-            if (!suppressDeprecationWarning) {
-                console.warn('[ScaleBunDebugRoot] Debug not enabled — running in production mode');
-            }
-            try { bs._setDebugReady(true); } catch { /* no-throw */ }
-        } else {
-            transport = bs._getTransport();
-            if (!transport) {
-                console.warn('[ScaleBunDebugRoot] No transport — skipping journey init');
-            } else {
-                try {
-                    journeyConfig = bs._getJourneyConfig();
-                } catch {
-                    journeyConfig = { enabled: false };
-                }
-                if (!journeyConfig.enabled) {
-                    console.warn('[ScaleBunDebugRoot] Journey not enabled — passthrough mode');
-                    try { bs._setDebugReady(true); } catch { /* no-throw */ }
-                }
-            }
-        }
-
-        // Wire unified SessionManager (independent of journey)
-        // NOTE: We do NOT auto-start the session here. The session stays idle
-        // until the desktop user explicitly presses Record (sends startSession command).
-        // We only wire the native capture bridge so that when a session IS started,
-        // the capture infrastructure is ready.
-        try {
-            const { SessionManager } = require('../session/SessionManager');
-            const sessionManager = SessionManager.getExistingInstance();
-            if (sessionManager) {
-
-                // Wire native bridge capture — uses PixelCopy (Android) / UIGraphicsImageRenderer (iOS)
-                // via the shared native module. This replaces the previous ViewShot dependency.
-                setTimeout(() => {
-                    try {
-                        const { bridgeAdapter } = require('../replay/bridge/adapters/bridgeAdapter');
-                        const { Dimensions, Platform } = require('react-native');
-
-                        if (bridgeAdapter.isAvailable()) {
-                            // Create a capture function compatible with NativeCaptureFn
-                            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: (Platform.OS === 'ios' ? 'ios' : 'android') as 'android' | 'ios',
-                                    };
-                                } catch {
-                                    return null;
-                                }
-                            };
-
-                            // Inject into SessionManager (hot-swaps if session is active)
-                            if (typeof (sessionManager as any).setNativeCapture === 'function') {
-                                (sessionManager as any).setNativeCapture(nativeBridgeCapture);
-                                console.warn('[ScaleBunDebugRoot] ✅ Native bridge capture wired');
-                            }
-                        } else {
-                            console.warn('[ScaleBunDebugRoot] ⚠️ Native capture module not available');
-                        }
-                    } catch (capErr: any) {
-                        console.warn('[ScaleBunDebugRoot] ⚠️ Native capture wiring failed:', capErr?.message);
-                    }
-                }, 500);
-
-                console.warn('[ScaleBunDebugRoot] ✅ Session wired');
-            }
-        } catch { /* SessionManager may not be available — non-fatal */ }
-
-        // Always wire AutoScreenDetector to React Navigation if a ref is provided.
-        // Register even when ref.current is still null: at mount the
-        // <NavigationContainer> child hasn't attached the ref yet. AutoScreenDetector's
-        // poller retries wiring the 'state' listener once the container populates,
-        // so gating on `ref.current` here would permanently miss the (common) case
-        // where the container mounts after this effect runs.
-        if (navigationRef) {
-            try {
-                const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
-                AutoScreenDetector.getInstance().setNavigationRef(navigationRef);
-            } catch { /* no-throw */ }
-        }
-
-        if (!journeyConfig.enabled || !transport) {
-            return; // Journey disabled — session is wired above independently
-        }
-
-        // LAZY: only now require JourneyManager (which pulls in screenshot/gesture deps)
-        let JourneyManager: any;
-        try {
-            JourneyManager = require('./journeyManager').JourneyManager;
-        } catch (e: any) {
-            console.warn('[ScaleBunDebugRoot] Failed to load JourneyManager:', e?.message);
-            try { bs._setDebugReady(true); } catch { /* no-throw */ }
-            return;
-        }
-
-        // Create journey manager (idempotent singleton)
-        const manager = JourneyManager.getInstance(transport, journeyConfig);
-        managerRef.current = manager;
-
-        // Wire into command registry
-        try {
-            const commands = bs._getCommands();
-            if (commands) {
-                commands.setJourneyManager(manager);
-                commands.setJourneyEnabled(true);
-                commands.setDebugReady(true);
-            }
-        } catch { /* no-throw */ }
-
-        // Initialize with root ref (slight delay to ensure View is mounted)
-        const timer = setTimeout(() => {
-            try {
-                manager.initialize(rootRef.current);
-
-                // If React Navigation ref is available, subscribe
-                if (navigationRef?.current) {
-                    try {
-                        const navContainer = navigationRef.current;
-                        if (navContainer.addListener) {
-                            navContainer.addListener('state', () => {
-                                try {
-                                    const state = navContainer.getRootState();
-                                    manager.nav.handleNavigationStateChange(state);
-                                } catch { /* no-throw */ }
-                            });
-                            // Get initial state
-                            try {
-                                const state = navContainer.getRootState();
-                                if (state) {
-                                    manager.nav.handleNavigationStateChange(state);
-                                }
-                            } catch { /* no-throw */ }
-                        }
-                    } catch { /* no-throw */ }
-                }
-
-                bs._setDebugReady(true);
-                initializedRef.current = true;
-                console.warn('[ScaleBunDebugRoot] ✅ Journey system initialized');
-            } catch (e: any) {
-                console.warn('[ScaleBunDebugRoot] ❌ Initialization error:', e?.message);
-            }
-        }, 200);
-
-        return () => {
-            clearTimeout(timer);
-        };
-    }, [navigationRef]);
-
-    // ─── Native Interaction Listener ────────────────────────────────────
-    // Receives high-confidence ScaleBunNativeInteraction events from the native tracker
-    // and forwards them to SessionManager as USER_ACTION events.
-    const lastNativeTouchTsRef = useRef<number>(0);
-    const nativeTrackingConfirmedRef = useRef<boolean>(false);
-    const pendingJsEmitRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-    useEffect(() => {
-        let subscription: any = null;
-        try {
-            const nativeModule = NativeModules.ReplaySdk;
-            if (!nativeModule) return;
-            const emitter = new NativeEventEmitter(nativeModule);
-            subscription = emitter.addListener('ScaleBunNativeInteraction', (event: any) => {
-                try {
-                    // Record timestamp to suppress duplicate JS touch events
-                    lastNativeTouchTsRef.current = Date.now();
-                    nativeTrackingConfirmedRef.current = true;
-
-                    // Cancel any pending JS emission — native event wins
-                    if (pendingJsEmitRef.current !== null) {
-                        clearTimeout(pendingJsEmitRef.current);
-                        pendingJsEmitRef.current = null;
-                    }
-
-                    const { SessionManager } = require('../session/SessionManager');
-                    const sm = SessionManager.getExistingInstance();
-                    if (!sm || typeof (sm as any).onGestureDetected !== 'function') return;
-
-                    // Diagnostic: capture window dims at event time. Pure
-                    // observability — NOT used for normalization (native path
-                    // already produced normalizedX/Y against the screenshot view).
-                    let _diagWinW: number | undefined;
-                    let _diagWinH: number | undefined;
-                    try {
-                        const { Dimensions } = require('react-native');
-                        const _d = Dimensions.get('window');
-                        _diagWinW = _d.width; _diagWinH = _d.height;
-                    } catch { /* no-throw */ }
-
-                    (sm as any).onGestureDetected(event.gestureType || 'tap', {
-                        x: event.rawX,
-                        y: event.rawY,
-                        // Use the actual native end coords when present, not the down
-                        // coords. The previous endX/endY fell back to rawX/rawY which
-                        // collapsed swipes to a zero-length segment in the dashboard.
-                        endX: event.rawEndX ?? event.rawX,
-                        endY: event.rawEndY ?? event.rawY,
-                        normalizedX: event.normalizedX,
-                        normalizedY: event.normalizedY,
-                        normalizedEndX: event.normalizedEndX,
-                        normalizedEndY: event.normalizedEndY,
-                        viewportWidth: event.screenshotWidthPx,
-                        viewportHeight: event.screenshotHeightPx,
-                        durationMs: event.durationMs,
-                        confidence: 'high',
-                        coordinateSpace: event.coordinateSpace,
-                        safeAreaTop: event.safeAreaTop,
-                        platform: event.platform,
-                        source: 'native-interaction-tracker',
-                        windowWidth: _diagWinW,
-                        windowHeight: _diagWinH,
-                    });
-                } catch { /* no-throw */ }
-            });
-        } catch { /* no-throw */ }
-
-        return () => {
-            try { subscription?.remove(); } catch { /* no-throw */ }
-        };
-    }, []);
-
-    // ─── Touch Tracking State ───────────────────────────────────────────
-    const touchStartRef = useRef<{ x: number; y: number; ts: number } | null>(null);
-
-    // On-screen rect of the root view — the EXACT view the native screenshot
-    // captures. Normalizing pageX/pageY against this rect makes JS-fallback taps
-    // share the screenshot's coordinate origin (fixes vertical status-bar offset).
-    const rootRectRef = useRef<{ x: number; y: number; w: number; h: number } | null>(null);
-    const measureRoot = () => {
-        try {
-            const node: any = rootRef.current;
-            if (node && typeof node.measureInWindow === 'function') {
-                node.measureInWindow((x: number, y: number, w: number, h: number) => {
-                    if (w > 0 && h > 0) rootRectRef.current = { x, y, w, h };
-                });
-            }
-        } catch { /* no-throw */ }
-    };
-
-    // Eagerly measure the root view on mount AND periodically until we have a
-    // non-null reading. measureInWindow is async, so the first tap can otherwise
-    // fall back to Dimensions.get('window') — which excludes system insets and
-    // is ~status-bar fraction smaller than the screenshot region on Android,
-    // pushing the marker upward. Polling stops as soon as the first measurement
-    // succeeds; subsequent taps re-measure inline.
-    useEffect(() => {
-        let attempts = 0;
-        const tryMeasure = () => {
-            measureRoot();
-            attempts += 1;
-            if (rootRectRef.current || attempts >= 10) return;
-            setTimeout(tryMeasure, 100);
-        };
-        const t = setTimeout(tryMeasure, 50);
-        return () => clearTimeout(t);
-    }, []);
-
-    // Gesture capture handlers — feed into SessionManager (unified capture)
-    const handleTouchStart = (e: any) => {
-        try {
-            const touch = e.nativeEvent;
-            touchStartRef.current = { x: touch.pageX, y: touch.pageY, ts: Date.now() };
-        } catch { /* no-throw */ }
-    };
-
-    const handleTouchEnd = (e: any) => {
-        try {
-            const touch = e.nativeEvent;
-
-            // Classify gesture based on touch movement and duration
-            const start = touchStartRef.current;
-            let gestureType = 'tap';
-
-            // Capture window dimensions at touch time for accurate normalization
-            let vpW = 0;
-            let vpH = 0;
-            let screenW = 0;
-            let screenH = 0;
-            let statusBarHeight = 0;
-            try {
-                const { Dimensions, StatusBar, Platform } = require('react-native');
-                const dims = Dimensions.get('window');
-                vpW = dims.width;
-                vpH = dims.height;
-                const scr = Dimensions.get('screen');
-                screenW = scr.width;
-                screenH = scr.height;
-                statusBarHeight = Platform.OS === 'android' ? (StatusBar.currentHeight || 0) : 0;
-            } catch { /* no-throw */ }
-
-            // Re-measure the root view so its on-screen rect is fresh for this tap.
-            measureRoot();
-            const rootRect = rootRectRef.current;
-
-            // WHAT was tapped, resolved from the React fiber on the touch event. Without this the tap
-            // carries only coordinates, so every tap in the app groups into one row per gesture type.
-            // Defensive by construction — returns undefined rather than throwing (see touchTarget.ts).
-            const tapped = describeTouchTarget(resolveTouchTarget(e));
-
-            const gestureDetails: any = {
-                target: tapped,
-                x: touch.pageX,
-                y: touch.pageY,
-                pageX: touch.pageX,
-                pageY: touch.pageY,
-                locationX: touch.locationX,
-                locationY: touch.locationY,
-                viewportWidth: vpW > 0 ? vpW : undefined,
-                viewportHeight: vpH > 0 ? vpH : undefined,
-            };
-
-            // Normalize against the measured root-view SIZE — the exact view the
-            // screenshot captures (Android: R.id.content, iOS: window root).
-            // pageX/pageY are ALREADY relative to the RN root view, which shares the
-            // screenshot's origin. Do NOT subtract rootRect.x/y: on Android
-            // measureInWindow returns rootRect.y = statusBarHeight, so subtracting it
-            // double-counts the status bar and pushes every marker upward.
-            if (rootRect && rootRect.w > 0 && rootRect.h > 0) {
-                const nx = Math.max(0, Math.min(1, touch.pageX / rootRect.w));
-                const ny = Math.max(0, Math.min(1, touch.pageY / rootRect.h));
-                gestureDetails.normalizedX = nx;
-                gestureDetails.normalizedY = ny;
-                gestureDetails.normalizedPrecomputed = true;
-                gestureDetails.viewportWidth = rootRect.w;
-                gestureDetails.viewportHeight = rootRect.h;
-                gestureDetails.coordinateSpace = 'js-root-measured';
-                gestureDetails.rootViewTop = rootRect.y;
-                gestureDetails.rootViewLeft = rootRect.x;
-            }
-            gestureDetails.statusBarHeight = statusBarHeight;
-            gestureDetails.screenWidth = screenW;
-            gestureDetails.screenHeight = screenH;
-            // Diagnostic-only: carry root-view & window dims through to the unified
-            // [TapDiag] log. NOT used for normalization decisions in SessionManager.
-            gestureDetails.windowWidth = vpW > 0 ? vpW : undefined;
-            gestureDetails.windowHeight = vpH > 0 ? vpH : undefined;
-            if (rootRect && rootRect.w > 0 && rootRect.h > 0) {
-                gestureDetails.rootViewWidth = rootRect.w;
-                gestureDetails.rootViewHeight = rootRect.h;
-            }
-            gestureDetails.platform = gestureDetails.platform ?? require('react-native').Platform.OS;
-
-            try {
-                const { logger } = require('../../core/logger/internalLogger');
-                logger?.debug?.(
-                    `[TapAccuracy] platform=js-path raw=(${Math.round(touch.pageX)},${Math.round(touch.pageY)}) ` +
-                    `normalized=(${gestureDetails.normalizedX?.toFixed?.(4)},${gestureDetails.normalizedY?.toFixed?.(4)}) ` +
-                    `rootRect=(${rootRect ? `${Math.round(rootRect.x)},${Math.round(rootRect.y)},${Math.round(rootRect.w)}x${Math.round(rootRect.h)}` : 'none'}) ` +
-                    `statusBar=${statusBarHeight} window=(${vpW}x${vpH}) screen=(${screenW}x${screenH}) space=js-root-measured`
-                );
-            } catch { /* no-throw */ }
-
-            if (start) {
-                const dx = touch.pageX - start.x;
-                const dy = touch.pageY - start.y;
-                const dist = Math.sqrt(dx * dx + dy * dy);
-                const duration = Date.now() - start.ts;
-                gestureDetails.duration = duration;
-
-                if (dist >= 15) {
-                    // Movement gesture: swipe or scroll
-                    gestureDetails.endX = touch.pageX;
-                    gestureDetails.endY = touch.pageY;
-                    
-                    if (Math.abs(dy) > Math.abs(dx)) {
-                        gestureType = 'scroll';
-                        gestureDetails.direction = dy > 0 ? 'down' : 'up';
-                        gestureDetails.distance = Math.abs(dy);
-                    } else {
-                        gestureType = 'swipe';
-                        gestureDetails.direction = dx > 0 ? 'right' : 'left';
-                        gestureDetails.distance = Math.abs(dx);
-                    }
-                } else if (duration > 500) {
-                    gestureType = 'long_press';
-                }
-            }
-
-            const targetInfo = _extractTarget(e);
-            gestureDetails.target = targetInfo?.testId || targetInfo?.accessibilityLabel;
-
-            if (captureAutomaticInteractions) {
-                let screen: string | undefined;
-                try {
-                    const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
-                    screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
-                } catch { /* no-throw */ }
-                emitAutomaticEvent('element_interacted', {
-                    gesture_type: gestureType,
-                    screen_name: screen,
-                    // testID/nativeID is an author-controlled stable identifier.
-                    // Accessibility labels and rendered text are deliberately omitted.
-                    target_id: targetInfo?.testId,
-                    normalized_x: gestureDetails.normalizedX,
-                    normalized_y: gestureDetails.normalizedY,
-                    direction: gestureDetails.direction,
-                    duration_ms: gestureDetails.duration,
-                });
-            }
-
-            // Feed the Engage gesture detector (rage_tap / dead_tap) — only committed
-            // taps, not swipes/scrolls/long-presses. Pure JS, cross-platform; emits the
-            // unified `$gesture` signal the engage trigger engine listens for.
-            if (gestureType === 'tap') {
-                try {
-                    const { gestureTriggerDetector } = require('../engage/gestureTriggerDetector');
-                    let screen: string | undefined;
-                    try {
-                        const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
-                        screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
-                    } catch { /* no-throw */ }
-                    gestureTriggerDetector.recordTap({
-                        x: touch.pageX,
-                        y: touch.pageY,
-                        hasTarget: !!(targetInfo?.testId || targetInfo?.accessibilityLabel),
-                        screen,
-                    });
-                } catch { /* no-throw */ }
-            }
-
-            // Emit gesture event to SessionManager for desktop-controlled recording.
-            // Native tracker produces high-confidence coords; JS is a fallback only.
-            //
-            // Race condition fix: the JS onTouchEnd fires BEFORE the native event
-            // crosses the bridge. Without guarding, the pipeline's 100ms dedup window
-            // drops the native event and keeps the JS-estimated coords (which can be
-            // wrong when measureInWindow hasn't resolved or the base differs from the
-            // screenshot capture view). Three-tier suppression:
-            //   1. Native confirmed active → skip JS entirely (native handles all touches)
-            //   2. Native event within 300ms → skip (existing dedup)
-            //   3. First touch (native not yet confirmed) → defer 200ms to let native arrive
-            const sinceNative = Date.now() - lastNativeTouchTsRef.current;
-            if (nativeTrackingConfirmedRef.current) {
-                // Native tracker is active — skip JS path entirely
-            } else if (sinceNative <= 300) {
-                // Native event arrived recently — skip (dedup)
-            } else {
-                // Native not yet confirmed — defer emission to give native time to arrive.
-                // If native fires during the delay, it cancels this pending emit.
-                const capturedType = gestureType;
-                const capturedDetails = { ...gestureDetails };
-                if (pendingJsEmitRef.current !== null) {
-                    clearTimeout(pendingJsEmitRef.current);
-                }
-                pendingJsEmitRef.current = setTimeout(() => {
-                    pendingJsEmitRef.current = null;
-                    if (nativeTrackingConfirmedRef.current) return;
-                    try {
-                        const { SessionManager } = require('../session/SessionManager');
-                        const sm = SessionManager.getExistingInstance();
-                        if (sm && (sm as any).onGestureDetected) {
-                            (sm as any).onGestureDetected(capturedType, {
-                                ...capturedDetails,
-                                confidence: 'medium',
-                                source: 'js-touch-handler',
-                            });
-                        }
-                    } catch { /* no-throw */ }
-                }, 200);
-            }
-
-            touchStartRef.current = null;
-        } catch { /* no-throw */ }
-    };
-
-    return (
-        <View
-            ref={rootRef}
-            style={styles.root}
-            collapsable={false}
-            onStartShouldSetResponderCapture={() => {
-                return false; // Don't consume — just observe
-            }}
-            onMoveShouldSetResponderCapture={() => false}
-            onTouchStart={handleTouchStart}
-            onTouchEnd={handleTouchEnd}
-        >
-            <JourneyContext.Provider value={managerRef.current}>
-                {children}
-            </JourneyContext.Provider>
-        </View>
-    );
-}
-
-// ─── ScaleBunScreen Beacon ───────────────────────────────────────────────────────
-
-interface ScaleBunScreenProps {
-    name: string;
-}
-
-/**
- * Screen beacon component — registers the current screen name.
- * Place it at the top of each screen component:
- *   <ScaleBunScreen name="HomeScreen" />
- */
-export function ScaleBunScreen({ name }: ScaleBunScreenProps) {
-    useScaleBunScreen(name);
-    return null; // Invisible beacon
-}
-
-/**
- * Screen beacon hook — registers the current screen name.
- * Use in screen components:
- *   useScaleBunScreen("HomeScreen");
- */
-export function useScaleBunScreen(name: string): void {
-    const manager = useContext(JourneyContext);
-
-    useEffect(() => {
-        // === CANONICAL SCREEN_VIEW SOURCE ===
-        // This hook is the SOLE source of SCREEN_VIEW session events.
-        // SessionManager.onScreenChange() emits the canonical SCREEN_VIEW
-        // event into the unified pipeline. No other code path emits SCREEN_VIEW.
-        //
-        // JourneyManager.nav.setScreen() is NOT a session event — it only
-        // records the current screen name for gesture step labeling context.
-
-        // Feed SessionManager first (canonical SCREEN_VIEW)
-        try {
-            const { SessionManager } = require('../session/SessionManager');
-            const sm = SessionManager.getExistingInstance();
-            // Always call onScreenChange — SessionManager.onScreenChange() has
-            // its own `if (!this.active) return` guard that correctly evaluates
-            // at call time. We must NOT gate here because useEffect only runs at
-            // mount/name-change, not when isActive changes. Gating here causes
-            // Record-after-mount to permanently miss screen registrations.
-            if (sm && (sm as any).onScreenChange) {
-                (sm as any).onScreenChange(name);
-            }
-        } catch { /* no-throw */ }
-
-        // Feed PerformanceFeature (screen context for perf metrics)
-        // NOTE: Only sets screen identity. Does NOT call markScreenLoadStart/End.
-        // AutoScreenLoadCollector handles timing independently via rAF + InteractionManager.
-        try {
-            const bs = getBootstrap();
-            const perfFeature = bs?.getPerformanceFeature?.();
-            if (perfFeature) {
-                perfFeature.setCurrentScreen(name);
-            }
-        } catch { /* no-throw */ }
-
-        // Feed ProfilerFeature (screen context for profiler samples)
-        // This sets screenKey on all subsequent profiler samples,
-        // enabling screen visit extraction and per-screen correlation on desktop.
-        try {
-            const bs = getBootstrap();
-            const profilerFeature = bs?.getProfilerFeature?.();
-            if (profilerFeature) {
-                profilerFeature.setCurrentScreen(name);
-            }
-        } catch { /* no-throw */ }
-
-        // NOTE: Auto-capture for performance preview is triggered from
-        // PerformanceFeature.autoScreenLoadCollector callback, NOT here.
-        // useScaleBunScreen uses developer-specified names (e.g. 'HomeScreen')
-        // while perf metrics use React Navigation route names (e.g. 'HomeMain').
-        // Triggering capture here would save screenshots under the wrong key.
-
-        // Feed JourneyManager (gesture context only, NOT a session event)
-        if (!manager) {
-            try {
-                const bs = getBootstrap();
-                const transport = bs?._getTransport();
-                if (transport && bs?._isJourneyEnabled()) {
-                    const JM = require('./journeyManager').JourneyManager;
-                    const fallback = JM.getInstance(transport);
-                    fallback.nav.setScreen(name);
-                }
-            } catch { /* no-throw */ }
-            return;
-        }
-        try {
-            manager.nav.setScreen(name);
-        } catch { /* no-throw */ }
-    }, [name, manager]);
-}
-
-// ─── Helpers ────────────────────────────────────────────────────────────────
-
-function _extractTarget(e: any): { testId?: string; accessibilityLabel?: string; text?: string } | undefined {
-    try {
-        const target = e?.target;
-        if (!target) return undefined;
-
-        // React Native nativeEvent target properties
-        const props = target._internalFiberInstanceHandleDEV?.memoizedProps ?? {};
-        return {
-            testId: props.testID || props.nativeID || undefined,
-            accessibilityLabel: props.accessibilityLabel || undefined,
-            text: undefined,
-        };
-    } catch {
-        return undefined;
-    }
-}
-
-// ─── Styles ─────────────────────────────────────────────────────────────────
-// IMPORTANT: Do NOT use StyleSheet.create() here.
-// In RN 0.84 bridgeless mode, StyleSheet.create() calls
-// PixelRatio.roundToNearestPixel() which accesses DeviceInfo TurboModule.
-// At module-load time, the TurboModule runtime isn't ready yet → crash.
-// Plain objects work identically for simple styles.
-
-const styles = {
-    root: {
-        flex: 1,
-    } as const,
-};
+/**
+ * ScaleBun SDK — ScaleBunDebugRoot
+ *
+ * Root wrapper component that provides:
+ * 1. Native screenshot capture wiring (via bridgeAdapter)
+ * 2. Navigation detection integration
+ * 3. Lightweight gesture capture layer
+ * 4. Emits EVENT_DEBUG_READY on mount
+ *
+ * Usage in demo app:
+ *   <ScaleBunDebugRoot>
+ *     <App />
+ *   </ScaleBunDebugRoot>
+ *
+ * Also provides:
+ *   <ScaleBunScreen name="..." /> — Screen beacon component
+ *   useScaleBunScreen("name")    — Screen beacon hook
+ *
+ * IMPORTANT: All heavy imports (JourneyManager, etc.) are LAZY
+ * to avoid pulling in native module dependencies at load time.
+ */
+
+import React, {
+    useEffect,
+    useRef,
+    createContext,
+    useContext,
+    type ReactNode,
+} from 'react';
+import { View, NativeEventEmitter, NativeModules } from 'react-native';
+import { emitAutomaticEvent } from '../../analytics/automaticEvents';
+import { resolveTouchTarget, describeTouchTarget } from './touchTarget';
+import { resolvePlatformOS } from '../../core/context/device';
+
+// ─── Lazy imports to avoid native module cascade at load time ────────────────
+// We only import TYPE references at the top level; actual modules are require()'d
+// inside effects or callbacks, which run AFTER the native runtime is initialized.
+
+let _bootstrap: typeof import('../../debug/bootstrap') | null = null;
+function getBootstrap() {
+    if (!_bootstrap) {
+        _bootstrap = require('../../debug/bootstrap');
+    }
+    return _bootstrap;
+}
+
+// ─── Context for Journey Manager ────────────────────────────────────────────
+
+const JourneyContext = createContext<any>(null);
+
+// ─── ScaleBunDebugRoot ───────────────────────────────────────────────────────────
+
+interface ScaleBunDebugRootProps {
+    children: ReactNode;
+    /** Optional: pass a React Navigation ref for auto-detection */
+    navigationRef?: any;
+    /** Internal bridge used by ScaleBunProvider's zero-instrumentation event lane. */
+    captureAutomaticInteractions?: boolean;
+    /** Avoid the legacy-wrapper warning when composed by ScaleBunProvider. */
+    suppressDeprecationWarning?: boolean;
+}
+
+export function ScaleBunDebugRoot({
+    children,
+    navigationRef,
+    captureAutomaticInteractions = false,
+    suppressDeprecationWarning = false,
+}: ScaleBunDebugRootProps) {
+    const rootRef = useRef<View>(null);
+    const managerRef = useRef<any>(null);
+    const initializedRef = useRef(false);
+
+    useEffect(() => {
+        // Guard: only initialize once
+        if (initializedRef.current) return;
+
+        // Deprecation notice (once per mount)
+        if (!suppressDeprecationWarning) {
+            console.warn(
+                '[ScaleBun] <ScaleBunDebugRoot> is no longer required for standard SDK usage. ' +
+                'Use <ScaleBunProvider> for initialization, Engage, automatic events, ' +
+                'touch tracking, and journey features in one wrapper. ' +
+                'See: https://docs.scalebun.com/migration/v2',
+            );
+        }
+
+        // LAZY: load bootstrap module only inside effect (after native runtime ready)
+        let bs: ReturnType<typeof getBootstrap>;
+        try {
+            bs = getBootstrap();
+        } catch (e: any) {
+            console.warn('[ScaleBunDebugRoot] Failed to load bootstrap:', e?.message);
+            return;
+        }
+
+        if (!bs) return;
+
+        const isDebugEnabled = bs.isDebugEnabled();
+        let transport: any = null;
+        let journeyConfig: any = { enabled: false };
+
+        if (!isDebugEnabled) {
+            // This is expected when ScaleBunDebugRoot is composed internally by
+            // ScaleBunProvider. Keep the diagnostic for direct legacy usage, but
+            // do not surface a LogBox warning in normal application mode.
+            if (!suppressDeprecationWarning) {
+                console.warn('[ScaleBunDebugRoot] Debug not enabled — running in production mode');
+            }
+            try { bs._setDebugReady(true); } catch { /* no-throw */ }
+        } else {
+            transport = bs._getTransport();
+            if (!transport) {
+                console.warn('[ScaleBunDebugRoot] No transport — skipping journey init');
+            } else {
+                try {
+                    journeyConfig = bs._getJourneyConfig();
+                } catch {
+                    journeyConfig = { enabled: false };
+                }
+                if (!journeyConfig.enabled) {
+                    console.warn('[ScaleBunDebugRoot] Journey not enabled — passthrough mode');
+                    try { bs._setDebugReady(true); } catch { /* no-throw */ }
+                }
+            }
+        }
+
+        // Wire unified SessionManager (independent of journey)
+        // NOTE: We do NOT auto-start the session here. The session stays idle
+        // until the desktop user explicitly presses Record (sends startSession command).
+        // We only wire the native capture bridge so that when a session IS started,
+        // the capture infrastructure is ready.
+        try {
+            const { SessionManager } = require('../session/SessionManager');
+            const sessionManager = SessionManager.getExistingInstance();
+            if (sessionManager) {
+
+                // Wire native bridge capture — uses PixelCopy (Android) / UIGraphicsImageRenderer (iOS)
+                // via the shared native module. This replaces the previous ViewShot dependency.
+                setTimeout(() => {
+                    try {
+                        const { bridgeAdapter } = require('../replay/bridge/adapters/bridgeAdapter');
+                        const { Dimensions, Platform } = require('react-native');
+
+                        if (bridgeAdapter.isAvailable()) {
+                            // Create a capture function compatible with NativeCaptureFn
+                            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;
+                                }
+                            };
+
+                            // Inject into SessionManager (hot-swaps if session is active)
+                            if (typeof (sessionManager as any).setNativeCapture === 'function') {
+                                (sessionManager as any).setNativeCapture(nativeBridgeCapture);
+                                console.warn('[ScaleBunDebugRoot] ✅ Native bridge capture wired');
+                            }
+                        } else {
+                            console.warn('[ScaleBunDebugRoot] ⚠️ Native capture module not available');
+                        }
+                    } catch (capErr: any) {
+                        console.warn('[ScaleBunDebugRoot] ⚠️ Native capture wiring failed:', capErr?.message);
+                    }
+                }, 500);
+
+                console.warn('[ScaleBunDebugRoot] ✅ Session wired');
+            }
+        } catch { /* SessionManager may not be available — non-fatal */ }
+
+        // Always wire AutoScreenDetector to React Navigation if a ref is provided.
+        // Register even when ref.current is still null: at mount the
+        // <NavigationContainer> child hasn't attached the ref yet. AutoScreenDetector's
+        // poller retries wiring the 'state' listener once the container populates,
+        // so gating on `ref.current` here would permanently miss the (common) case
+        // where the container mounts after this effect runs.
+        if (navigationRef) {
+            try {
+                const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
+                AutoScreenDetector.getInstance().setNavigationRef(navigationRef);
+            } catch { /* no-throw */ }
+        }
+
+        if (!journeyConfig.enabled || !transport) {
+            return; // Journey disabled — session is wired above independently
+        }
+
+        // LAZY: only now require JourneyManager (which pulls in screenshot/gesture deps)
+        let JourneyManager: any;
+        try {
+            JourneyManager = require('./journeyManager').JourneyManager;
+        } catch (e: any) {
+            console.warn('[ScaleBunDebugRoot] Failed to load JourneyManager:', e?.message);
+            try { bs._setDebugReady(true); } catch { /* no-throw */ }
+            return;
+        }
+
+        // Create journey manager (idempotent singleton)
+        const manager = JourneyManager.getInstance(transport, journeyConfig);
+        managerRef.current = manager;
+
+        // Wire into command registry
+        try {
+            const commands = bs._getCommands();
+            if (commands) {
+                commands.setJourneyManager(manager);
+                commands.setJourneyEnabled(true);
+                commands.setDebugReady(true);
+            }
+        } catch { /* no-throw */ }
+
+        // Initialize with root ref (slight delay to ensure View is mounted)
+        const timer = setTimeout(() => {
+            try {
+                manager.initialize(rootRef.current);
+
+                // If React Navigation ref is available, subscribe
+                if (navigationRef?.current) {
+                    try {
+                        const navContainer = navigationRef.current;
+                        if (navContainer.addListener) {
+                            navContainer.addListener('state', () => {
+                                try {
+                                    const state = navContainer.getRootState();
+                                    manager.nav.handleNavigationStateChange(state);
+                                } catch { /* no-throw */ }
+                            });
+                            // Get initial state
+                            try {
+                                const state = navContainer.getRootState();
+                                if (state) {
+                                    manager.nav.handleNavigationStateChange(state);
+                                }
+                            } catch { /* no-throw */ }
+                        }
+                    } catch { /* no-throw */ }
+                }
+
+                bs._setDebugReady(true);
+                initializedRef.current = true;
+                console.warn('[ScaleBunDebugRoot] ✅ Journey system initialized');
+            } catch (e: any) {
+                console.warn('[ScaleBunDebugRoot] ❌ Initialization error:', e?.message);
+            }
+        }, 200);
+
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [navigationRef]);
+
+    // ─── Native Interaction Listener ────────────────────────────────────
+    // Receives high-confidence ScaleBunNativeInteraction events from the native tracker
+    // and forwards them to SessionManager as USER_ACTION events.
+    const lastNativeTouchTsRef = useRef<number>(0);
+    const nativeTrackingConfirmedRef = useRef<boolean>(false);
+    const pendingJsEmitRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    useEffect(() => {
+        let subscription: any = null;
+        try {
+            const nativeModule = NativeModules.ReplaySdk;
+            if (!nativeModule) return;
+            const emitter = new NativeEventEmitter(nativeModule);
+            subscription = emitter.addListener('ScaleBunNativeInteraction', (event: any) => {
+                try {
+                    // Record timestamp to suppress duplicate JS touch events
+                    lastNativeTouchTsRef.current = Date.now();
+                    nativeTrackingConfirmedRef.current = true;
+
+                    // Cancel any pending JS emission — native event wins
+                    if (pendingJsEmitRef.current !== null) {
+                        clearTimeout(pendingJsEmitRef.current);
+                        pendingJsEmitRef.current = null;
+                    }
+
+                    const { SessionManager } = require('../session/SessionManager');
+                    const sm = SessionManager.getExistingInstance();
+                    if (!sm || typeof (sm as any).onGestureDetected !== 'function') return;
+
+                    // Diagnostic: capture window dims at event time. Pure
+                    // observability — NOT used for normalization (native path
+                    // already produced normalizedX/Y against the screenshot view).
+                    let _diagWinW: number | undefined;
+                    let _diagWinH: number | undefined;
+                    try {
+                        const { Dimensions } = require('react-native');
+                        const _d = Dimensions.get('window');
+                        _diagWinW = _d.width; _diagWinH = _d.height;
+                    } catch { /* no-throw */ }
+
+                    (sm as any).onGestureDetected(event.gestureType || 'tap', {
+                        x: event.rawX,
+                        y: event.rawY,
+                        // Use the actual native end coords when present, not the down
+                        // coords. The previous endX/endY fell back to rawX/rawY which
+                        // collapsed swipes to a zero-length segment in the dashboard.
+                        endX: event.rawEndX ?? event.rawX,
+                        endY: event.rawEndY ?? event.rawY,
+                        normalizedX: event.normalizedX,
+                        normalizedY: event.normalizedY,
+                        normalizedEndX: event.normalizedEndX,
+                        normalizedEndY: event.normalizedEndY,
+                        viewportWidth: event.screenshotWidthPx,
+                        viewportHeight: event.screenshotHeightPx,
+                        durationMs: event.durationMs,
+                        confidence: 'high',
+                        coordinateSpace: event.coordinateSpace,
+                        safeAreaTop: event.safeAreaTop,
+                        platform: event.platform,
+                        source: 'native-interaction-tracker',
+                        windowWidth: _diagWinW,
+                        windowHeight: _diagWinH,
+                    });
+                } catch { /* no-throw */ }
+            });
+        } catch { /* no-throw */ }
+
+        return () => {
+            try { subscription?.remove(); } catch { /* no-throw */ }
+        };
+    }, []);
+
+    // ─── Touch Tracking State ───────────────────────────────────────────
+    const touchStartRef = useRef<{ x: number; y: number; ts: number } | null>(null);
+
+    // On-screen rect of the root view — the EXACT view the native screenshot
+    // captures. Normalizing pageX/pageY against this rect makes JS-fallback taps
+    // share the screenshot's coordinate origin (fixes vertical status-bar offset).
+    const rootRectRef = useRef<{ x: number; y: number; w: number; h: number } | null>(null);
+    const measureRoot = () => {
+        try {
+            const node: any = rootRef.current;
+            if (node && typeof node.measureInWindow === 'function') {
+                node.measureInWindow((x: number, y: number, w: number, h: number) => {
+                    if (w > 0 && h > 0) rootRectRef.current = { x, y, w, h };
+                });
+            }
+        } catch { /* no-throw */ }
+    };
+
+    // Eagerly measure the root view on mount AND periodically until we have a
+    // non-null reading. measureInWindow is async, so the first tap can otherwise
+    // fall back to Dimensions.get('window') — which excludes system insets and
+    // is ~status-bar fraction smaller than the screenshot region on Android,
+    // pushing the marker upward. Polling stops as soon as the first measurement
+    // succeeds; subsequent taps re-measure inline.
+    useEffect(() => {
+        let attempts = 0;
+        const tryMeasure = () => {
+            measureRoot();
+            attempts += 1;
+            if (rootRectRef.current || attempts >= 10) return;
+            setTimeout(tryMeasure, 100);
+        };
+        const t = setTimeout(tryMeasure, 50);
+        return () => clearTimeout(t);
+    }, []);
+
+    // Gesture capture handlers — feed into SessionManager (unified capture)
+    const handleTouchStart = (e: any) => {
+        try {
+            const touch = e.nativeEvent;
+            touchStartRef.current = { x: touch.pageX, y: touch.pageY, ts: Date.now() };
+        } catch { /* no-throw */ }
+    };
+
+    const handleTouchEnd = (e: any) => {
+        try {
+            const touch = e.nativeEvent;
+
+            // Classify gesture based on touch movement and duration
+            const start = touchStartRef.current;
+            let gestureType = 'tap';
+
+            // Capture window dimensions at touch time for accurate normalization
+            let vpW = 0;
+            let vpH = 0;
+            let screenW = 0;
+            let screenH = 0;
+            let statusBarHeight = 0;
+            try {
+                const { Dimensions, StatusBar, Platform } = require('react-native');
+                const dims = Dimensions.get('window');
+                vpW = dims.width;
+                vpH = dims.height;
+                const scr = Dimensions.get('screen');
+                screenW = scr.width;
+                screenH = scr.height;
+                statusBarHeight = Platform.OS === 'android' ? (StatusBar.currentHeight || 0) : 0;
+            } catch { /* no-throw */ }
+
+            // Re-measure the root view so its on-screen rect is fresh for this tap.
+            measureRoot();
+            const rootRect = rootRectRef.current;
+
+            // WHAT was tapped, resolved from the React fiber on the touch event. Without this the tap
+            // carries only coordinates, so every tap in the app groups into one row per gesture type.
+            // Defensive by construction — returns undefined rather than throwing (see touchTarget.ts).
+            const tapped = describeTouchTarget(resolveTouchTarget(e));
+
+            const gestureDetails: any = {
+                target: tapped,
+                x: touch.pageX,
+                y: touch.pageY,
+                pageX: touch.pageX,
+                pageY: touch.pageY,
+                locationX: touch.locationX,
+                locationY: touch.locationY,
+                viewportWidth: vpW > 0 ? vpW : undefined,
+                viewportHeight: vpH > 0 ? vpH : undefined,
+            };
+
+            // Normalize against the measured root-view SIZE — the exact view the
+            // screenshot captures (Android: R.id.content, iOS: window root).
+            // pageX/pageY are ALREADY relative to the RN root view, which shares the
+            // screenshot's origin. Do NOT subtract rootRect.x/y: on Android
+            // measureInWindow returns rootRect.y = statusBarHeight, so subtracting it
+            // double-counts the status bar and pushes every marker upward.
+            if (rootRect && rootRect.w > 0 && rootRect.h > 0) {
+                const nx = Math.max(0, Math.min(1, touch.pageX / rootRect.w));
+                const ny = Math.max(0, Math.min(1, touch.pageY / rootRect.h));
+                gestureDetails.normalizedX = nx;
+                gestureDetails.normalizedY = ny;
+                gestureDetails.normalizedPrecomputed = true;
+                gestureDetails.viewportWidth = rootRect.w;
+                gestureDetails.viewportHeight = rootRect.h;
+                gestureDetails.coordinateSpace = 'js-root-measured';
+                gestureDetails.rootViewTop = rootRect.y;
+                gestureDetails.rootViewLeft = rootRect.x;
+            }
+            gestureDetails.statusBarHeight = statusBarHeight;
+            gestureDetails.screenWidth = screenW;
+            gestureDetails.screenHeight = screenH;
+            // Diagnostic-only: carry root-view & window dims through to the unified
+            // [TapDiag] log. NOT used for normalization decisions in SessionManager.
+            gestureDetails.windowWidth = vpW > 0 ? vpW : undefined;
+            gestureDetails.windowHeight = vpH > 0 ? vpH : undefined;
+            if (rootRect && rootRect.w > 0 && rootRect.h > 0) {
+                gestureDetails.rootViewWidth = rootRect.w;
+                gestureDetails.rootViewHeight = rootRect.h;
+            }
+            gestureDetails.platform = gestureDetails.platform ?? require('react-native').Platform.OS;
+
+            try {
+                const { logger } = require('../../core/logger/internalLogger');
+                logger?.debug?.(
+                    `[TapAccuracy] platform=js-path raw=(${Math.round(touch.pageX)},${Math.round(touch.pageY)}) ` +
+                    `normalized=(${gestureDetails.normalizedX?.toFixed?.(4)},${gestureDetails.normalizedY?.toFixed?.(4)}) ` +
+                    `rootRect=(${rootRect ? `${Math.round(rootRect.x)},${Math.round(rootRect.y)},${Math.round(rootRect.w)}x${Math.round(rootRect.h)}` : 'none'}) ` +
+                    `statusBar=${statusBarHeight} window=(${vpW}x${vpH}) screen=(${screenW}x${screenH}) space=js-root-measured`
+                );
+            } catch { /* no-throw */ }
+
+            if (start) {
+                const dx = touch.pageX - start.x;
+                const dy = touch.pageY - start.y;
+                const dist = Math.sqrt(dx * dx + dy * dy);
+                const duration = Date.now() - start.ts;
+                gestureDetails.duration = duration;
+
+                if (dist >= 15) {
+                    // Movement gesture: swipe or scroll
+                    gestureDetails.endX = touch.pageX;
+                    gestureDetails.endY = touch.pageY;
+                    
+                    if (Math.abs(dy) > Math.abs(dx)) {
+                        gestureType = 'scroll';
+                        gestureDetails.direction = dy > 0 ? 'down' : 'up';
+                        gestureDetails.distance = Math.abs(dy);
+                    } else {
+                        gestureType = 'swipe';
+                        gestureDetails.direction = dx > 0 ? 'right' : 'left';
+                        gestureDetails.distance = Math.abs(dx);
+                    }
+                } else if (duration > 500) {
+                    gestureType = 'long_press';
+                }
+            }
+
+            const targetInfo = _extractTarget(e);
+            gestureDetails.target = targetInfo?.testId || targetInfo?.accessibilityLabel;
+
+            if (captureAutomaticInteractions) {
+                let screen: string | undefined;
+                try {
+                    const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
+                    screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
+                } catch { /* no-throw */ }
+                emitAutomaticEvent('element_interacted', {
+                    gesture_type: gestureType,
+                    screen_name: screen,
+                    // testID/nativeID is an author-controlled stable identifier.
+                    // Accessibility labels and rendered text are deliberately omitted.
+                    target_id: targetInfo?.testId,
+                    normalized_x: gestureDetails.normalizedX,
+                    normalized_y: gestureDetails.normalizedY,
+                    direction: gestureDetails.direction,
+                    duration_ms: gestureDetails.duration,
+                });
+            }
+
+            // Feed the Engage gesture detector (rage_tap / dead_tap) — only committed
+            // taps, not swipes/scrolls/long-presses. Pure JS, cross-platform; emits the
+            // unified `$gesture` signal the engage trigger engine listens for.
+            if (gestureType === 'tap') {
+                try {
+                    const { gestureTriggerDetector } = require('../engage/gestureTriggerDetector');
+                    let screen: string | undefined;
+                    try {
+                        const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
+                        screen = AutoScreenDetector.getInstance().getCurrentScreen() || undefined;
+                    } catch { /* no-throw */ }
+                    gestureTriggerDetector.recordTap({
+                        x: touch.pageX,
+                        y: touch.pageY,
+                        hasTarget: !!(targetInfo?.testId || targetInfo?.accessibilityLabel),
+                        screen,
+                    });
+                } catch { /* no-throw */ }
+            }
+
+            // Emit gesture event to SessionManager for desktop-controlled recording.
+            // Native tracker produces high-confidence coords; JS is a fallback only.
+            //
+            // Race condition fix: the JS onTouchEnd fires BEFORE the native event
+            // crosses the bridge. Without guarding, the pipeline's 100ms dedup window
+            // drops the native event and keeps the JS-estimated coords (which can be
+            // wrong when measureInWindow hasn't resolved or the base differs from the
+            // screenshot capture view). Three-tier suppression:
+            //   1. Native confirmed active → skip JS entirely (native handles all touches)
+            //   2. Native event within 300ms → skip (existing dedup)
+            //   3. First touch (native not yet confirmed) → defer 200ms to let native arrive
+            const sinceNative = Date.now() - lastNativeTouchTsRef.current;
+            if (nativeTrackingConfirmedRef.current) {
+                // Native tracker is active — skip JS path entirely
+            } else if (sinceNative <= 300) {
+                // Native event arrived recently — skip (dedup)
+            } else {
+                // Native not yet confirmed — defer emission to give native time to arrive.
+                // If native fires during the delay, it cancels this pending emit.
+                const capturedType = gestureType;
+                const capturedDetails = { ...gestureDetails };
+                if (pendingJsEmitRef.current !== null) {
+                    clearTimeout(pendingJsEmitRef.current);
+                }
+                pendingJsEmitRef.current = setTimeout(() => {
+                    pendingJsEmitRef.current = null;
+                    if (nativeTrackingConfirmedRef.current) return;
+                    try {
+                        const { SessionManager } = require('../session/SessionManager');
+                        const sm = SessionManager.getExistingInstance();
+                        if (sm && (sm as any).onGestureDetected) {
+                            (sm as any).onGestureDetected(capturedType, {
+                                ...capturedDetails,
+                                confidence: 'medium',
+                                source: 'js-touch-handler',
+                            });
+                        }
+                    } catch { /* no-throw */ }
+                }, 200);
+            }
+
+            touchStartRef.current = null;
+        } catch { /* no-throw */ }
+    };
+
+    return (
+        <View
+            ref={rootRef}
+            style={styles.root}
+            collapsable={false}
+            onStartShouldSetResponderCapture={() => {
+                return false; // Don't consume — just observe
+            }}
+            onMoveShouldSetResponderCapture={() => false}
+            onTouchStart={handleTouchStart}
+            onTouchEnd={handleTouchEnd}
+        >
+            <JourneyContext.Provider value={managerRef.current}>
+                {children}
+            </JourneyContext.Provider>
+        </View>
+    );
+}
+
+// ─── ScaleBunScreen Beacon ───────────────────────────────────────────────────────
+
+interface ScaleBunScreenProps {
+    name: string;
+}
+
+/**
+ * Screen beacon component — registers the current screen name.
+ * Place it at the top of each screen component:
+ *   <ScaleBunScreen name="HomeScreen" />
+ */
+export function ScaleBunScreen({ name }: ScaleBunScreenProps) {
+    useScaleBunScreen(name);
+    return null; // Invisible beacon
+}
+
+/**
+ * Screen beacon hook — registers the current screen name.
+ * Use in screen components:
+ *   useScaleBunScreen("HomeScreen");
+ */
+export function useScaleBunScreen(name: string): void {
+    const manager = useContext(JourneyContext);
+
+    useEffect(() => {
+        // === CANONICAL SCREEN_VIEW SOURCE ===
+        // This hook is the SOLE source of SCREEN_VIEW session events.
+        // SessionManager.onScreenChange() emits the canonical SCREEN_VIEW
+        // event into the unified pipeline. No other code path emits SCREEN_VIEW.
+        //
+        // JourneyManager.nav.setScreen() is NOT a session event — it only
+        // records the current screen name for gesture step labeling context.
+
+        // Feed SessionManager first (canonical SCREEN_VIEW)
+        try {
+            const { SessionManager } = require('../session/SessionManager');
+            const sm = SessionManager.getExistingInstance();
+            // Always call onScreenChange — SessionManager.onScreenChange() has
+            // its own `if (!this.active) return` guard that correctly evaluates
+            // at call time. We must NOT gate here because useEffect only runs at
+            // mount/name-change, not when isActive changes. Gating here causes
+            // Record-after-mount to permanently miss screen registrations.
+            if (sm && (sm as any).onScreenChange) {
+                (sm as any).onScreenChange(name);
+            }
+        } catch { /* no-throw */ }
+
+        // Feed PerformanceFeature (screen context for perf metrics)
+        // NOTE: Only sets screen identity. Does NOT call markScreenLoadStart/End.
+        // AutoScreenLoadCollector handles timing independently via rAF + InteractionManager.
+        try {
+            const bs = getBootstrap();
+            const perfFeature = bs?.getPerformanceFeature?.();
+            if (perfFeature) {
+                perfFeature.setCurrentScreen(name);
+            }
+        } catch { /* no-throw */ }
+
+        // Feed ProfilerFeature (screen context for profiler samples)
+        // This sets screenKey on all subsequent profiler samples,
+        // enabling screen visit extraction and per-screen correlation on desktop.
+        try {
+            const bs = getBootstrap();
+            const profilerFeature = bs?.getProfilerFeature?.();
+            if (profilerFeature) {
+                profilerFeature.setCurrentScreen(name);
+            }
+        } catch { /* no-throw */ }
+
+        // NOTE: Auto-capture for performance preview is triggered from
+        // PerformanceFeature.autoScreenLoadCollector callback, NOT here.
+        // useScaleBunScreen uses developer-specified names (e.g. 'HomeScreen')
+        // while perf metrics use React Navigation route names (e.g. 'HomeMain').
+        // Triggering capture here would save screenshots under the wrong key.
+
+        // Feed JourneyManager (gesture context only, NOT a session event)
+        if (!manager) {
+            try {
+                const bs = getBootstrap();
+                const transport = bs?._getTransport();
+                if (transport && bs?._isJourneyEnabled()) {
+                    const JM = require('./journeyManager').JourneyManager;
+                    const fallback = JM.getInstance(transport);
+                    fallback.nav.setScreen(name);
+                }
+            } catch { /* no-throw */ }
+            return;
+        }
+        try {
+            manager.nav.setScreen(name);
+        } catch { /* no-throw */ }
+    }, [name, manager]);
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function _extractTarget(e: any): { testId?: string; accessibilityLabel?: string; text?: string } | undefined {
+    try {
+        const target = e?.target;
+        if (!target) return undefined;
+
+        // React Native nativeEvent target properties
+        const props = target._internalFiberInstanceHandleDEV?.memoizedProps ?? {};
+        return {
+            testId: props.testID || props.nativeID || undefined,
+            accessibilityLabel: props.accessibilityLabel || undefined,
+            text: undefined,
+        };
+    } catch {
+        return undefined;
+    }
+}
+
+// ─── Styles ─────────────────────────────────────────────────────────────────
+// IMPORTANT: Do NOT use StyleSheet.create() here.
+// In RN 0.84 bridgeless mode, StyleSheet.create() calls
+// PixelRatio.roundToNearestPixel() which accesses DeviceInfo TurboModule.
+// At module-load time, the TurboModule runtime isn't ready yet → crash.
+// Plain objects work identically for simple styles.
+
+const styles = {
+    root: {
+        flex: 1,
+    } as const,
+};