@scalebun-release/react-native 2.5.0

package/src/features/journey/ScaleBunDebugRoot.tsx

@@ -0,0 +1,1045 @@
+/**
+ * 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 { scrollFields } from './nativeScroll';
+import React, {
+    useEffect,
+    useRef,
+    createContext,
+    useContext,
+    type ReactNode,
+} from 'react';
+import { View, NativeEventEmitter, NativeModules } from 'react-native';
+import { resolveTouchTarget, describeTouchTarget, targetIdentity } from './touchTarget';
+import { localPoint, normalizeRect, readRectSync, type NormalizedRect } from './targetGeometry';
+import { nativeTagOf, nearestRecordedOffset } from './scrollContext';
+import { resolvePlatformOS } from '../../core/context/device';
+import {
+    INTERACTION_PROTOCOL_VERSION,
+    generateInteractionId,
+    correlateInteraction,
+    pruneInteractionStarts,
+    type InteractionStartContext,
+} from './interactionProtocol';
+
+// ─── 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);
+
+/**
+ * Floor on how often a UI-state change may request a screenshot.
+ *
+ * One frame per second is far finer than any state a person perceives changing, and far coarser
+ * than a render loop — which is the case that matters, because a host may legitimately declare
+ * state from inside render and an oscillating dimension would otherwise capture continuously.
+ */
+const UI_STATE_CAPTURE_MIN_INTERVAL_MS = 1000;
+
+// ─── 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;
+}
+
+interface TouchStartContext extends InteractionStartContext {
+    locationX?: number;
+    locationY?: number;
+}
+
+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]);
+
+    /**
+     * RN-11 — CAPTURE A FRAME WHEN THE UI CHANGES SHAPE.
+     *
+     * A declared state used to have no picture of its own. Nothing captured on `setUiState`, so a
+     * state's visual existed only if a screenshot happened to be taken for another reason — a
+     * navigation, a timer, or the interaction capture that fires AFTER the touch and therefore
+     * photographs the outcome. A drawer could be recorded as open with no frame showing it open,
+     * or with the frame of the screen that replaced it.
+     *
+     * The native capture reasons are NAVIGATION, MANUAL, INTERACTION and TIMER; none of them means
+     * "the UI changed shape". This routes through the MANUAL path, which is the only one reachable
+     * from JS. A dedicated native reason would let the backend tell a state capture from a
+     * developer-requested one, and that is a native change on both platforms — worth doing, not
+     * doable from here.
+     *
+     * RATE LIMITED, and the limit is not politeness. A screenshot is expensive, and while
+     * `uiState` already collapses redundant declarations, a genuinely oscillating dimension (a
+     * spinner toggling, a live-updating badge) would otherwise capture continuously. One frame per
+     * second is far finer than any state a person can perceive changing and far coarser than a
+     * render loop.
+     *
+     * Requests only; never awaits and never throws. If the session is not recording,
+     * `captureManualFrame` declines and the state simply has no frame — which is the honest
+     * outcome and is exactly what the analytics-only lane already reports elsewhere.
+     */
+    useEffect(() => {
+        let lastCaptureTs = 0;
+        const { onUiStateChange } = require('./uiState');
+        const unsubscribe = onUiStateChange(() => {
+            const now = Date.now();
+            if (now - lastCaptureTs < UI_STATE_CAPTURE_MIN_INTERVAL_MS) return;
+            lastCaptureTs = now;
+            try {
+                const { SessionManager } = require('../session/SessionManager');
+                const sm = SessionManager.getExistingInstance();
+                if (sm && typeof (sm as any).captureManualFrame === 'function') {
+                    /* Fire and forget: the tap that follows must not wait on a screenshot. */
+                    void (sm as any).captureManualFrame();
+                }
+            } catch { /* no-throw */ }
+        });
+        return unsubscribe;
+    }, []);
+
+    // ─── 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 touchStartRef = useRef<TouchStartContext | null>(null);
+    const interactionStartsRef = useRef<TouchStartContext[]>([]);
+    const pendingJsEmitsRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+    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;
+
+                    const nativeOccurredAt =
+                        typeof event.occurredAt === 'number'
+                            ? event.occurredAt
+                            : (typeof event.timestamp === 'number' ? event.timestamp : Date.now()) -
+                              (typeof event.durationMs === 'number' ? event.durationMs : 0);
+                    /**
+                     * RN-6 — correlate, then CONSUME. See interactionProtocol.ts for why
+                     * the join is on time at all, and why a refusal is the important part.
+                     *
+                     * Pruning first is part of the correctness, not tidying: a start older
+                     * than the tolerance can never be paired, but while it sits in the list
+                     * it is still counted by the ambiguity test, so a stale entry can turn a
+                     * clear pairing into a refusal — and the list only grows.
+                     */
+                    pruneInteractionStarts(interactionStartsRef.current, nativeOccurredAt);
+                    const correlation = correlateInteraction(
+                        interactionStartsRef.current,
+                        nativeOccurredAt,
+                    );
+                    const start = correlation.start;
+                    /**
+                     * ONE-TO-ONE. Without removing the matched start, a second native event
+                     * arriving within the window claims the SAME js evidence, so one tap's
+                     * target is stamped onto another tap that never had one — a duplicate
+                     * identity that reads as two genuine interactions on the same control.
+                     */
+                    if (correlation.index >= 0) {
+                        interactionStartsRef.current.splice(correlation.index, 1);
+                    }
+
+                    // Cancel only this physical touch's fallback. A single timer used to cancel a
+                    // previous rapid tap and silently lose it on devices without native tracking.
+                    if (start) {
+                        const pending = pendingJsEmitsRef.current.get(start.interactionId);
+                        if (pending !== undefined) clearTimeout(pending);
+                        pendingJsEmitsRef.current.delete(start.interactionId);
+                    }
+
+                    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', {
+                        interactionId: event.interactionId || start?.interactionId || generateInteractionId(),
+                        interactionProtocol: event.interactionProtocol || INTERACTION_PROTOCOL_VERSION,
+                        occurredAt: nativeOccurredAt,
+                        /**
+                         * RN-6 — THESE FIVE FIELDS ARE THE ONLY ONES THE JOIN CARRIES, AND
+                         * THEREFORE THE ONLY ONES A BAD JOIN CAN FALSIFY.
+                         *
+                         * Coordinates below come from native and are right regardless. So a
+                         * mispairing does not produce visibly broken data: it produces heat
+                         * in the correct position attributed to the wrong control, in the
+                         * wrong UI state, on the wrong screen. Every field is individually
+                         * well-formed and nothing downstream can tell.
+                         *
+                         * When the correlation is not 'exact' they are left UNDEFINED rather
+                         * than filled from a best guess. An interaction with no target is
+                         * honest and visibly incomplete — the accounting lane can count it as
+                         * unplaceable and say why. An interaction with the WRONG target is
+                         * indistinguishable from a correct one and silently corrupts every
+                         * aggregate it enters. `null` is not `0`, and a guess is not a
+                         * measurement.
+                         */
+                        ui: start?.ui,
+                        stateStatus: start?.stateStatus ?? 'not_captured',
+                        target: start?.target,
+                        targetId: start?.targetId,
+                        targetSource: start?.targetSource,
+                        screenName: start?.screenName,
+                        screenSource: start?.screenSource ?? 'none',
+                        targetRect: start?.targetRect,
+                        /**
+                         * RN-15 — WHERE IN THE CONTROL, computed where both halves exist: the
+                         * point comes from the native event and the rect was measured at
+                         * finger-down, in the same capture base. Pairing them here rather than
+                         * downstream stops anything later reaching for a different rect.
+                         */
+                        ...(() => {
+                            const lp = localPoint(
+                                start?.targetRect ?? null,
+                                event.normalizedX,
+                                event.normalizedY,
+                            );
+                            return lp ? { localU: lp.u, localV: lp.v } : {};
+                        })(),
+                        /**
+                         * SCROLL — the JS wrapper's offset when the app uses it, else the NATIVE
+                         * probe's innermost scroll container (read at ACTION_DOWN, no wrapper
+                         * needed). The native half comes from this native event, not from the
+                         * JS join, so it is valid whatever the correlation verdict: it is a
+                         * measurement of where the finger landed, not an attribution.
+                         */
+                        ...scrollFields(start, event),
+                        itemKey: start?.itemKey,
+                        itemIndex: start?.itemIndex,
+                        /**
+                         * The join's own verdict, shipped with the row so it is auditable
+                         * rather than a claim made in a comment. 'ambiguous' and 'none' are
+                         * deliberately distinguished: 'none' means the JS handler never fired
+                         * (a real capture gap on this platform), 'ambiguous' means it fired
+                         * more than once too close together to attribute. Those have
+                         * different fixes, and collapsing them would hide which one is
+                         * actually happening in production.
+                         */
+                        correlation: correlation.outcome,
+                        correlationDeltaMs: correlation.deltaMs,
+                        correlationRunnerUpDeltaMs: correlation.runnerUpDeltaMs,
+                        emitAutomaticAnalytics: start?.emitAutomaticAnalytics ?? captureAutomaticInteractions,
+                        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 */ }
+            for (const timer of pendingJsEmitsRef.current.values()) clearTimeout(timer);
+            pendingJsEmitsRef.current.clear();
+        };
+    }, [captureAutomaticInteractions]);
+
+    // ─── Touch Tracking State ───────────────────────────────────────────
+
+    // 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;
+            const target = resolveTouchTarget(e);
+            let ui: string | undefined;
+            let screenName: string | undefined;
+            /**
+             * RN-8 — WHERE the screen name came from, carried with the interaction.
+             *
+             * Production shows 13.8% of Android interactions with a screen and 0.5% on iOS, and
+             * those figures cannot distinguish three unrelated causes: nothing was instrumented,
+             * a manual beacon was instrumented but never reached interactions, or auto-detection
+             * ran and failed. Each has a different owner. Recording the source turns one
+             * unactionable percentage into three answerable ones.
+             */
+            let screenSource: 'manual' | 'navigation' | 'none' = 'none';
+            let stateInstrumented = false;
+            try {
+                const { uiStateSignature, uiStateInstrumented } = require('./uiState');
+                ui = uiStateSignature();
+                stateInstrumented = uiStateInstrumented();
+            } catch { /* no-throw */ }
+            try {
+                const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
+                const detector = AutoScreenDetector.getInstance();
+                screenName = detector.getCurrentScreen() || undefined;
+                /* Read from the SAME call site as the name, so the two can never describe
+                   different moments — the detector is polled and its answer can change between
+                   two reads a few milliseconds apart. */
+                screenSource = screenName ? detector.getCurrentScreenSource() : 'none';
+            } catch { /* no-throw */ }
+            const start: TouchStartContext = {
+                interactionId: generateInteractionId(),
+                occurredAt: Date.now(),
+                x: touch.pageX,
+                y: touch.pageY,
+                locationX: touch.locationX,
+                locationY: touch.locationY,
+                /**
+                 * RN-1 + RN-2 — the identity that is persisted, and it is now code-derived.
+                 *
+                 * `describeTouchTarget` returns `testID` -> structural path -> component name,
+                 * and never a caption or an accessibilityLabel. Before RN-2 it preferred free
+                 * text, so this line was writing user data ("Pay EGP 1,442", an order row
+                 * labelled with an email address, a contact's name) into the analytics store —
+                 * and, because `target` is an aggregation key, splitting one button into one
+                 * bucket per person at the same time.
+                 *
+                 * `targetId` used to be `target?.testID` alone, which is `undefined` in the
+                 * overwhelming majority of apps — no testIDs authored — so the field the
+                 * backend keys on was empty almost always. It now falls back to the structural
+                 * path, with `targetSource` recording WHICH it got.
+                 */
+                target: describeTouchTarget(target),
+                targetId: targetIdentity(target).id,
+                /**
+                 * WHICH KIND of identity this is, because they are not equally trustworthy: a
+                 * `testID` is a promise from the app's authors that this control is this
+                 * control; a `path` is an inference that breaks when the tree is refactored.
+                 * Without this the accounting lane cannot distinguish "the control had no
+                 * identity" from "the identity is a structural guess", and both would render
+                 * as an equally confident target.
+                 */
+                targetSource: targetIdentity(target).source,
+                /* RN-4 — row identity from the app's own keyExtractor; see touchTarget.ts. */
+                itemKey: target?.itemKey,
+                itemIndex: target?.itemIndex,
+                /**
+                 * RN-13 — the control's rectangle, so `heat ∈ target` is decidable.
+                 *
+                 * Read SYNCHRONOUSLY here, in the same tick as the touch, and normalized against
+                 * the SAME measured root the tap's own coordinates use. Both halves matter:
+                 *
+                 *   - A callback measurement (`measureInWindow`) would resolve after this handler
+                 *     returns, so the rect attached to a tap could be the previous tap's, with
+                 *     nothing afterwards able to tell. `targetGeometry` refuses to guess: it reads
+                 *     now or reports null.
+                 *   - Normalizing against a window size instead of the root view is off by the
+                 *     status bar on most devices, which would read as "the heat is just outside
+                 *     the button" everywhere rather than as a measurement bug.
+                 *
+                 * `measureRoot()` is called first because the cached root rect is populated
+                 * asynchronously at mount; without it the first taps of a session normalize
+                 * against nothing and get a null rect for a reason that has nothing to do with
+                 * the control.
+                 */
+                /**
+                 * RN-3 — WHERE IN THE CONTENT, not just where on the glass.
+                 *
+                 * Two taps at the same screen coordinate one viewport apart are two different
+                 * controls. Without an offset they merge into one hotspot, and the heatmap shows
+                 * heavy engagement at a position where, in content terms, nothing in particular
+                 * is. The offset is also a CACHE dimension — two scroll states of one route must
+                 * not share a backdrop — so its absence corrupts the picture as well as the count.
+                 *
+                 * `ancestors` is innermost-first, so this takes the NEAREST scroller that has a
+                 * recorded position: a tap inside a horizontal carousel belongs to the carousel's
+                 * content, not to how far the page behind it had scrolled.
+                 *
+                 * Null when no ancestor has one — never zero. Zero is a real scroll position (the
+                 * top of a list), and reporting it for "unknown" would place every unmeasured tap
+                 * at the top of its content, indistinguishable from a genuine tap there.
+                 */
+                ...(() => {
+                    const hit = nearestRecordedOffset(
+                        (target?.ancestors ?? []).map((n) => nativeTagOf(n)),
+                    );
+                    return hit
+                        ? { scrollX: hit.x, scrollY: hit.y, scrollSource: 'wrapper' as const }
+                        : { scrollSource: 'none' as const };
+                })(),
+                targetRect: (() => {
+                    measureRoot();
+                    const root = rootRectRef.current;
+                    /* null -> undefined: the context field is optional, and an explicit null would
+                       serialise as a JSON null claiming "measured, and it was nothing". */
+                    return normalizeRect(readRectSync(target?.node), root ? { w: root.w, h: root.h } : null) ?? undefined;
+                })(),
+                screenName,
+                screenSource,
+                ui,
+                stateStatus: ui ? 'captured_nonempty' : stateInstrumented ? 'captured_empty' : 'not_instrumented',
+                emitAutomaticAnalytics: captureAutomaticInteractions,
+            };
+            touchStartRef.current = start;
+            interactionStartsRef.current = interactionStartsRef.current
+                .filter((candidate) => start.occurredAt - candidate.occurredAt < 5000)
+                .concat(start)
+                .slice(-8);
+        } 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).
+            /**
+             * Resolved ONCE, so `target` and `targetId` cannot disagree about the same tap.
+             *
+             * The previous shape called `resolveTouchTarget(e)` inline for `target` while
+             * `targetId` came only from `start` — so on the fallback path (no JS start, or a
+             * refused correlation) the tap carried a description with NO id, and the two fields
+             * were computed from different sources. Anything joining on `targetId` therefore
+             * saw nothing for a tap that visibly had a target.
+             */
+            const freshTarget = start ? null : resolveTouchTarget(e);
+            const tapped = start?.target ?? describeTouchTarget(freshTarget);
+            const identity = start
+                ? { id: start.targetId, source: start.targetSource }
+                : targetIdentity(freshTarget);
+
+            const gestureDetails: any = {
+                target: tapped,
+                interactionId: start?.interactionId ?? generateInteractionId(),
+                interactionProtocol: INTERACTION_PROTOCOL_VERSION,
+                occurredAt: start?.occurredAt ?? Date.now(),
+                ui: start?.ui,
+                stateStatus: start?.stateStatus ?? 'not_captured',
+                targetId: identity.id,
+                targetSource: identity.source,
+                screenName: start?.screenName,
+                screenSource: start?.screenSource ?? 'none',
+                targetRect: start?.targetRect,
+                scrollX: start?.scrollX,
+                scrollY: start?.scrollY,
+                scrollSource: start?.scrollSource ?? 'none',
+                itemKey: start?.itemKey,
+                itemIndex: start?.itemIndex,
+                emitAutomaticAnalytics: start?.emitAutomaticAnalytics ?? captureAutomaticInteractions,
+                x: start?.x ?? touch.pageX,
+                y: start?.y ?? touch.pageY,
+                pageX: start?.x ?? touch.pageX,
+                pageY: start?.y ?? touch.pageY,
+                locationX: start?.locationX ?? touch.locationX,
+                locationY: start?.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, (start?.x ?? touch.pageX) / rootRect.w));
+                const ny = Math.max(0, Math.min(1, (start?.y ?? touch.pageY) / rootRect.h));
+                gestureDetails.normalizedX = nx;
+                gestureDetails.normalizedY = ny;
+                /**
+                 * RN-15 on the JS-fallback lane.
+                 *
+                 * Computed here rather than in the literal above because that is where nx/ny first
+                 * exist. The rect is the SAME one the native lane uses, so one physical tap yields
+                 * the same local position whichever lane captured it — two lanes disagreeing about
+                 * where in a control a tap landed would be worse than neither reporting it.
+                 */
+                const lp = localPoint(start?.targetRect ?? null, nx, ny);
+                if (lp) {
+                    gestureDetails.localU = lp.u;
+                    gestureDetails.localV = lp.v;
+                }
+                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.occurredAt;
+                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';
+                }
+            }
+
+            // 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');
+                    gestureTriggerDetector.recordTap({
+                        x: start?.x ?? touch.pageX,
+                        y: start?.y ?? touch.pageY,
+                        hasTarget: !!(start?.targetId || start?.target),
+                        screen: start?.screenName,
+                    });
+                } 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 600ms 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 };
+                const interactionId = capturedDetails.interactionId as string;
+                const timer = setTimeout(() => {
+                    pendingJsEmitsRef.current.delete(interactionId);
+                    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 */ }
+                    // 600ms, was 200ms. The race this defer exists for happens on the FIRST tap of a
+                    // mount: native isn't confirmed yet, JS emitted at 200ms, then the first native
+                    // event crossed the bridge at ~300-400ms — recording the same tap TWICE, with the
+                    // JS copy missing normalizedX/Y whenever the async root-view measure hadn't
+                    // resolved (an interaction the heatmap cannot place). QA hit exactly this pair.
+                    // The wider defer lets the first native event cancel the JS emission instead; on
+                    // devices with no native tracker at all it merely delays a background emission,
+                    // which nothing user-visible waits on.
+                }, 600);
+                pendingJsEmitsRef.current.set(interactionId, timer);
+            }
+
+            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 */ }
+
+        /**
+         * RN-8 — TELL THE DETECTOR TOO, because interactions read their screen from IT.
+         *
+         * This hook fed SessionManager, PerformanceFeature, ProfilerFeature and JourneyManager
+         * — four consumers — and never `AutoScreenDetector`. But `handleTouchStart` resolves an
+         * interaction's `screenName` from `AutoScreenDetector.getCurrentScreen()`, so a
+         * manually-instrumented app produced perfectly-named SCREEN_VIEW events while every TAP
+         * carried no screen at all. `setManualScreen` existed and was called only by tests.
+         *
+         * That is the whole story for apps the auto-hook cannot help: expo-router, a custom
+         * navigator, anything not `@react-navigation/native`. The documented manual escape hatch
+         * did not reach the one field that partitions every heatmap.
+         *
+         * Requires the last-writer-wins fix in `_currentScreen()` to be useful: under the
+         * previous rule a manual screen was readable for only 2000 ms, so wiring this alone
+         * would have handed interactions a name that expired before most taps happened.
+         */
+        try {
+            const { AutoScreenDetector } = require('../navigation/AutoScreenDetector');
+            AutoScreenDetector.getInstance().setManualScreen(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]);
+}
+
+// ─── 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,
+};