@scalebun-release/react-native 2.5.0

package/lib/commonjs/features/journey/navDetector.js

@@ -0,0 +1,161 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NavDetector = void 0;
+var _bootstrap = require("../../debug/bootstrap");
+/**
+ * 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>
+ */
+
+class NavDetector {
+  _navMode = 'unknown';
+  _currentScreen = 'UnknownScreen';
+  _stack = [];
+  _listeners = [];
+  _installed = false;
+  _teardownFns = [];
+  get navMode() {
+    return this._navMode;
+  }
+  get currentScreen() {
+    return this._currentScreen;
+  }
+  get stack() {
+    return this._stack;
+  }
+
+  /** Install detection. Call after mount. Idempotent. */
+  install(config) {
+    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) {
+    if (name === this._currentScreen) return;
+    this._currentScreen = name;
+    this._notifyListeners();
+  }
+
+  /** Subscribe to screen changes */
+  onScreenChange(callback) {
+    this._listeners.push(callback);
+    return () => {
+      this._listeners = this._listeners.filter(l => l !== callback);
+    };
+  }
+
+  /** Get current screen payload for protocol */
+  getCurrentPayload() {
+    return {
+      screenName: this._currentScreen,
+      stack: this._stack.length > 0 ? this._stack : undefined
+    };
+  }
+
+  /** Teardown listeners */
+  teardown() {
+    for (const fn of this._teardownFns) {
+      try {
+        fn();
+      } catch {/* no-throw */}
+    }
+    this._teardownFns = [];
+    this._listeners = [];
+    this._installed = false;
+  }
+
+  // ─── Internal ───────────────────────────────────────────────────────
+
+  _tryReactNavigation() {
+    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;
+  }
+  _tryExpoRouter() {
+    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) {
+    try {
+      const route = this._extractCurrentRoute(state);
+      if (route?.name) {
+        this._currentScreen = route.name;
+        this._stack = this._extractStack(state);
+        this._notifyListeners();
+      }
+    } catch {
+      // no-throw
+    }
+  }
+  _extractCurrentRoute(state) {
+    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
+    };
+  }
+  _extractStack(state) {
+    if (!state || !state.routes) return [];
+    return state.routes.map(r => r.name);
+  }
+  _notifyListeners() {
+    // Update module-level screen tracker for cross-cutting enrichment
+    (0, _bootstrap.setTrackedScreen)(this._currentScreen);
+    for (const listener of this._listeners) {
+      try {
+        listener(this._currentScreen, this._stack);
+      } catch {
+        // no-throw
+      }
+    }
+  }
+}
+exports.NavDetector = NavDetector;
+//# sourceMappingURL=navDetector.js.map

package/lib/commonjs/features/journey/screenshotHelper.js

@@ -0,0 +1,136 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ScreenshotHelper = void 0;
+/**
+ * ScaleBun SDK — Screenshot Helper
+ *
+ * On-demand screenshot capture with compression.
+ * Falls back gracefully if react-native-view-shot is not available.
+ */
+
+class ScreenshotHelper {
+  _canCapture = false;
+  _rootRef = null;
+  constructor(config = {}) {
+    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() {
+    return this._canCapture;
+  }
+
+  /** Set the root ref for capturing (from ScaleBunDebugRoot) */
+  setRootRef(ref) {
+    this._rootRef = ref;
+    if (ref) this._canCapture = true;
+  }
+
+  /**
+   * Capture a screenshot. Returns null with reason if capture fails.
+   */
+  async capture() {
+    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) {
+      return {
+        result: null,
+        error: `Screenshot capture failed: ${e?.message || 'unknown error'}`
+      };
+    }
+  }
+
+  // ─── Internal ───────────────────────────────────────────────────────
+
+  _detectCapability() {
+    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;
+    }
+  }
+  _getCaptureRef() {
+    try {
+      const viewShot = require('react-native-view-shot');
+      return viewShot.captureRef || null;
+    } catch {
+      return null;
+    }
+  }
+}
+exports.ScreenshotHelper = ScreenshotHelper;
+//# sourceMappingURL=screenshotHelper.js.map

package/lib/commonjs/features/journey/scrollContext.js

