@scalebun-release/react-native 2.5.0

package/src/features/journey/nativeScroll.ts

@@ -0,0 +1,94 @@
+/**
+ * SCROLL FIELDS FOR ONE TAP — the JS wrapper's offset when present, else the native probe's.
+ *
+ * Production had 0 of ~55,000 mobile taps with a scroll offset: offsets were only recorded by the
+ * SDK's own ScrollView/FlatList wrappers, and apps use the stock components. The native trackers
+ * now read every scroll container under the finger at ACTION_DOWN (Android ScrollContextProbe),
+ * with no wrapper, in the capture view's pixel space — the same space as the tap's x/y.
+ *
+ * Precedence: the innermost NATIVE entry (`'native'`, capture-view pixels, the same space as x/y)
+ * first; the JS wrapper's offset (`'wrapper'`, layout points) only when native had none. `'none'`
+ * still means no scroll container was under the finger — which, unlike
+ * before, is now a statement about the layout rather than about the integration.
+ */
+
+/** Current version of the mobile heatmap tap contract. Bump when a field's meaning changes. */
+export const HEATMAP_SCHEMA_VERSION = 2;
+
+export interface NativeScrollEntry {
+  containerTag?: number;
+  kind?: string;
+  horizontal?: boolean;
+  offsetX?: number;
+  offsetY?: number;
+  contentWidth?: number;
+  contentHeight?: number;
+  viewportWidth?: number;
+  viewportHeight?: number;
+}
+
+interface StartLike {
+  scrollX?: number;
+  scrollY?: number;
+  scrollSource?: string;
+}
+
+interface NativeEventLike {
+  scrollContext?: unknown;
+  pixelDensity?: unknown;
+}
+
+const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+
+/** Keep only well-formed entries: a malformed native payload must never become a fabricated offset. */
+export function sanitizeScrollContext(raw: unknown): NativeScrollEntry[] {
+  if (!Array.isArray(raw)) return [];
+  const out: NativeScrollEntry[] = [];
+  for (const e of raw) {
+    if (!e || typeof e !== 'object') continue;
+    const r = e as NativeScrollEntry;
+    if (!finite(r.offsetX) || !finite(r.offsetY)) continue;
+    out.push({
+      containerTag: finite(r.containerTag) ? r.containerTag : undefined,
+      kind: typeof r.kind === 'string' ? r.kind : undefined,
+      horizontal: r.horizontal === true,
+      offsetX: r.offsetX,
+      offsetY: r.offsetY,
+      contentWidth: finite(r.contentWidth) ? r.contentWidth : undefined,
+      contentHeight: finite(r.contentHeight) ? r.contentHeight : undefined,
+      viewportWidth: finite(r.viewportWidth) ? r.viewportWidth : undefined,
+      viewportHeight: finite(r.viewportHeight) ? r.viewportHeight : undefined,
+    });
+    if (out.length >= 4) break;
+  }
+  return out;
+}
+
+export function scrollFields(
+  start: StartLike | null | undefined,
+  event: NativeEventLike | null | undefined,
+): {
+  scrollX?: number;
+  scrollY?: number;
+  scrollSource: 'wrapper' | 'native' | 'none';
+  scrollContext?: NativeScrollEntry[];
+  pixelDensity?: number;
+  heatmapSchemaVersion: number;
+} {
+  const chain = sanitizeScrollContext(event?.scrollContext);
+  const density = finite(event?.pixelDensity) && (event!.pixelDensity as number) > 0 ? (event!.pixelDensity as number) : undefined;
+  const base = {
+    ...(chain.length ? { scrollContext: chain } : {}),
+    ...(density ? { pixelDensity: density } : {}),
+    heatmapSchemaVersion: HEATMAP_SCHEMA_VERSION,
+  };
+  /* NATIVE FIRST: it is in the capture view's pixel space, the same space as the tap's x/y. The JS
+     wrapper records contentOffset in layout points, so on Android (x/y in physical pixels) mixing
+     the two is off by the pixel density. The wrapper remains the fallback where native has none. */
+  const inner = chain[0];
+  if (inner) return { scrollX: inner.offsetX, scrollY: inner.offsetY, scrollSource: 'native', ...base };
+  if (start?.scrollSource === 'wrapper' && finite(start.scrollX) && finite(start.scrollY)) {
+    return { scrollX: start.scrollX, scrollY: start.scrollY, scrollSource: 'wrapper', ...base };
+  }
+  return { scrollSource: 'none', ...base };
+}

