@scalebun/react-native 1.0.2 → 1.0.3

package/src/features/navigation/AutoScreenDetector.ts

@@ -1,448 +1,503 @@
-/**
- * ScaleBun SDK — Auto Screen Detector
- *
- * Automatically detects the current screen/route from React Navigation
- * WITHOUT requiring per-screen `<ScaleBunScreen>` beacons.
- *
- * Precedence rules (deterministic, no oscillation):
- *   1. Manual override via `useScaleBunScreen()` / `<ScaleBunScreen>` ALWAYS wins
- *   2. Explicit navigation ref (via `setNavigationRef()`) wins over heuristics
- *   3. Heuristic polling (best-effort) is the last fallback
- *
- * The detector is idempotent, no-throw, safe to call multiple times,
- * and safe when navigation is unavailable.
- */
-
-import { logger } from '../../core/logger/internalLogger';
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-interface ScreenChangeCallback {
-    (screenName: string, source: 'manual' | 'navRef' | 'heuristic'): void;
-}
-
-interface NavigationState {
-    index?: number;
-    routes?: Array<{
-        name: string;
-        state?: NavigationState;
-        params?: Record<string, unknown>;
-    }>;
-}
-
-// ─── Singleton State ────────────────────────────────────────────────────────
-
-let _instance: AutoScreenDetector | null = null;
-
-/**
- * AutoScreenDetector — singleton that auto-detects the active screen.
- *
- * Does NOT use undocumented `(global).__reactNavigation` as a primary mechanism.
- * Instead:
- *   1. `setNavigationRef(ref)` — explicit, reliable, developer-provided
- *   2. Heuristic navigation state polling — best-effort fallback using
- *      common React Navigation patterns
- *   3. Manual `useScaleBunScreen()` always overrides — via `setManualScreen()`
- */
-export class AutoScreenDetector {
-    private _listeners: ScreenChangeCallback[] = [];
-    private _manualScreen: string | null = null;
-    private _manualScreenTs = 0;
-    private _autoScreen: string | null = null;
-    private _navigationRef: any = null;
-    private _navListenerRemover: (() => void) | null = null;
-    private _navListenerWired = false;
-    private _heuristicTimer: ReturnType<typeof setInterval> | null = null;
-    private _started = false;
-    private _lastEmittedScreen: string | null = null;
-    private _navDebounceTimer: ReturnType<typeof setTimeout> | null = null;
-
-    /** Cooldown: after manual screen is set, suppress auto-detection for this duration */
-    private static MANUAL_COOLDOWN_MS = 2000;
-    /** Heuristic polling interval */
-    private static HEURISTIC_POLL_MS = 1500;
-
-    static getInstance(): AutoScreenDetector {
-        if (!_instance) {
-            _instance = new AutoScreenDetector();
-        }
-        return _instance;
-    }
-
-    // ─── Registration ───────────────────────────────────────────────────
-
-    /** Register a callback for screen changes */
-    onScreenChange(cb: ScreenChangeCallback): () => void {
-        this._listeners.push(cb);
-        // Return unsubscribe function
-        return () => {
-            this._listeners = this._listeners.filter(l => l !== cb);
-        };
-    }
-
-    // ─── Manual Override (highest priority) ────────────────────────────
-
-    /**
-     * Set screen name from manual instrumentation (`useScaleBunScreen` / `<ScaleBunScreen>`).
-     * This ALWAYS takes precedence over auto-detection.
-     */
-    setManualScreen(name: string): void {
-        try {
-            this._manualScreen = name;
-            this._manualScreenTs = Date.now();
-            this._emitScreenChange(name, 'manual');
-        } catch { /* no-throw */ }
-    }
-
-    /**
-     * Clear manual override. Auto-detection may resume after cooldown.
-     */
-    clearManualScreen(): void {
-        this._manualScreen = null;
-    }
-
-    /**
-     * Set screen name from native lifecycle detection (Android Activity / iOS ViewController).
-     * Lower priority than manual override — yields when manual is active.
-     * Use this when native code auto-detects the current screen without JS navigation.
-     */
-    setNativeScreen(name: string): void {
-        try {
-            if (!name || name === 'unknown') return;
-            if (this.isManualScreenActive()) return;
-            if (name !== this._autoScreen) {
-                this._autoScreen = name;
-                this._emitScreenChange(name, 'heuristic');
-            }
-        } catch { /* no-throw */ }
-    }
-
-    /**
-     * Check if a manual screen is currently active.
-     * Used by auto-detection to yield to manual overrides.
-     */
-    isManualScreenActive(): boolean {
-        if (!this._manualScreen) return false;
-        // Within cooldown period — manual wins
-        return (Date.now() - this._manualScreenTs) < AutoScreenDetector.MANUAL_COOLDOWN_MS;
-    }
-
-    // ─── Explicit Navigation Ref (second priority) ─────────────────────
-
-    /**
-     * Set an explicit React Navigation container ref.
-     * This is the most reliable auto-detection mechanism.
-     *
-     * @param ref - A React Navigation `NavigationContainerRef`
-     */
-    setNavigationRef(ref: any): void {
-        try {
-            if (!ref) return;
-            this._navigationRef = ref;
-            this._wireNavigationListener();
-            logger.debug('[AutoScreenDetector] Navigation ref set');
-        } catch (err: any) {
-            logger.warn('[AutoScreenDetector] setNavigationRef failed:', err?.message);
-        }
-    }
-
-    private _wireNavigationListener(): void {
-        try {
-            // Clean up previous listener
-            if (this._navListenerRemover) {
-                this._navListenerRemover();
-                this._navListenerRemover = null;
-            }
-            this._navListenerWired = false;
-
-            const navRef = this._navigationRef;
-            const container = navRef?.current ?? navRef;
-            // Container may be null when the ref came from useNavigationContainerRef()
-            // /createNavigationContainerRef() before <NavigationContainer> mounted.
-            // Leave _navListenerWired false so the poller retries once it populates.
-            if (!container || typeof container.addListener !== 'function') return;
-            this._navListenerWired = true;
-
-            // Wire state change listener (documented React Navigation API)
-            if (typeof container.addListener === 'function') {
-                const remover = container.addListener('state', () => {
-                    try {
-                        if (this.isManualScreenActive()) return;
-                        // Debounce: React Navigation fires multiple 'state' events
-                        // during a single transition (one per nested navigator).
-                        // Wait for the final settled state before emitting.
-                        if (this._navDebounceTimer) clearTimeout(this._navDebounceTimer);
-                        this._navDebounceTimer = setTimeout(() => {
-                            try {
-                                const state = typeof container.getRootState === 'function'
-                                    ? container.getRootState()
-                                    : null;
-                                if (state) {
-                                    const screen = this._extractActiveRoute(state);
-                                    if (screen && screen !== this._autoScreen) {
-                                        this._autoScreen = screen;
-                                        this._emitScreenChange(screen, 'navRef');
-                                    }
-                                }
-                            } catch { /* no-throw */ }
-                        }, 30);
-                    } catch { /* no-throw */ }
-                });
-                this._navListenerRemover = typeof remover === 'function'
-                    ? remover
-                    : remover?.remove ? () => remover.remove() : null;
-            }
-
-            // Get initial state immediately
-            if (typeof container.getRootState === 'function') {
-                const state = container.getRootState();
-                if (state) {
-                    const screen = this._extractActiveRoute(state);
-                    if (screen) {
-                        this._autoScreen = screen;
-                        this._emitScreenChange(screen, 'navRef');
-                    }
-                }
-            }
-        } catch { /* no-throw */ }
-    }
-
-    // ─── Heuristic Fallback (lowest priority) ──────────────────────────
-
-    /**
-     * Start the heuristic polling fallback.
-     * This periodically checks for React Navigation state via common patterns.
-     * Only fires if no manual screen or explicit nav ref is active.
-     */
-    private _startHeuristicPolling(): void {
-        if (this._heuristicTimer) return; // Idempotent
-
-        this._heuristicTimer = setInterval(() => {
-            try {
-                // If manual or navRef is providing screens, skip heuristic
-                if (this.isManualScreenActive()) return;
-                if (this._navigationRef) {
-                    // A ref was captured (e.g. via the React Navigation auto-hook) but
-                    // its container may have been null at wire time. Retry until the
-                    // documented 'state' listener attaches, then defer to it.
-                    if (!this._navListenerWired) this._wireNavigationListener();
-                    return;
-                }
-
-                // Best-effort: try to find the navigation container
-                // via the commonly-used global that React Navigation
-                // attaches when linking is configured
-                const navContainer = this._findNavigationContainer();
-                if (navContainer) {
-                    const state = typeof navContainer.getRootState === 'function'
-                        ? navContainer.getRootState()
-                        : null;
-                    if (state) {
-                        const screen = this._extractActiveRoute(state);
-                        if (screen && screen !== this._autoScreen) {
-                            this._autoScreen = screen;
-                            this._emitScreenChange(screen, 'heuristic');
-                        }
-                    }
-                }
-            } catch { /* no-throw — heuristic is best-effort */ }
-        }, AutoScreenDetector.HEURISTIC_POLL_MS);
-    }
-
-    /**
-     * Best-effort: try to locate a navigation container.
-     * Checks common global locations, returns null if none found.
-     */
-    private _findNavigationContainer(): any {
-        try {
-            // Check for React Navigation linking config container
-            const g = globalThis as any;
-
-            // Pattern 1: __reactNavigationRef (set by some navigation setups)
-            if (g.__reactNavigationRef?.current) {
-                return g.__reactNavigationRef.current;
-            }
-
-            // Pattern 2: Check if there's a registered navigation container
-            // via @react-navigation/native's NavigationContainer internal state
-            if (g.__scalebun_navigationRef?.current) {
-                return g.__scalebun_navigationRef.current;
-            }
-
-            return null;
-        } catch {
-            return null;
-        }
-    }
-
-    // ─── Route Extraction ───────────────────────────────────────────────
-
-    /**
-     * Extract the active route name from a navigation state tree.
-     * Handles nested navigators by walking to the deepest active route.
-     */
-    private _extractActiveRoute(state: NavigationState | null | undefined): string | null {
-        try {
-            if (!state?.routes || typeof state.index !== 'number') return null;
-
-            const activeRoute = state.routes[state.index];
-            if (!activeRoute) return null;
-
-            // If this route has nested state, recurse to find the deepest active route
-            if (activeRoute.state?.routes && typeof activeRoute.state.index === 'number') {
-                const nested = this._extractActiveRoute(activeRoute.state);
-                if (nested) return nested;
-            }
-
-            return activeRoute.name || null;
-        } catch {
-            return null;
-        }
-    }
-
-    // ─── Lifecycle ──────────────────────────────────────────────────────
-
-    /** Start auto-detection (idempotent) */
-    start(): void {
-        if (this._started) return;
-        this._started = true;
-        this._autoHookReactNavigation();
-        this._startHeuristicPolling();
-        logger.debug('[AutoScreenDetector] Started');
-    }
-
-    /**
-     * Zero-config React Navigation hook.
-     *
-     * Patches the three public entry points apps use to obtain a navigation
-     * container so the SDK captures the container ref WITHOUT the app wiring
-     * `setNavigationRef()` / `<ScaleBunDebugRoot navigationRef>`. Best-effort and
-     * no-throw: if `@react-navigation/native` isn't installed, or an entry point
-     * is missing, we silently skip and the heuristic poller remains the fallback.
-     *
-     * Once any container ref is captured, `setNavigationRef()` wires the
-     * documented `'state'` listener and the existing pipeline emits screen
-     * changes (→ SessionManager SCREEN_VIEW + navigation-triggered frames).
-     */
-    private _autoHookReactNavigation(): void {
-        try {
-            const reactNav = require('@react-navigation/native');
-            if (!reactNav || reactNav.__scalebunAutoHooked) return;
-
-            const detector = this;
-            const register = (ref: any) => {
-                try {
-                    const container = ref?.current ?? ref;
-                    if (container && typeof container.getRootState === 'function') {
-                        detector.setNavigationRef(ref?.current ? ref : { current: container });
-                    }
-                } catch { /* no-throw */ }
-            };
-
-            // 1. NavigationContainer — broadest hook. Wrap so any container that
-            //    mounts registers its ref, regardless of whether the app passes one.
-            if (typeof reactNav.NavigationContainer === 'function') {
-                const Original = reactNav.NavigationContainer;
-                const React = require('react');
-                const Wrapped = React.forwardRef((props: any, forwardedRef: any) => {
-                    const innerRef = React.useRef(null);
-                    const registeredRef = React.useRef(null);
-                    const setRef = (node: any) => {
-                        innerRef.current = node;
-                        if (typeof forwardedRef === 'function') forwardedRef(node);
-                        else if (forwardedRef) forwardedRef.current = node;
-                    };
-                    React.useEffect(() => {
-                        // Register once per distinct container instance.
-                        if (innerRef.current && innerRef.current !== registeredRef.current) {
-                            registeredRef.current = innerRef.current;
-                            register(innerRef);
-                        }
-                    });
-                    return React.createElement(Original, { ...props, ref: setRef });
-                });
-                (Wrapped as any).displayName = 'ScaleBunNavigationContainer';
-                try { reactNav.NavigationContainer = Wrapped; } catch { /* frozen export — skip */ }
-            }
-
-            // 2. createNavigationContainerRef — apps that build the ref manually.
-            if (typeof reactNav.createNavigationContainerRef === 'function') {
-                const originalCreate = reactNav.createNavigationContainerRef;
-                const patchedCreate = (...args: any[]) => {
-                    const ref = originalCreate(...args);
-                    try { detector.setNavigationRef(ref); } catch { /* no-throw */ }
-                    return ref;
-                };
-                try { reactNav.createNavigationContainerRef = patchedCreate; } catch { /* skip */ }
-            }
-
-            // 3. useNavigationContainerRef — hook variant of (2).
-            if (typeof reactNav.useNavigationContainerRef === 'function') {
-                const originalHook = reactNav.useNavigationContainerRef;
-                const patchedHook = (...args: any[]) => {
-                    const ref = originalHook(...args);
-                    try { detector.setNavigationRef(ref); } catch { /* no-throw */ }
-                    return ref;
-                };
-                try { reactNav.useNavigationContainerRef = patchedHook; } catch { /* skip */ }
-            }
-
-            try { reactNav.__scalebunAutoHooked = true; } catch { /* frozen — best-effort */ }
-            logger.debug('[AutoScreenDetector] React Navigation auto-hook installed');
-        } catch { /* @react-navigation/native not installed — heuristic remains fallback */ }
-    }
-
-    /** Stop auto-detection and clean up */
-    stop(): void {
-        if (this._navDebounceTimer) {
-            clearTimeout(this._navDebounceTimer);
-            this._navDebounceTimer = null;
-        }
-        if (this._heuristicTimer) {
-            clearInterval(this._heuristicTimer);
-            this._heuristicTimer = null;
-        }
-        if (this._navListenerRemover) {
-            this._navListenerRemover();
-            this._navListenerRemover = null;
-        }
-        this._navListenerWired = false;
-        this._started = false;
-        this._lastEmittedScreen = null;
-        logger.debug('[AutoScreenDetector] Stopped');
-    }
-
-    /** Teardown completely (reset singleton) */
-    teardown(): void {
-        this.stop();
-        this._listeners = [];
-        this._manualScreen = null;
-        this._autoScreen = null;
-        this._navigationRef = null;
-        _instance = null;
-    }
-
-    /** Get the current best-known screen name */
-    getCurrentScreen(): string | null {
-        if (this._manualScreen && this.isManualScreenActive()) {
-            return this._manualScreen;
-        }
-        return this._autoScreen;
-    }
-
-    // ─── Internal ───────────────────────────────────────────────────────
-
-    private _emitScreenChange(name: string, source: 'manual' | 'navRef' | 'heuristic'): void {
-        try {
-            // Deduplicate: don't emit if the screen is the same as last emitted
-            if (name === this._lastEmittedScreen) return;
-            this._lastEmittedScreen = name;
-
-            for (const cb of this._listeners) {
-                try {
-                    cb(name, source);
-                } catch { /* no-throw per-listener */ }
-            }
-        } catch { /* no-throw */ }
-    }
-}
+/**
+ * ScaleBun SDK — Auto Screen Detector
+ *
+ * Automatically detects the current screen/route from React Navigation
+ * WITHOUT requiring per-screen `<ScaleBunScreen>` beacons.
+ *
+ * Precedence rules (deterministic, no oscillation):
+ *   1. Manual override via `useScaleBunScreen()` / `<ScaleBunScreen>` ALWAYS wins
+ *   2. Explicit navigation ref (via `setNavigationRef()`) wins over heuristics
+ *   3. Heuristic polling (best-effort) is the last fallback
+ *
+ * The detector is idempotent, no-throw, safe to call multiple times,
+ * and safe when navigation is unavailable.
+ */
+
+import { logger } from '../../core/logger/internalLogger';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface ScreenChangeCallback {
+    (screenName: string, source: 'manual' | 'navRef' | 'heuristic'): void;
+}
+
+interface NavigationState {
+    index?: number;
+    routes?: Array<{
+        name: string;
+        state?: NavigationState;
+        params?: Record<string, unknown>;
+    }>;
+}
+
+// ─── Singleton State ────────────────────────────────────────────────────────
+
+let _instance: AutoScreenDetector | null = null;
+
+/**
+ * AutoScreenDetector — singleton that auto-detects the active screen.
+ *
+ * Does NOT use undocumented `(global).__reactNavigation` as a primary mechanism.
+ * Instead:
+ *   1. `setNavigationRef(ref)` — explicit, reliable, developer-provided
+ *   2. Heuristic navigation state polling — best-effort fallback using
+ *      common React Navigation patterns
+ *   3. Manual `useScaleBunScreen()` always overrides — via `setManualScreen()`
+ */
+export class AutoScreenDetector {
+    private _listeners: ScreenChangeCallback[] = [];
+    private _manualScreen: string | null = null;
+    private _manualScreenTs = 0;
+    private _autoScreen: string | null = null;
+    private _navigationRef: any = null;
+    private _navListenerRemover: (() => void) | null = null;
+    private _navListenerWired = false;
+    private _heuristicTimer: ReturnType<typeof setInterval> | null = null;
+    private _started = false;
+    private _lastEmittedScreen: string | null = null;
+    private _navDebounceTimer: ReturnType<typeof setTimeout> | null = null;
+    /** Whether the React Navigation exports were actually replaced — see _autoHookReactNavigation. */
+    private _autoHookInstalled = false;
+
+    /** Cooldown: after manual screen is set, suppress auto-detection for this duration */
+    private static MANUAL_COOLDOWN_MS = 2000;
+    /** Heuristic polling interval */
+    private static HEURISTIC_POLL_MS = 1500;
+
+    static getInstance(): AutoScreenDetector {
+        if (!_instance) {
+            _instance = new AutoScreenDetector();
+        }
+        return _instance;
+    }
+
+    // ─── Registration ───────────────────────────────────────────────────
+
+    /** Register a callback for screen changes */
+    onScreenChange(cb: ScreenChangeCallback): () => void {
+        this._listeners.push(cb);
+        // Return unsubscribe function
+        return () => {
+            this._listeners = this._listeners.filter(l => l !== cb);
+        };
+    }
+
+    // ─── Manual Override (highest priority) ────────────────────────────
+
+    /**
+     * Set screen name from manual instrumentation (`useScaleBunScreen` / `<ScaleBunScreen>`).
+     * This ALWAYS takes precedence over auto-detection.
+     */
+    setManualScreen(name: string): void {
+        try {
+            this._manualScreen = name;
+            this._manualScreenTs = Date.now();
+            this._emitScreenChange(name, 'manual');
+        } catch { /* no-throw */ }
+    }
+
+    /**
+     * Clear manual override. Auto-detection may resume after cooldown.
+     */
+    clearManualScreen(): void {
+        this._manualScreen = null;
+    }
+
+    /**
+     * Set screen name from native lifecycle detection (Android Activity / iOS ViewController).
+     * Lower priority than manual override — yields when manual is active.
+     * Use this when native code auto-detects the current screen without JS navigation.
+     */
+    setNativeScreen(name: string): void {
+        try {
+            if (!name || name === 'unknown') return;
+            if (this.isManualScreenActive()) return;
+            if (name !== this._autoScreen) {
+                this._autoScreen = name;
+                this._emitScreenChange(name, 'heuristic');
+            }
+        } catch { /* no-throw */ }
+    }
+
+    /**
+     * Check if a manual screen is currently active.
+     * Used by auto-detection to yield to manual overrides.
+     */
+    isManualScreenActive(): boolean {
+        if (!this._manualScreen) return false;
+        // Within cooldown period — manual wins
+        return (Date.now() - this._manualScreenTs) < AutoScreenDetector.MANUAL_COOLDOWN_MS;
+    }
+
+    // ─── Explicit Navigation Ref (second priority) ─────────────────────
+
+    /**
+     * Set an explicit React Navigation container ref.
+     * This is the most reliable auto-detection mechanism.
+     *
+     * @param ref - A React Navigation `NavigationContainerRef`
+     */
+    setNavigationRef(ref: any): void {
+        try {
+            if (!ref) return;
+            this._navigationRef = ref;
+            this._wireNavigationListener();
+            logger.debug('[AutoScreenDetector] Navigation ref set');
+        } catch (err: any) {
+            logger.warn('[AutoScreenDetector] setNavigationRef failed:', err?.message);
+        }
+    }
+
+    private _wireNavigationListener(): void {
+        try {
+            // Clean up previous listener
+            if (this._navListenerRemover) {
+                this._navListenerRemover();
+                this._navListenerRemover = null;
+            }
+            this._navListenerWired = false;
+
+            const navRef = this._navigationRef;
+            const container = navRef?.current ?? navRef;
+            // Container may be null when the ref came from useNavigationContainerRef()
+            // /createNavigationContainerRef() before <NavigationContainer> mounted.
+            // Leave _navListenerWired false so the poller retries once it populates.
+            if (!container || typeof container.addListener !== 'function') return;
+            this._navListenerWired = true;
+
+            // Wire state change listener (documented React Navigation API)
+            if (typeof container.addListener === 'function') {
+                const remover = container.addListener('state', () => {
+                    try {
+                        if (this.isManualScreenActive()) return;
+                        // Debounce: React Navigation fires multiple 'state' events
+                        // during a single transition (one per nested navigator).
+                        // Wait for the final settled state before emitting.
+                        if (this._navDebounceTimer) clearTimeout(this._navDebounceTimer);
+                        this._navDebounceTimer = setTimeout(() => {
+                            try {
+                                const state = typeof container.getRootState === 'function'
+                                    ? container.getRootState()
+                                    : null;
+                                if (state) {
+                                    const screen = this._extractActiveRoute(state);
+                                    if (screen && screen !== this._autoScreen) {
+                                        this._autoScreen = screen;
+                                        this._emitScreenChange(screen, 'navRef');
+                                    }
+                                }
+                            } catch { /* no-throw */ }
+                        }, 30);
+                    } catch { /* no-throw */ }
+                });
+                this._navListenerRemover = typeof remover === 'function'
+                    ? remover
+                    : remover?.remove ? () => remover.remove() : null;
+            }
+
+            // Get initial state immediately
+            if (typeof container.getRootState === 'function') {
+                const state = container.getRootState();
+                if (state) {
+                    const screen = this._extractActiveRoute(state);
+                    if (screen) {
+                        this._autoScreen = screen;
+                        this._emitScreenChange(screen, 'navRef');
+                    }
+                }
+            }
+        } catch { /* no-throw */ }
+    }
+
+    // ─── Heuristic Fallback (lowest priority) ──────────────────────────
+
+    /**
+     * Start the heuristic polling fallback.
+     * This periodically checks for React Navigation state via common patterns.
+     * Only fires if no manual screen or explicit nav ref is active.
+     */
+    private _startHeuristicPolling(): void {
+        if (this._heuristicTimer) return; // Idempotent
+
+        this._heuristicTimer = setInterval(() => {
+            try {
+                // If manual or navRef is providing screens, skip heuristic
+                if (this.isManualScreenActive()) return;
+                if (this._navigationRef) {
+                    // A ref was captured (e.g. via the React Navigation auto-hook) but
+                    // its container may have been null at wire time. Retry until the
+                    // documented 'state' listener attaches, then defer to it.
+                    if (!this._navListenerWired) this._wireNavigationListener();
+                    return;
+                }
+
+                // Best-effort: try to find the navigation container
+                // via the commonly-used global that React Navigation
+                // attaches when linking is configured
+                const navContainer = this._findNavigationContainer();
+                if (navContainer) {
+                    const state = typeof navContainer.getRootState === 'function'
+                        ? navContainer.getRootState()
+                        : null;
+                    if (state) {
+                        const screen = this._extractActiveRoute(state);
+                        if (screen && screen !== this._autoScreen) {
+                            this._autoScreen = screen;
+                            this._emitScreenChange(screen, 'heuristic');
+                        }
+                    }
+                }
+            } catch { /* no-throw — heuristic is best-effort */ }
+        }, AutoScreenDetector.HEURISTIC_POLL_MS);
+    }
+
+    /**
+     * Best-effort: try to locate a navigation container.
+     * Checks common global locations, returns null if none found.
+     */
+    private _findNavigationContainer(): any {
+        try {
+            // Check for React Navigation linking config container
+            const g = globalThis as any;
+
+            // Pattern 1: __reactNavigationRef (set by some navigation setups)
+            if (g.__reactNavigationRef?.current) {
+                return g.__reactNavigationRef.current;
+            }
+
+            // Pattern 2: Check if there's a registered navigation container
+            // via @react-navigation/native's NavigationContainer internal state
+            if (g.__scalebun_navigationRef?.current) {
+                return g.__scalebun_navigationRef.current;
+            }
+
+            return null;
+        } catch {
+            return null;
+        }
+    }
+
+    // ─── Route Extraction ───────────────────────────────────────────────
+
+    /**
+     * Extract the active route name from a navigation state tree.
+     * Handles nested navigators by walking to the deepest active route.
+     */
+    private _extractActiveRoute(state: NavigationState | null | undefined): string | null {
+        try {
+            if (!state?.routes || typeof state.index !== 'number') return null;
+
+            const activeRoute = state.routes[state.index];
+            if (!activeRoute) return null;
+
+            // If this route has nested state, recurse to find the deepest active route
+            if (activeRoute.state?.routes && typeof activeRoute.state.index === 'number') {
+                const nested = this._extractActiveRoute(activeRoute.state);
+                if (nested) return nested;
+            }
+
+            return activeRoute.name || null;
+        } catch {
+            return null;
+        }
+    }
+
+    // ─── Lifecycle ──────────────────────────────────────────────────────
+
+    /** Start auto-detection (idempotent) */
+    start(): void {
+        if (this._started) return;
+        this._started = true;
+        this._autoHookReactNavigation();
+        this._startHeuristicPolling();
+        logger.debug('[AutoScreenDetector] Started');
+    }
+
+    /**
+     * Zero-config React Navigation hook.
+     *
+     * Patches the three public entry points apps use to obtain a navigation
+     * container so the SDK captures the container ref WITHOUT the app wiring
+     * `setNavigationRef()` / `<ScaleBunDebugRoot navigationRef>`. Best-effort and
+     * no-throw: if `@react-navigation/native` isn't installed, or an entry point
+     * is missing, we silently skip and the heuristic poller remains the fallback.
+     *
+     * Once any container ref is captured, `setNavigationRef()` wires the
+     * documented `'state'` listener and the existing pipeline emits screen
+     * changes (→ SessionManager SCREEN_VIEW + navigation-triggered frames).
+     */
+    private _autoHookReactNavigation(): void {
+        try {
+            const reactNav = require('@react-navigation/native');
+            if (!reactNav || reactNav.__scalebunAutoHooked) return;
+
+            const detector = this;
+            /** How many entry points were verifiably replaced — 0 means detection is dead. */
+            let installed = 0;
+
+            /**
+             * Replace an export, on a module whose exports are GETTERS.
+             *
+             * `@react-navigation/native` ships ESM whose index is only re-exports, and every bundler
+             * compiles `export { X } from './X.js'` to an accessor with a getter and no setter. Plain
+             * assignment to that throws in strict mode — which is what the three patch points here
+             * used to do, inside a `catch` that discarded the error. The hook reported success, no
+             * container ref was ever captured, and the whole screen-name pipeline stayed empty.
+             *
+             * Defining the property works where assigning does not, and the read-back is what makes
+             * a future failure visible instead of silent.
+             */
+            const redefine = (key: string, value: unknown): boolean => {
+                try {
+                    Object.defineProperty(reactNav, key, {
+                        value,
+                        configurable: true,
+                        enumerable: true,
+                        writable: true,
+                    });
+                } catch {
+                    try {
+                        reactNav[key] = value;
+                    } catch { /* genuinely frozen — reported by the read-back below */ }
+                }
+                return reactNav[key] === value;
+            };
+
+            const register = (ref: any) => {
+                try {
+                    const container = ref?.current ?? ref;
+                    if (container && typeof container.getRootState === 'function') {
+                        detector.setNavigationRef(ref?.current ? ref : { current: container });
+                    }
+                } catch { /* no-throw */ }
+            };
+
+            // 1. NavigationContainer — broadest hook. Wrap so any container that
+            //    mounts registers its ref, regardless of whether the app passes one.
+            if (typeof reactNav.NavigationContainer === 'function') {
+                const Original = reactNav.NavigationContainer;
+                const React = require('react');
+                const Wrapped = React.forwardRef((props: any, forwardedRef: any) => {
+                    const innerRef = React.useRef(null);
+                    const registeredRef = React.useRef(null);
+                    const setRef = (node: any) => {
+                        innerRef.current = node;
+                        if (typeof forwardedRef === 'function') forwardedRef(node);
+                        else if (forwardedRef) forwardedRef.current = node;
+                    };
+                    React.useEffect(() => {
+                        // Register once per distinct container instance.
+                        if (innerRef.current && innerRef.current !== registeredRef.current) {
+                            registeredRef.current = innerRef.current;
+                            register(innerRef);
+                        }
+                    });
+                    return React.createElement(Original, { ...props, ref: setRef });
+                });
+                (Wrapped as any).displayName = 'ScaleBunNavigationContainer';
+                if (redefine('NavigationContainer', Wrapped)) installed++;
+            }
+
+            // 2. createNavigationContainerRef — apps that build the ref manually.
+            if (typeof reactNav.createNavigationContainerRef === 'function') {
+                const originalCreate = reactNav.createNavigationContainerRef;
+                const patchedCreate = (...args: any[]) => {
+                    const ref = originalCreate(...args);
+                    try { detector.setNavigationRef(ref); } catch { /* no-throw */ }
+                    return ref;
+                };
+                if (redefine('createNavigationContainerRef', patchedCreate)) installed++;
+            }
+
+            // 3. useNavigationContainerRef — hook variant of (2).
+            if (typeof reactNav.useNavigationContainerRef === 'function') {
+                const originalHook = reactNav.useNavigationContainerRef;
+                const patchedHook = (...args: any[]) => {
+                    const ref = originalHook(...args);
+                    try { detector.setNavigationRef(ref); } catch { /* no-throw */ }
+                    return ref;
+                };
+                if (redefine('useNavigationContainerRef', patchedHook)) installed++;
+            }
+
+            this._autoHookInstalled = installed > 0;
+            try { reactNav.__scalebunAutoHooked = true; } catch { /* frozen — best-effort */ }
+
+            if (installed === 0) {
+                // Said out loud. The previous silence is why this shipped broken: an app with screen
+                // detection completely dead looked identical to one with it working.
+                logger.warn(
+                    '[AutoScreenDetector] React Navigation is installed but none of its exports could be ' +
+                    'wrapped — screens will not be detected automatically. Pass your container ref to ' +
+                    'ScaleBun.setNavigationRef(ref) to restore screen names.',
+                );
+            } else {
+                logger.debug(`[AutoScreenDetector] React Navigation auto-hook installed (${installed}/3 entry points)`);
+            }
+        } catch { /* @react-navigation/native not installed — heuristic remains fallback */ }
+    }
+
+    /**
+     * Did the zero-config hook actually take effect?
+     *
+     * Exposed because "we tried" and "it worked" were previously the same observable state, and the
+     * difference between them is every screen name in the product.
+     */
+    isAutoHookInstalled(): boolean {
+        return this._autoHookInstalled;
+    }
+
+    /** Stop auto-detection and clean up */
+    stop(): void {
+        if (this._navDebounceTimer) {
+            clearTimeout(this._navDebounceTimer);
+            this._navDebounceTimer = null;
+        }
+        if (this._heuristicTimer) {
+            clearInterval(this._heuristicTimer);
+            this._heuristicTimer = null;
+        }
+        if (this._navListenerRemover) {
+            this._navListenerRemover();
+            this._navListenerRemover = null;
+        }
+        this._navListenerWired = false;
+        this._started = false;
+        this._lastEmittedScreen = null;
+        logger.debug('[AutoScreenDetector] Stopped');
+    }
+
+    /** Teardown completely (reset singleton) */
+    teardown(): void {
+        this.stop();
+        this._listeners = [];
+        this._manualScreen = null;
+        this._autoScreen = null;
+        this._navigationRef = null;
+        _instance = null;
+    }
+
+    /** Get the current best-known screen name */
+    getCurrentScreen(): string | null {
+        if (this._manualScreen && this.isManualScreenActive()) {
+            return this._manualScreen;
+        }
+        return this._autoScreen;
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    private _emitScreenChange(name: string, source: 'manual' | 'navRef' | 'heuristic'): void {
+        try {
+            // Deduplicate: don't emit if the screen is the same as last emitted
+            if (name === this._lastEmittedScreen) return;
+            this._lastEmittedScreen = name;
+
+            for (const cb of this._listeners) {
+                try {
+                    cb(name, source);
+                } catch { /* no-throw per-listener */ }
+            }
+        } catch { /* no-throw */ }
+    }
+}