@scalebun-release/react-native 2.5.0

package/lib/module/features/navigation/AutoScreenDetector.js

@@ -0,0 +1,601 @@
+/**
+ * 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 ──────────────────────────────────────────────────────────────────
+
+// ─── Singleton State ────────────────────────────────────────────────────────
+
+let _instance = 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 {
+  _listeners = [];
+  _manualScreen = null;
+  _manualScreenTs = 0;
+  _autoScreen = 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()`.
+   */
+  _autoScreenTs = 0;
+  /** `name#key` of the last auto-detected screen VISIT — see _extractActiveVisit. */
+  _autoVisitSig = null;
+  _navigationRef = null;
+  _navListenerRemover = null;
+  _navListenerWired = false;
+  _heuristicTimer = null;
+  _started = false;
+  _lastEmittedScreen = null;
+  _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.
+   */
+  static EMIT_DEDUP_WINDOW_MS = 800;
+  _navDebounceTimer = null;
+  /** Whether the React Navigation exports were actually replaced — see _autoHookReactNavigation. */
+  _autoHookInstalled = false;
+
+  /** Cooldown: after manual screen is set, suppress auto-detection for this duration */
+  static MANUAL_COOLDOWN_MS = 2000;
+  /** Heuristic polling interval */
+  static HEURISTIC_POLL_MS = 1500;
+  static getInstance() {
+    if (!_instance) {
+      _instance = new AutoScreenDetector();
+    }
+    return _instance;
+  }
+
+  // ─── Registration ───────────────────────────────────────────────────
+
+  /** Register a callback for screen changes */
+  onScreenChange(cb) {
+    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) {
+    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() {
+    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) {
+    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() {
+    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) {
+    try {
+      if (!ref) return;
+      this._navigationRef = ref;
+      this._wireNavigationListener();
+      __DEV__ && logger.debug('[AutoScreenDetector] Navigation ref set');
+    } catch (err) {
+      logger.warn('[AutoScreenDetector] setNavigationRef failed:', err?.message);
+    }
+  }
+  _wireNavigationListener() {
+    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.
+   */
+  _startHeuristicPolling() {
+    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.
+   */
+  _findNavigationContainer() {
+    try {
+      // Check for React Navigation linking config container
+      const g = globalThis;
+
+      // 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.
+   */
+  _extractActiveRoute(state) {
+    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.
+   */
+  _extractActiveVisit(state) {
+    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.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. */
+  _visitSig(visit) {
+    return visit.key ? `${visit.name}#${visit.key}` : visit.name;
+  }
+
+  // ─── Lifecycle ──────────────────────────────────────────────────────
+
+  /** Start auto-detection (idempotent) */
+  start() {
+    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).
+   */
+  _autoHookReactNavigation() {
+    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, value) => {
+        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 => {
+        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, forwardedRef) => {
+          const innerRef = React.useRef(null);
+          const registeredRef = React.useRef(null);
+          const setRef = node => {
+            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.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) => {
+          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) => {
+          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() {
+    return this._autoHookInstalled;
+  }
+
+  /** Stop auto-detection and clean up */
+  stop() {
+    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() {
+    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() {
+    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() {
+    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.
+   */
+  _currentScreen() {
+    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 ───────────────────────────────────────────────────────
+
+  _emitScreenChange(name, source) {
+    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 */}
+  }
+}
+//# sourceMappingURL=AutoScreenDetector.js.map