@@ -0,0 +1,154 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SCROLL_OFFSET_TTL_MS = void 0;
+exports.clearScrollOffsets = clearScrollOffsets;
+exports.nativeTagOf = nativeTagOf;
+exports.nearestRecordedOffset = nearestRecordedOffset;
+exports.recordScrollOffset = recordScrollOffset;
+exports.trackedScrollerCount = trackedScrollerCount;
+var _targetGeometry = require("./targetGeometry");
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+const SCROLL_OFFSET_TTL_MS = exports.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();
+
+/**
+ * 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.
+ */
+function nativeTagOf(node) {
+  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.canonical;
+  if (canonical && typeof canonical.nativeTag === 'number' && Number.isFinite(canonical.nativeTag)) {
+    return canonical.nativeTag;
+  }
+  const n = (0, _targetGeometry.publicHostInstance)(node);
+  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. */
+function recordScrollOffset(tag, x, y, now = Date.now()) {
+  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 = 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.
+ */
+function nearestRecordedOffset(ancestorTags, now = Date.now()) {
+  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. */
+function clearScrollOffsets() {
+  offsets.clear();
+}
+
+/** How many scrollers are currently tracked — for the leak assertion in tests. */
+function trackedScrollerCount() {
+  return offsets.size;
+}
+//# sourceMappingURL=scrollContext.js.map

package/lib/commonjs/features/journey/targetGeometry.js

@@ -0,0 +1,185 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.containsNormalizedPoint = containsNormalizedPoint;
+exports.localPoint = localPoint;
+exports.normalizeRect = normalizeRect;
+exports.publicHostInstance = publicHostInstance;
+exports.readRectSync = readRectSync;
+/**
+ * RN-13 — THE TARGET'S RECTANGLE, without which "placed on Add to Cart" is unprovable.
+ *
+ * WHAT IS MISSING WITHOUT IT. A tap carries a point and an identity. That is enough to say "this
+ * tap resolved to the control named `checkout-cta`" and NOT enough to say the heat is actually ON
+ * that control — those are different claims, and only the second is what a heatmap draws. With no
+ * rect, an off-by-a-status-bar coordinate transform, a stale layout, or a mispaired identity all
+ * produce output that looks correct: a marker somewhere on the screen, labelled with a real
+ * control's name. The rect is what makes `heat ∈ target` decidable rather than assumed, which is
+ * why the plan moved this to P0 and ships it WITH semantic identity rather than after.
+ *
+ * WHY A SYNCHRONOUS MEASUREMENT IS THE WHOLE DESIGN CONSTRAINT. The tap handler runs synchronously
+ * and the interaction is emitted shortly after. React Native's classic measurement APIs
+ * (`measure`, `measureInWindow`) are CALLBACK-based, so a rect requested at finger-down arrives
+ * after the handler has returned and possibly after the event has been emitted. An implementation
+ * built on them would attach whichever rect happened to have resolved in time — sometimes the
+ * right one, sometimes the previous tap's, with no way to tell the two apart afterwards. That is
+ * the failure this module refuses to have.
+ *
+ * The New Architecture's host components expose `unstable_getBoundingClientRect()`, which returns
+ * a DOMRect SYNCHRONOUSLY. So the rect is either read in the same tick as the touch, or it is
+ * null. There is no third option and no best-effort.
+ *
+ * THE `unstable_` PREFIX IS LOAD-BEARING and is why every access here is a probe rather than a
+ * call. The method may be renamed when it stabilises, may be absent on the old architecture
+ * entirely, and may throw on a node that has been unmounted between the touch and the read. Each
+ * of those degrades to `null` — the SDK reports that it could not measure, which is a fact, rather
+ * than a rectangle it invented, which would be indistinguishable from a measured one.
+ */
+
+/** A rectangle in the same coordinate space as `pageX`/`pageY`: the RN root view. */
+
+/** A rectangle expressed as fractions of the capture base, directly comparable to a tap's normalized point. */
+
+/**
+ * THE PUBLIC HOST INSTANCE behind whatever a fiber's `stateNode` is.
+ *
+ * A host fiber's `stateNode` is NOT the object refs receive. On the New Architecture (Fabric) it is
+ * the renderer's internal `{ node, canonical }` wrapper, and the methods live one level down on
+ * `canonical.publicInstance` (ReactFabric renderer: `getPublicInstance`). Handed the wrapper, every
+ * probe below found nothing, so `target_rect` — and `local_u/v` derived from it — were null on 100%
+ * of production taps from v2.0.1 onward (legarage: RN 0.78.3, New Architecture) with no error
+ * anywhere. The scroll-ancestor lookup read its native tag off the same wrapper and failed the same
+ * way. On the old architecture the stateNode IS the public instance, so it is returned unchanged.
+ */
+function publicHostInstance(node) {
+  if (!node || typeof node !== 'object') return node;
+  const canonical = node.canonical;
+  if (canonical && typeof canonical === 'object' && canonical.publicInstance && typeof canonical.publicInstance === 'object') {
+    return canonical.publicInstance;
+  }
+  return node;
+}
+/**
+ * Read a node's rectangle synchronously, or return null.
+ *
+ * Both spellings are probed: `unstable_getBoundingClientRect` is what React Native 0.81 ships, and
+ * the unprefixed name is what it becomes if the API stabilises. Probing for both means the day it
+ * is renamed the SDK keeps working instead of silently losing geometry — and silently is exactly
+ * how it would go, because a missing rect is a legitimate outcome that produces no error.
+ */
+function readRectSync(node) {
+  const host = publicHostInstance(node);
+  if (!host || typeof host !== 'object') return null;
+  const n = host;
+  const fn = typeof n.unstable_getBoundingClientRect === 'function' ? n.unstable_getBoundingClientRect : typeof n.getBoundingClientRect === 'function' ? n.getBoundingClientRect : null;
+  if (!fn) return null;
+  try {
+    const r = fn.call(n);
+    if (!r) return null;
+    const {
+      x,
+      y,
+      width,
+      height
+    } = r;
+    /* A zero-area rect is not a measurement of a control, it is a control that is not laid out —
+       collapsed, unmounted mid-gesture, or measured before layout. Reporting it would put a
+       degenerate box into `heat ∈ target` and every containment test against it would fail in a
+       way that looks like a placement bug rather than a measurement gap. */
+    if (![x, y, width, height].every(v => typeof v === 'number' && Number.isFinite(v))) return null;
+    if (width <= 0 || height <= 0) return null;
+    return {
+      x,
+      y,
+      width,
+      height
+    };
+  } catch {
+    /* An unmounted node throws. Not measurable is not an error worth propagating. */
+    return null;
+  }
+}
+
+/**
+ * Express a rect as fractions of the capture base, so it is comparable to the tap's normalized point.
+ *
+ * WHY THIS SHARES THE TAP'S BASE AND NOT A WINDOW SIZE. The tap is normalized against the measured
+ * ROOT VIEW — the exact view the screenshot captures — precisely because `Dimensions.get('window')`
+ * excludes system insets differently across devices and pushes markers about 10% off vertically.
+ * A rect normalized against a different base than the point it will be compared with produces a
+ * containment test that is wrong by that same offset, which would read as "the heat is just outside
+ * the button" on every device with a status bar. Same base, or no rect.
+ *
+ * Values are NOT clamped to 0..1. A control genuinely extending past the capture base (a row
+ * scrolled half off-screen) has a rect that runs past the edge, and clamping it would silently
+ * enlarge the containment test — turning a tap that missed the visible part of a control into a hit.
+ */
+function normalizeRect(rect, base) {
+  if (!rect || !base || base.w <= 0 || base.h <= 0) return null;
+  const out = {
+    x: rect.x / base.w,
+    y: rect.y / base.h,
+    width: rect.width / base.w,
+    height: rect.height / base.h
+  };
+  if (![out.x, out.y, out.width, out.height].every(v => Number.isFinite(v))) return null;
+  return out;
+}
+
+/**
+ * WHERE IN THE CONTROL the tap landed — RN-15.
+ *
+ * `u` and `v` are the tap's position as fractions of the target's own box: (0,0) is its top-left,
+ * (1,1) its bottom-right, (0.5,0.5) dead centre. This is what turns "they tapped Add to Cart" into
+ * "they tapped the left edge of Add to Cart", which is the difference between knowing a control is
+ * used and knowing whether its hit area is right.
+ *
+ * RESOLUTION-INDEPENDENT BY CONSTRUCTION, which is the point on mobile. A screen-space heatmap
+ * aggregates a control differently on every device size, so a button that sits at 40% width on a
+ * phone and 25% on a tablet produces two clouds of heat that never combine. Local coordinates are
+ * the same numbers on both, so one control is one distribution regardless of what it is rendered on.
+ *
+ * DELIBERATELY NOT CLAMPED, and this is the interesting part rather than an oversight. A value
+ * outside 0..1 means the tap landed OUTSIDE the control's visual box and was still attributed to
+ * it — which is exactly what `hitSlop` does, and it is real: `hitSlop={24}` makes a control
+ * respond to touches two dozen points beyond its own edge. Clamping would erase the one signal
+ * that distinguishes "tapped the button" from "tapped near the button and the button took it",
+ * and that distinction is a design finding: a control whose taps cluster outside its own bounds is
+ * drawn too small.
+ *
+ * Returns null, not a centre, when either input is missing. A fabricated (0.5, 0.5) would sit in
+ * the middle of every distribution and look exactly like a deliberate central tap.
+ */
+function localPoint(rect, nx, ny) {
+  if (!rect || rect.width <= 0 || rect.height <= 0) return null;
+  if (typeof nx !== 'number' || typeof ny !== 'number') return null;
+  if (!Number.isFinite(nx) || !Number.isFinite(ny)) return null;
+  return {
+    u: (nx - rect.x) / rect.width,
+    v: (ny - rect.y) / rect.height
+  };
+}
+
+/**
+ * Is the tap's normalized point inside the target's normalized rect?
+ *
+ * THE PREDICATE THE WHOLE MODULE EXISTS FOR. A heatmap that draws a marker labelled with a
+ * control's name is asserting this, and until now nothing checked it.
+ *
+ * Edges are INCLUSIVE. A tap on a button's exact border is a tap on the button — exclusive edges
+ * would report a sliver of every control as a miss, and at the resolution these coordinates carry
+ * that sliver is not a real distinction.
+ *
+ * Returns null, not false, when either input is missing. "The point is outside the control" and
+ * "we could not measure the control" are different findings with different fixes, and collapsing
+ * them into `false` would make an unmeasurable control look like a placement failure.
+ */
+function containsNormalizedPoint(rect, nx, ny) {
+  if (!rect) return null;
+  if (typeof nx !== 'number' || typeof ny !== 'number') return null;
+  if (!Number.isFinite(nx) || !Number.isFinite(ny)) return null;
+  return nx >= rect.x && nx <= rect.x + rect.width && ny >= rect.y && ny <= rect.y + rect.height;
+}
+//# sourceMappingURL=targetGeometry.js.map

package/lib/commonjs/features/journey/targetRegistry.js

@@ -0,0 +1,53 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.findTarget = findTarget;
+exports.getRegisteredTargetIds = getRegisteredTargetIds;
+exports.hasTarget = hasTarget;
+exports.registerTarget = registerTarget;
+/**
+ * ScaleBun SDK — Target Registry
+ *
+ * Registry for deterministic replay targets.
+ * Apps register interactive elements with handlers for replay execution.
+ */
+
+const _targets = new Map();
+
+/**
+ * Register a target element for deterministic journey replay.
+ * During replay, the runner can call press/setValue/scrollTo directly.
+ */
+function registerTarget(target) {
+  _targets.set(target.id, target);
+  return () => {
+    _targets.delete(target.id);
+  };
+}
+
+/**
+ * Find a registered target by ID.
+ * @internal
+ */
+function findTarget(id) {
+  return _targets.get(id);
+}
+
+/**
+ * Check if a target is registered.
+ * @internal
+ */
+function hasTarget(id) {
+  return _targets.has(id);
+}
+
+/**
+ * Get all registered target IDs.
+ * @internal
+ */
+function getRegisteredTargetIds() {
+  return Array.from(_targets.keys());
+}
+//# sourceMappingURL=targetRegistry.js.map