@scalebun-release/react-native 2.5.0

package/src/features/navigation/AutoScreenDetector.ts

@@ -0,0 +1,617 @@
+/**
+ * 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;
+    /**
+     * When `_autoScreen` was last written.
+     *
+     * Needed so `getCurrentScreen()` can prefer whichever source spoke MOST RECENTLY.
+     * Without a timestamp the only comparison available was "is the manual value still
+     * fresh", which is a different question and gave the wrong answer — see the note on
+     * `_currentScreen()`.
+     */
+    private _autoScreenTs = 0;
+    /** `name#key` of the last auto-detected screen VISIT — see _extractActiveVisit. */
+    private _autoVisitSig: 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 _lastEmittedTs = 0;
+    /**
+     * Cross-source emit dedup window — see _emitScreenChange. Long enough to absorb the manual
+     * beacon and the navRef listener both reporting the SAME transition (they land within the
+     * 30ms nav debounce plus a render), short enough that a genuine re-visit of the same route
+     * a moment later is a new screen view rather than silence.
+     */
+    private static readonly EMIT_DEDUP_WINDOW_MS = 800;
+    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._autoScreenTs = Date.now();
+                this._autoVisitSig = name; // native lifecycle carries no route key — name-only visit
+                this._emitScreenChange(name, 'heuristic');
+            }
+        } catch { /* no-throw */ }
+    }
+
+    /**
+     * Should a WRITER defer to the manual screen right now?
+     *
+     * THIS IS A PRECEDENCE GATE, NOT A VALIDITY TEST, and conflating the two was a real
+     * bug. Its job is what the cooldown constant says: for a short window after a manual
+     * beacon fires, an auto source must not overwrite it — the poller runs every 1500 ms
+     * and would otherwise clobber a fresh declaration with whatever it inferred.
+     *
+     * `getCurrentScreen()` used to reuse this as "is the manual screen still the current
+     * screen", which made a declared screen READABLE for only 2000 ms. Nothing called
+     * `setManualScreen` in production, so the effect was latent — but the moment the
+     * `<ScaleBunScreen>` beacon was wired to it (RN-8), every tap more than two seconds
+     * after a screen mounted would have lost its name, which is very nearly every tap. A
+     * fix that introduced that would have been worse than the gap it closed.
+     */
+    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();
+            __DEV__ && 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) {
+                                    // Compared by name#key so a re-VISIT of the same route
+                                    // (new key) is recorded — name-only comparison swallowed it.
+                                    const visit = this._extractActiveVisit(state);
+                                    if (visit && this._visitSig(visit) !== this._autoVisitSig) {
+                                        this._autoScreen = visit.name;
+                        this._autoScreenTs = Date.now();
+                                        this._autoVisitSig = this._visitSig(visit);
+                                        this._emitScreenChange(visit.name, '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 visit = this._extractActiveVisit(state);
+                    if (visit) {
+                        this._autoScreen = visit.name;
+                        this._autoScreenTs = Date.now();
+                        this._autoVisitSig = this._visitSig(visit);
+                        this._emitScreenChange(visit.name, '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) {
+                        // name#key comparison: a re-opened route (same name, fresh key) seen
+                        // across poll ticks is a new visit even when every intermediate screen
+                        // fell between polls — the case a name-only diff could never see.
+                        const visit = this._extractActiveVisit(state);
+                        if (visit && this._visitSig(visit) !== this._autoVisitSig) {
+                            this._autoScreen = visit.name;
+                        this._autoScreenTs = Date.now();
+                            this._autoVisitSig = this._visitSig(visit);
+                            this._emitScreenChange(visit.name, '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 {
+        return this._extractActiveVisit(state)?.name ?? null;
+    }
+
+    /**
+     * Extract the active route's name AND its React Navigation route `key`.
+     *
+     * The key is what makes re-VISITS detectable. Comparing names alone collapses two
+     * different visits to the same route into one screen view: leave Details, open Details
+     * again, and `name === _autoScreen` swallowed the second visit entirely (QA: "opened the
+     * same route again and no screen event was recorded"). React Navigation mints a fresh
+     * `key` for every pushed route instance, so a re-push of the same name is a NEW key —
+     * name+key comparison records each visit while a mere re-render of the same instance
+     * (same key) still emits nothing. States without keys degrade to name-only, i.e. the
+     * old behaviour, never worse.
+     */
+    private _extractActiveVisit(
+        state: NavigationState | null | undefined,
+    ): { name: string; key: string | null } | 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._extractActiveVisit(activeRoute.state);
+                if (nested) return nested;
+            }
+
+            if (!activeRoute.name) return null;
+            const rawKey = (activeRoute as unknown as { key?: unknown }).key;
+            return { name: activeRoute.name, key: typeof rawKey === 'string' ? rawKey : null };
+        } catch {
+            return null;
+        }
+    }
+
+    /** `name#key` signature of one screen VISIT — what the auto paths dedup on. */
+    private _visitSig(visit: { name: string; key: string | null }): string {
+        return visit.key ? `${visit.name}#${visit.key}` : visit.name;
+    }
+
+    // ─── Lifecycle ──────────────────────────────────────────────────────
+
+    /** Start auto-detection (idempotent) */
+    start(): void {
+        if (this._started) return;
+        this._started = true;
+        this._autoHookReactNavigation();
+        this._startHeuristicPolling();
+        __DEV__ && 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 {
+                __DEV__ && 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;
+        __DEV__ && logger.debug('[AutoScreenDetector] Stopped');
+    }
+
+    /** Teardown completely (reset singleton) */
+    teardown(): void {
+        this.stop();
+        this._listeners = [];
+        this._manualScreen = null;
+        this._autoScreen = null;
+        this._autoScreenTs = 0;
+        this._navigationRef = null;
+        _instance = null;
+    }
+
+    /** Get the current best-known screen name */
+    getCurrentScreen(): string | null {
+        return this._currentScreen().name;
+    }
+
+    /**
+     * WHERE the current screen name came from, or 'none'.
+     *
+     * Recorded on every interaction (RN-8) so low screen coverage is DIAGNOSABLE rather
+     * than merely visible. Production shows 13.8% of Android interactions carrying a
+     * screen and 0.5% on iOS, and those numbers cannot today distinguish three different
+     * causes: the app never instrumented anything, the app instrumented manually and the
+     * value never reached interactions, or auto-detection ran and failed. Those have
+     * different owners and different fixes, and guessing between them is how a P0 stays
+     * open.
+     */
+    getCurrentScreenSource(): 'manual' | 'navigation' | 'none' {
+        return this._currentScreen().source;
+    }
+
+    /**
+     * LAST WRITER WINS between the manual beacon and auto-detection.
+     *
+     * A screen declared by `<ScaleBunScreen name>` stays current until something else
+     * declares a different one — that is what mounting a screen means. It does not
+     * expire, which is the correction here: the previous rule returned the manual name
+     * only while it was under 2000 ms old and then silently fell back to the auto value,
+     * which in a manually-instrumented app is `null`.
+     *
+     * Comparing timestamps rather than hard-coding a priority also handles the real
+     * interleaving: an app can use React Navigation for most screens AND drop a manual
+     * beacon on one modal, and whichever spoke last is the truth.
+     */
+    private _currentScreen(): { name: string | null; source: 'manual' | 'navigation' | 'none' } {
+        const manual = this._manualScreen;
+        const auto = this._autoScreen;
+        if (manual && (!auto || this._manualScreenTs >= this._autoScreenTs)) {
+            return { name: manual, source: 'manual' };
+        }
+        if (auto) return { name: auto, source: 'navigation' };
+        return { name: null, source: 'none' };
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    private _emitScreenChange(name: string, source: 'manual' | 'navRef' | 'heuristic'): void {
+        try {
+            // Cross-source dedup, TIME-BOUNDED. This used to drop any name equal to the last
+            // emitted, forever — so re-entering a route whose departure was never observed
+            // (heuristic poll missed the intermediate screen, or the user re-pushed the same
+            // route) was swallowed on EVERY path, manual beacons included (QA: "opened the
+            // same route again, no screen event"). Same name within the window is still one
+            // transition double-reported by two sources; same name after it is a new visit.
+            const emitNow = Date.now();
+            if (
+                name === this._lastEmittedScreen &&
+                emitNow - this._lastEmittedTs < AutoScreenDetector.EMIT_DEDUP_WINDOW_MS
+            ) return;
+            this._lastEmittedScreen = name;
+            this._lastEmittedTs = emitNow;
+
+            for (const cb of this._listeners) {
+                try {
+                    cb(name, source);
+                } catch { /* no-throw per-listener */ }
+            }
+        } catch { /* no-throw */ }
+    }
+}