package/src/features/journey/navDetector.ts

@@ -0,0 +1,149 @@
+/**
+ * ScaleBun SDK — Navigation Detector
+ *
+ * Layered detection strategy:
+ * 1. React Navigation — detect via @react-navigation/native
+ * 2. Expo Router — detect via expo-router
+ * 3. Screen Beacon — fallback via useScaleBunScreen() / <ScaleBunScreen>
+ */
+
+import type { NavMode, CurrentScreenPayload } from './journeyTypes';
+import { setTrackedScreen } from '../../debug/bootstrap';
+
+export type ScreenChangeCallback = (screenName: string, stack?: string[]) => void;
+
+export class NavDetector {
+    private _navMode: NavMode = 'unknown';
+    private _currentScreen = 'UnknownScreen';
+    private _stack: string[] = [];
+    private _listeners: ScreenChangeCallback[] = [];
+    private _installed = false;
+    private _teardownFns: Array<() => void> = [];
+
+    get navMode(): NavMode { return this._navMode; }
+    get currentScreen(): string { return this._currentScreen; }
+    get stack(): string[] { return this._stack; }
+
+    /** Install detection. Call after mount. Idempotent. */
+    install(config: { autoDetect?: boolean; allowBeaconFallback?: boolean }): void {
+        if (this._installed) return;
+        this._installed = true;
+
+        if (config.autoDetect !== false) {
+            // Try React Navigation first
+            if (this._tryReactNavigation()) return;
+            // Try Expo Router
+            if (this._tryExpoRouter()) return;
+        }
+
+        // Fallback to beacon mode
+        if (config.allowBeaconFallback !== false) {
+            this._navMode = 'beacon';
+        }
+    }
+
+    /** Set screen name (used by Screen Beacon hook/component) */
+    setScreen(name: string): void {
+        if (name === this._currentScreen) return;
+        this._currentScreen = name;
+        this._notifyListeners();
+    }
+
+    /** Subscribe to screen changes */
+    onScreenChange(callback: ScreenChangeCallback): () => void {
+        this._listeners.push(callback);
+        return () => {
+            this._listeners = this._listeners.filter(l => l !== callback);
+        };
+    }
+
+    /** Get current screen payload for protocol */
+    getCurrentPayload(): CurrentScreenPayload {
+        return {
+            screenName: this._currentScreen,
+            stack: this._stack.length > 0 ? this._stack : undefined,
+        };
+    }
+
+    /** Teardown listeners */
+    teardown(): void {
+        for (const fn of this._teardownFns) {
+            try { fn(); } catch { /* no-throw */ }
+        }
+        this._teardownFns = [];
+        this._listeners = [];
+        this._installed = false;
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    private _tryReactNavigation(): boolean {
+        try {
+            const reactNav = require('@react-navigation/native');
+            if (reactNav && reactNav.createNavigationContainerRef) {
+                this._navMode = 'react-navigation';
+                // We'll use the ref-based approach from ScaleBunDebugRoot
+                return true;
+            }
+        } catch {
+            // Not installed
+        }
+        return false;
+    }
+
+    private _tryExpoRouter(): boolean {
+        try {
+            const expoRouter = require('expo-router');
+            // Validate a real Expo Router API rather than mere truthiness: the SDK's
+            // optional-dependency stub is an empty object, so `if (expoRouter)` alone
+            // would falsely report Expo Router as present when it is not installed.
+            if (typeof expoRouter?.usePathname === 'function') {
+                this._navMode = 'expo-router';
+                return true;
+            }
+        } catch {
+            // Not installed
+        }
+        return false;
+    }
+
+    /** Called when React Navigation state changes */
+    handleNavigationStateChange(state: any): void {
+        try {
+            const route = this._extractCurrentRoute(state);
+            if (route?.name) {
+                this._currentScreen = route.name;
+                this._stack = this._extractStack(state);
+                this._notifyListeners();
+            }
+        } catch {
+            // no-throw
+        }
+    }
+
+    private _extractCurrentRoute(state: any): { name: string; key?: string } | null {
+        if (!state || !state.routes) return null;
+        const route = state.routes[state.index ?? state.routes.length - 1];
+        if (route?.state) {
+            return this._extractCurrentRoute(route.state) || { name: route.name, key: route.key };
+        }
+        return { name: route.name, key: route.key };
+    }
+
+    private _extractStack(state: any): string[] {
+        if (!state || !state.routes) return [];
+        return state.routes.map((r: any) => r.name);
+    }
+
+    private _notifyListeners(): void {
+        // Update module-level screen tracker for cross-cutting enrichment
+        setTrackedScreen(this._currentScreen);
+        for (const listener of this._listeners) {
+            try {
+                listener(this._currentScreen, this._stack);
+            } catch {
+                // no-throw
+            }
+        }
+    }
+}

package/src/features/journey/screenshotHelper.ts

@@ -0,0 +1,137 @@
+/**
+ * ScaleBun SDK — Screenshot Helper
+ *
+ * On-demand screenshot capture with compression.
+ * Falls back gracefully if react-native-view-shot is not available.
+ */
+
+import type { JourneyScreenshotConfig } from './journeyTypes';
+
+export interface ScreenshotResult {
+    base64: string;
+    width: number;
+    height: number;
+    mime: string;
+    byteSize: number;
+}
+
+export class ScreenshotHelper {
+    private config: Required<JourneyScreenshotConfig>;
+    private _canCapture = false;
+    private _rootRef: any = null;
+
+    constructor(config: JourneyScreenshotConfig = {}) {
+        this.config = {
+            mode: config.mode ?? 'onDemand',
+            periodicMs: config.periodicMs ?? 1000,
+            maxWidth: config.maxWidth ?? 720,
+            maxImageKB: config.maxImageKB ?? 250,
+            format: config.format ?? 'jpeg',
+        };
+        this._detectCapability();
+    }
+
+    get canCapture(): boolean { return this._canCapture; }
+
+    /** Set the root ref for capturing (from ScaleBunDebugRoot) */
+    setRootRef(ref: any): void {
+        this._rootRef = ref;
+        if (ref) this._canCapture = true;
+    }
+
+    /**
+     * Capture a screenshot. Returns null with reason if capture fails.
+     */
+    async capture(): Promise<{ result: ScreenshotResult | null; error?: string }> {
+        if (!this._canCapture || !this._rootRef) {
+            return {
+                result: null,
+                error: 'Screenshot not available: no root ref (wrap app with <ScaleBunDebugRoot>)',
+            };
+        }
+
+        try {
+            const captureRef = this._getCaptureRef();
+            if (!captureRef) {
+                return { result: null, error: 'react-native-view-shot not installed' };
+            }
+
+            const uri = await captureRef(this._rootRef, {
+                format: this.config.format === 'webp' ? 'webm' : 'jpg',
+                quality: 0.7,
+                width: this.config.maxWidth,
+                result: 'base64',
+            });
+
+            if (!uri) {
+                return { result: null, error: 'Capture returned empty result' };
+            }
+
+            const base64 = typeof uri === 'string' ? uri : '';
+            const byteSize = Math.ceil(base64.length * 0.75); // base64 → bytes
+            const mime = this.config.format === 'webp' ? 'image/webp' : 'image/jpeg';
+
+            // Check max size
+            const maxBytes = this.config.maxImageKB * 1024;
+            if (byteSize > maxBytes) {
+                // Try again with lower quality
+                const retryUri = await captureRef(this._rootRef, {
+                    format: 'jpg',
+                    quality: 0.4,
+                    width: Math.min(this.config.maxWidth, 480),
+                    result: 'base64',
+                });
+                if (retryUri) {
+                    const retryBytes = Math.ceil(retryUri.length * 0.75);
+                    return {
+                        result: {
+                            base64: retryUri,
+                            width: Math.min(this.config.maxWidth, 480),
+                            height: 0, // Will be inferred by renderer
+                            mime: 'image/jpeg',
+                            byteSize: retryBytes,
+                        },
+                    };
+                }
+            }
+
+            return {
+                result: {
+                    base64,
+                    width: this.config.maxWidth,
+                    height: 0, // Inferred
+                    mime,
+                    byteSize,
+                },
+            };
+        } catch (e: any) {
+            return {
+                result: null,
+                error: `Screenshot capture failed: ${e?.message || 'unknown error'}`,
+            };
+        }
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    private _detectCapability(): void {
+        try {
+            const viewShot = require('react-native-view-shot');
+            if (viewShot && viewShot.captureRef) {
+                this._canCapture = true;
+            }
+        } catch {
+            // Not installed — will fall back to explicit error
+            this._canCapture = false;
+        }
+    }
+
+    private _getCaptureRef(): ((ref: any, options: any) => Promise<string>) | null {
+        try {
+            const viewShot = require('react-native-view-shot');
+            return viewShot.captureRef || null;
+        } catch {
+            return null;
+        }
+    }
+}

package/src/features/journey/scrollContext.ts

@@ -0,0 +1,146 @@
+/**
+ * RN-3 — WHERE IN THE CONTENT A TAP HAPPENED, not just where on the glass.
+ *
+ * THE DEFECT. A tap carries screen coordinates. Two taps at the SAME screen coordinate, one
+ * viewport apart in a scrolling list, are two different controls — and with no scroll offset they
+ * are indistinguishable, so they merge into one hotspot. The heatmap then shows heavy engagement
+ * at a position where, in content terms, nothing in particular is.
+ *
+ * That is not a rendering nicety. Scroll offset is a PLACEMENT dimension (which content was under
+ * the finger) and a CACHE dimension (two states of one route that must not share a backdrop), so
+ * its absence corrupts both the aggregate and the picture drawn beneath it.
+ *
+ * WHY A REGISTRY RATHER THAN A SINGLE NUMBER. `ScrollTracker` already accumulates
+ * `previousOffsetX/Y`, but as ONE global pair with no idea which scroller moved. A screen with a
+ * vertical list containing a horizontal carousel has two scrollers, and whichever fired last
+ * overwrites the other — so the vertical position of a tap inside the carousel is whatever the
+ * carousel's horizontal offset happened to leave behind. A single global scrollY cannot express a
+ * nested scroller, and silently reports a wrong number rather than none.
+ *
+ * So offsets are keyed by the scroller's NATIVE TAG, which is the one identity both ends of this
+ * can see: the wrapper holds a ref to its own ScrollView, and the touch handler's fiber walk
+ * passes the same host instances on its way up. Matching on anything else — a name, an index, a
+ * generated id — would require the two sides to agree on a convention, and a convention that can
+ * drift is a join that can silently attach the wrong scroller's offset.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: guess. If no ancestor of the tapped node has a recorded
+ * offset, the answer is null, not zero. Zero is a real scroll position — the top of a list — and
+ * reporting it for "we do not know" would place every unmeasured tap at the top of its content,
+ * which is both wrong and indistinguishable from a genuine tap there.
+ *
+ * KNOWN LIMIT, stated because it bounds what this can deliver: offsets only arrive from
+ * `ScaleBunScrollView`, which an app has to opt into. A plain `<ScrollView>` reports nothing, so
+ * `scrollSource` is `'none'` and the tap has no content depth. Making it automatic means patching
+ * React Native's own exports — the SDK already does that for `@react-navigation/native` — and that
+ * is a decision with a much larger blast radius, not one to make silently inside a data fix.
+ */
+import { publicHostInstance } from './targetGeometry';
+
+
+export interface ScrollOffset {
+  x: number;
+  y: number;
+  /** When it was recorded; used only to expire entries, never reported. */
+  at: number;
+}
+
+/**
+ * How long a recorded offset stays usable.
+ *
+ * A scroller that has not moved in this long may well have been unmounted — a list on a screen the
+ * user left — and its stale offset must not be attached to a tap on a DIFFERENT screen that happens
+ * to reuse the same native tag. Tags are recycled by the platform, which makes this a correctness
+ * bound rather than a memory one.
+ *
+ * Five minutes is far longer than any plausible gap between scrolling a list and tapping in it,
+ * and far shorter than a session.
+ */
+export const SCROLL_OFFSET_TTL_MS = 5 * 60_000;
+
+/**
+ * Cap on tracked scrollers.
+ *
+ * Bounded because a long session on a virtualised screen can mount and unmount many scrollers, and
+ * an unbounded map is a leak that only shows up in the sessions that matter most — the long ones.
+ * Eviction is oldest-first, which is the entry least likely to be the one a tap needs.
+ */
+const MAX_TRACKED_SCROLLERS = 32;
+
+const offsets = new Map<number, ScrollOffset>();
+
+/**
+ * The native tag of a host instance, across the shapes React Native has used.
+ *
+ * Fabric exposes `__nativeTag`; the old architecture used `_nativeTag`. Probing both means this
+ * keeps working on either architecture, and returns null rather than throwing on anything else —
+ * a scroll offset is never worth a crash.
+ */
+export function nativeTagOf(node: unknown): number | null {
+  if (!node || typeof node !== 'object') return null;
+  /* A Fabric fiber stateNode is `{ node, canonical }`: the tag is on `canonical.nativeTag` and on the
+     public instance's `__nativeTag`, never on the wrapper itself — see publicHostInstance. */
+  const canonical = (node as { canonical?: { nativeTag?: unknown } }).canonical;
+  if (canonical && typeof canonical.nativeTag === 'number' && Number.isFinite(canonical.nativeTag)) {
+    return canonical.nativeTag;
+  }
+  const n = publicHostInstance(node) as { __nativeTag?: unknown; _nativeTag?: unknown };
+  if (!n || typeof n !== 'object') return null;
+  const tag = typeof n.__nativeTag === 'number' ? n.__nativeTag : n._nativeTag;
+  return typeof tag === 'number' && Number.isFinite(tag) ? tag : null;
+}
+
+/** Record where a scroller currently sits. Called on every scroll event of a wrapped scroller. */
+export function recordScrollOffset(tag: number | null, x: number, y: number, now = Date.now()): void {
+  if (tag === null || !Number.isFinite(x) || !Number.isFinite(y)) return;
+  offsets.set(tag, { x, y, at: now });
+  if (offsets.size > MAX_TRACKED_SCROLLERS) {
+    let oldestTag: number | null = null;
+    let oldestAt = Infinity;
+    for (const [k, v] of offsets) {
+      if (v.at < oldestAt) {
+        oldestAt = v.at;
+        oldestTag = k;
+      }
+    }
+    if (oldestTag !== null) offsets.delete(oldestTag);
+  }
+}
+
+/**
+ * The offset of the NEAREST ancestor scroller that has one, given the tapped node's ancestor tags
+ * ordered innermost first.
+ *
+ * Nearest wins because that is the scroller the content under the finger actually moved with. A
+ * tap inside a horizontal carousel inside a vertical list belongs to the carousel's content
+ * position; attributing it to the outer list would place it by how far the PAGE had scrolled,
+ * which is the merge this whole module exists to prevent.
+ *
+ * Returns null when no ancestor has a recorded offset — never a zero.
+ */
+export function nearestRecordedOffset(
+  ancestorTags: readonly (number | null)[],
+  now = Date.now(),
+): { x: number; y: number; tag: number } | null {
+  for (const tag of ancestorTags) {
+    if (tag === null) continue;
+    const hit = offsets.get(tag);
+    if (!hit) continue;
+    if (now - hit.at > SCROLL_OFFSET_TTL_MS) {
+      /* Expired: drop it so a recycled tag cannot serve a previous screen's offset. */
+      offsets.delete(tag);
+      continue;
+    }
+    return { x: hit.x, y: hit.y, tag };
+  }
+  return null;
+}
+
+/** Forget everything. Called between sessions so one recording cannot inherit another's scrollers. */
+export function clearScrollOffsets(): void {
+  offsets.clear();
+}
+
+/** How many scrollers are currently tracked — for the leak assertion in tests. */
+export function trackedScrollerCount(): number {
+  return offsets.size;
+}