@scalebun/react-native 1.13.0 → 2.0.1

package/src/features/journey/targetGeometry.ts

@@ -0,0 +1,176 @@
+/**
+ * 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. */
+export interface ElementRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** A rectangle expressed as fractions of the capture base, directly comparable to a tap's normalized point. */
+export interface NormalizedRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+interface RectCapableNode {
+  unstable_getBoundingClientRect?: () => { x: number; y: number; width: number; height: number } | null;
+  getBoundingClientRect?: () => { x: number; y: number; width: number; height: number } | null;
+}
+
+/**
+ * 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.
+ */
+export function readRectSync(node: unknown): ElementRect | null {
+  if (!node || typeof node !== 'object') return null;
+  const n = node as RectCapableNode;
+  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.
+ */
+export function normalizeRect(rect: ElementRect | null, base: { w: number; h: number } | null): NormalizedRect | null {
+  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.
+ */
+export function localPoint(
+  rect: NormalizedRect | null,
+  nx: number | null | undefined,
+  ny: number | null | undefined,
+): { u: number; v: number } | null {
+  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.
+ */
+export function containsNormalizedPoint(
+  rect: NormalizedRect | null,
+  nx: number | null | undefined,
+  ny: number | null | undefined,
+): boolean | null {
+  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
+  );
+}

package/src/features/journey/touchTarget.ts

@@ -9,29 +9,165 @@
  * WHY THE FIBER. There is no DOM. The only place a tapped view's identity exists in JS is the React
  * fiber hanging off the touch event (`_targetInst`), which carries `memoizedProps` — where
  * `accessibilityLabel` and `testID` live. This is a React internal, so every access is defensive and
- * the whole thing degrades to `null` rather than throwing: a analytics label is never worth a crash.
+ * the whole thing degrades to `null` rather than throwing: an analytics label is never worth a crash.
  *
- * IDENTITY PREFERENCE, strongest first:
- *   1. `accessibilityLabel` — authored to describe the control, and already required for a11y.
- *   2. `testID` — authored to identify the control, stable across copy changes.
- *   3. a literal string child — the button's visible caption.
- *   4. the nearest named component — coarse, but far better than nothing.
+ * ─────────────────────────────────────────────────────────────────────────────────────────────
+ * RN-2 — THE IDENTITY LADDER USED TO CAPTURE USER TEXT, AND THAT IS A PRIVACY DEFECT, NOT A
+ * TRADE-OFF.
+ *
+ * The previous preference order was:
+ *
+ *   1. accessibilityLabel   2. testID   3. a literal string child   4. nearest component
+ *
+ * Ranks 1 and 3 are FREE TEXT authored for humans, and in a real app they routinely contain user
+ * data. An accessible order row is labelled "Order 1042 for mohamed@scalebun.com". A pay button
+ * reads "Pay EGP 1,442". A contact row's caption is a person's name. Rank 1 was preferred over
+ * `testID`, so the leakiest source won whenever it existed.
+ *
+ * Two separate harms, and the second is easy to miss:
+ *
+ *   PRIVACY. `describeTouchTarget`'s output is persisted as the interaction's `target`. So names,
+ *   email addresses and amounts were being written into an analytics store, under a field nobody
+ *   would think to audit for PII. The same product already found 27 rows in `replay_events`
+ *   carrying email addresses through a different route; this was a second one.
+ *
+ *   CORRECTNESS. `target` is an AGGREGATION KEY. Keyed on text that varies per user, a single
+ *   button produces one bucket per person — so the grouping this feature exists to provide is
+ *   destroyed precisely in the screens that matter most. A leaky key is also a useless key.
+ *
+ * SO THE LADDER IS NOW DERIVED FROM CODE, NEVER FROM CONTENT:
+ *
+ *   1. `testID`     — authored to identify, stable across copy edits, and by convention never
+ *                     user data. The strongest signal and now the first.
+ *   2. `path`       — the component-name chain from the tapped node upward, e.g.
+ *                     `CartScreen>OrderRow>Pressable`. Structural: it changes when the code
+ *                     changes, not when the data does. This is what makes the ladder useful in
+ *                     the overwhelming majority of apps, which have no testIDs — without it,
+ *                     removing free text would have meant removing identity.
+ *   3. `component`  — the nearest named component alone. Coarse, but a code identifier.
+ *
+ * Free text is still RESOLVABLE, because a team that has audited its own labels may legitimately
+ * want them, but it is opt-in per call (`includeText`) and it is NEVER what
+ * `describeTouchTarget` returns. Default-off matters more than the option: a default that leaks
+ * is a leak, whatever the documentation says.
+ *
+ * WHY THIS SHIPS WITH RN-1 (persistence) RATHER THAN AFTER IT. RN-1 makes the resolved target
+ * actually reach the backend. Landing that first would persist the leaky ladder and create a
+ * historical PII problem to clean up; landing the sanitised ladder first and persistence second
+ * leaves a window where the feature looks broken. They are one change.
+ * ─────────────────────────────────────────────────────────────────────────────────────────────
  */
 
 export interface TouchTarget {
-  accessibilityLabel?: string;
+  /** Authored identifier. Safe to persist and to aggregate on. */
   testID?: string;
-  text?: string;
+  /**
+   * Structural path of component names, tapped node first, e.g. `Pressable<OrderRow<CartScreen`.
+   * Derived from the code's shape, so it never contains user data.
+   */
+  path?: string;
+  /** Nearest named component. A code identifier, safe. */
   component?: string;
+  /**
+   * FREE TEXT — may contain user data. Populated ONLY when `includeText` is requested, and never
+   * returned by `describeTouchTarget`. Treat as unsafe to persist without an audit.
+   */
+  accessibilityLabel?: string;
+  /** FREE TEXT — the visible caption. Same warning as `accessibilityLabel`. */
+  text?: string;
+  /**
+   * RN-13 — the host node the IDENTITY was taken from, so a rect read off it describes the
+   * same element the tap was attributed to.
+   *
+   * This is the reason the node is captured during the identity walk rather than by a second,
+   * independent walk: two walks can disagree about which ancestor is "the control", and a rect
+   * belonging to a different element than the name is worse than no rect at all — it would make
+   * `heat ∈ target` answer confidently about the wrong box.
+   *
+   * Deliberately NOT serialisable and never persisted. Callers read a rectangle off it and
+   * discard it; nothing downstream should hold a React internal.
+   */
+  node?: unknown;
+  /**
+   * RN-3 — every ancestor host instance from the tapped node upward, INNERMOST FIRST.
+   *
+   * Collected on the identity walk rather than by a second traversal, for the same reason the
+   * rect's node is: two walks can disagree about the chain, and attributing a tap to the wrong
+   * scroller's offset places it by how far a DIFFERENT container had scrolled. Order is the
+   * contract — `nearestRecordedOffset` takes the first ancestor that has an offset, because that
+   * is the scroller the content under the finger actually moved with.
+   *
+   * Like `node`, these are React internals: read a native tag off them and discard.
+   */
+  ancestors?: unknown[];
+  /**
+   * RN-4 — the list row's own identity, for FREE.
+   *
+   * MEASURED BEFORE IT WAS DESIGNED, because the obvious fix was to make every app author a
+   * testID per row and that would have been a large, permanent burden on every integration. It is
+   * unnecessary. React Native's `VirtualizedList` builds each cell as
+   *
+   *     const key = VirtualizedList._keyExtractor(item, ii, this.props);   // line 797
+   *     <CellRenderer cellKey={key} index={ii} key={key} ... />            // line 817
+   *
+   * so the app's OWN `keyExtractor` output — which every correct list already provides, because
+   * React requires keys — sits on the cell fiber as an ordinary prop. The walk that resolves
+   * identity already passes that fiber and simply never read it.
+   *
+   * `cellKey` is preferred over the fiber's `key` field: it is the same value, but reached
+   * through `memoizedProps` like every other prop this module reads, rather than through a React
+   * internal whose exposure is not part of any contract.
+   *
+   * WHY THIS MATTERS MORE THAN AN ORDINARY LABEL. A virtualised list REUSES native views: row 40
+   * scrolls into the view row 1 vacated. Without the cell key those two taps share a native
+   * identity and a screen position, so they merge — one hotspot on a row nobody in particular
+   * tapped. `itemIndex` is carried alongside precisely so the recycling is visible: the same index
+   * with a different key is a recycled slot, and that is a fact worth being able to prove rather
+   * than infer.
+   */
+  itemKey?: string;
+  /** The cell's position in the list at render time. See `itemKey` for why both are kept. */
+  itemIndex?: number;
+}
+
+/** Where a resolved identity came from — so a consumer can tell an authored id from a guess. */
+export type TargetIdentitySource = 'testID' | 'path' | 'component' | 'none';
+
+export interface ResolveTouchTargetOptions {
+  /** How far up the tree to look. */
+  maxDepth?: number;
+  /**
+   * Collect `accessibilityLabel` and the visible caption.
+   *
+   * OFF BY DEFAULT AND MEANT TO STAY THAT WAY. Turning it on means user-authored text may be
+   * carried out of the app, so it belongs to a team that has audited its own labels — not to a
+   * default. Even when on, the text is never used as the identity.
+   */
+  includeText?: boolean;
 }
 
 /** How far up the tree to look before giving up. Deep enough for a wrapped button, cheap enough to run on every tap. */
 const MAX_DEPTH = 12;
 /** Labels longer than this are truncated — a caption, not a paragraph. */
 const MAX_LEN = 60;
+/**
+ * How many component names the structural path may hold.
+ *
+ * Four is enough to separate two same-named controls in different containers
+ * (`Pressable<OrderRow<CartScreen` vs `Pressable<SuggestionRow<CartScreen`) without letting the
+ * key drift every time someone adds a wrapper view higher up. A path that changes on unrelated
+ * refactors is a key that silently splits its own history.
+ */
+const MAX_PATH_SEGMENTS = 4;
 
 interface FiberLike {
   memoizedProps?: Record<string, unknown> | null;
+  /**
+   * The host instance. On the New Architecture this is a ReactFabricHostComponent, which is
+   * the only thing in reach that can report a rectangle SYNCHRONOUSLY — see targetGeometry.ts
+   * for why an asynchronous measurement is unusable for a per-tap rect.
+   */
+  stateNode?: unknown;
   elementType?: unknown;
   type?: unknown;
   return?: FiberLike | null;
@@ -56,7 +192,7 @@ function componentName(f: FiberLike): string | undefined {
   return n.slice(0, MAX_LEN);
 }
 
-/** First literal string child, e.g. <Text>Buy now</Text>. */
+/** First literal string child, e.g. <Text>Buy now</Text>. FREE TEXT — see the header. */
 function textChild(props: Record<string, unknown> | null | undefined): string | undefined {
   if (!props) return undefined;
   const c = props.children;
@@ -76,10 +212,11 @@ function fiberOf(event: unknown): FiberLike | null {
   const e = event as Record<string, unknown>;
   const direct = e._targetInst;
   if (direct && typeof direct === 'object') return direct as FiberLike;
-  // Newer RN exposes the instance handle on the target node instead.
-  const target = e.target as Record<string, unknown> | undefined;
-  if (target && typeof target === 'object') {
-    const handle = target._internalFiberInstanceHandleDEV ?? target._internalInstanceHandle;
+  const target = (e.target ?? (e.nativeEvent as Record<string, unknown> | undefined)?.target) as
+    | Record<string, unknown>
+    | undefined;
+  if (target) {
+    const handle = target._internalInstanceHandle ?? target._targetInst;
     if (handle && typeof handle === 'object') return handle as FiberLike;
   }
   return null;
@@ -88,41 +225,115 @@ function fiberOf(event: unknown): FiberLike | null {
 /**
  * Walk up from the touched fiber collecting the best identity available.
  *
- * Keeps walking after a hit so a wrapper's `testID` can still be picked up when the leaf only had text,
- * but stops as soon as BOTH an accessibilityLabel and a testID are known — nothing above can improve on
- * that pair.
+ * Keeps walking after a hit so a wrapper's `testID` can still be picked up when the leaf had none,
+ * and stops as soon as a `testID` is known AND the path is full — nothing above can improve on that.
  */
-export function resolveTouchTarget(event: unknown, maxDepth = MAX_DEPTH): TouchTarget | null {
+export function resolveTouchTarget(
+  event: unknown,
+  optsOrMaxDepth: ResolveTouchTargetOptions | number = {},
+): TouchTarget | null {
+  /* Number form kept for the previous signature `resolveTouchTarget(event, maxDepth)`. */
+  const opts: ResolveTouchTargetOptions =
+    typeof optsOrMaxDepth === 'number' ? { maxDepth: optsOrMaxDepth } : optsOrMaxDepth;
+  const maxDepth = opts.maxDepth ?? MAX_DEPTH;
+
   let f = fiberOf(event);
   if (!f) return null;
   const out: TouchTarget = {};
+  const segments: string[] = [];
+  const ancestors: unknown[] = [];
   let depth = 0;
   try {
     while (f && depth < maxDepth) {
       const props = f.memoizedProps;
       if (props) {
-        out.accessibilityLabel ??= str(props.accessibilityLabel);
+        const beforeTestId = out.testID;
         out.testID ??= str(props.testID);
-        out.text ??= textChild(props);
+        /* The node is pinned to the fiber that supplied the testID — the CONTROL, not the
+           deepest node hit. A Text inside a Pressable is a tap on the Pressable, so the rect
+           has to be the Pressable's or the containment test would be run against the caption. */
+        if (!beforeTestId && out.testID) out.node = f.stateNode;
+        /* The nearest enclosing cell wins: nested lists mean a row can sit inside another
+           row, and the innermost is the one the finger is actually in. `??=` keeps the first
+           seen while walking outward, which is the innermost. */
+        if (typeof props.cellKey === 'string' && props.cellKey) {
+          out.itemKey ??= str(props.cellKey);
+          if (typeof props.index === 'number' && Number.isFinite(props.index)) {
+            out.itemIndex ??= props.index;
+          }
+        }
+        if (opts.includeText) {
+          out.accessibilityLabel ??= str(props.accessibilityLabel);
+          out.text ??= textChild(props);
+        }
+      }
+      /* Host instances only — a composite fiber has no native tag, so keeping them would pad
+         the chain with entries no scroller could ever match. */
+      if (f.stateNode) ancestors.push(f.stateNode);
+      const name = componentName(f);
+      if (name) {
+        out.component ??= name;
+        /* Consecutive duplicates collapse: a component that renders itself through a memo or a
+           forwardRef appears twice in the fiber chain and would otherwise pad the path with a
+           repetition that carries no information. */
+        if (segments[segments.length - 1] !== name && segments.length < MAX_PATH_SEGMENTS) {
+          segments.push(name);
+        }
       }
-      out.component ??= componentName(f);
-      if (out.accessibilityLabel && out.testID) break;
+      if (out.testID && segments.length >= MAX_PATH_SEGMENTS) break;
       f = f.return ?? null;
       depth++;
     }
   } catch {
     /* React internals shifted under us — return whatever was gathered so far */
   }
-  return out.accessibilityLabel || out.testID || out.text || out.component ? out : null;
+
+  /* Tapped node first, so the most specific segment leads and a truncated path is still anchored
+     to the thing actually touched. */
+  if (segments.length) out.path = segments.join('<');
+
+  /* No authored testID anywhere, so identity came from the structural path. Anchor the rect to
+     the node that was actually touched — imperfect (it may be the caption rather than the
+     control) but honest, and better than no geometry for the majority of apps, which author no
+     testIDs. `targetSource` records which case this was, so a consumer can weight it. */
+  if (!out.node) out.node = fiberOf(event)?.stateNode;
+
+  if (ancestors.length) out.ancestors = ancestors;
+
+  return out.testID || out.path || out.component || out.accessibilityLabel || out.text || out.itemKey
+    ? out
+    : null;
 }
 
 /**
- * One short human label for the tapped thing, or undefined when nothing identified it.
+ * One short, STABLE, non-identifying label for the tapped thing.
  *
- * This is what ends up grouping the Events explorer, so it must be STABLE: a11y label and testID are
- * authored and rarely change, whereas visible text moves with copy edits — hence the ordering.
+ * This is what ends up grouping the Events explorer and what gets persisted as the interaction's
+ * target, so it must satisfy two constraints at once: stable across copy edits, and free of user
+ * data. Both rule out visible text, which is why the free-text fields are not consulted here even
+ * when they have been resolved — see the RN-2 note in the header.
  */
 export function describeTouchTarget(t: TouchTarget | null): string | undefined {
   if (!t) return undefined;
-  return t.accessibilityLabel || t.testID || t.text || t.component;
+  return t.testID || t.path || t.component;
+}
+
+/**
+ * The identity plus WHERE IT CAME FROM.
+ *
+ * A consumer cannot treat an authored `testID` and a structural `path` as equally trustworthy: the
+ * first is a promise from the app's authors that this control is this control, the second is an
+ * inference that breaks when the tree is refactored. Returning the source lets the accounting lane
+ * say WHY a tap could not be attributed, instead of reporting a missing target and leaving the
+ * reader to guess whether the control had no identity or the walk failed.
+ */
+export function targetIdentity(t: TouchTarget | null): {
+  id?: string;
+  source: TargetIdentitySource;
+} {
+  if (!t) return { source: 'none' };
+  if (t.testID) return { id: t.testID, source: 'testID' };
+  if (t.path) return { id: t.path, source: 'path' };
+  if (t.component) return { id: t.component, source: 'component' };
+  return { source: 'none' };
 }

package/src/features/journey/uiState.ts

@@ -50,7 +50,10 @@ const clean = (s: string): string =>
 export function setUiState(name: string, value: string): void {
   const n = clean(name);
   const v = clean(value);
-  if (n && v) declared.set(n, v);
+  if (!n || !v) return;
+  if (declared.get(n) === v) return;
+  declared.set(n, v);
+  notifyChanged();
 }
 
 /**
@@ -62,8 +65,10 @@ export function setUiState(name: string, value: string): void {
  * screen.
  */
 export function clearUiState(name?: string): void {
+  const before = declared.size;
   if (name === undefined) declared.clear();
   else declared.delete(clean(name));
+  if (declared.size !== before) notifyChanged();
 }
 
 /**
@@ -87,3 +92,77 @@ export function uiStateSignature(): string | undefined {
   }
   return signature || undefined;
 }
+
+/**
+ * RN-11 — TELL SOMEONE THE STATE CHANGED, so a frame can exist for it.
+ *
+ * THE GAP. Declaring a state used to mutate a Map and nothing else. Nothing captured a frame, so
+ * the visual for a declared state existed only if a screenshot happened to be taken for some other
+ * reason — a navigation, a timer, or the interaction capture that fires AFTER the touch and
+ * photographs the outcome. A state could therefore be recorded as a fact with no picture of it
+ * anywhere, or with a picture of the state that replaced it.
+ *
+ * The native capture reasons are NAVIGATION, MANUAL, INTERACTION and TIMER. None of them is "the
+ * UI changed shape", which is exactly the moment a heatmap needs a frame.
+ *
+ * FIRING ON A REAL CHANGE ONLY, AND WHY THAT IS THE SDK'S JOB. The advice above says to call
+ * `setUiState` when the state changes rather than on every render — but that is advice to the
+ * host, not a guarantee. A component that declares its state inside render is ordinary React, and
+ * trusting the caller would mean a screenshot per render: a performance disaster in exactly the
+ * apps that instrument most carefully. So a redundant set — same dimension, same value — is now a
+ * no-op, and the change test lives here where it cannot be got wrong by a host.
+ *
+ * COALESCED, because a transition usually declares several dimensions in one tick ("drawer:open"
+ * and "overlay:visible" belong to one visual change). Notifying per call would capture the
+ * intermediate shapes, which are states the user never saw.
+ *
+ * The listener is deliberately NOT given the signature. A subscriber that wants it calls
+ * `uiStateSignature()` at the moment it acts, which is the value that will actually be attached
+ * to the next tap; handing over a snapshot invites acting on a state that has already moved on.
+ */
+export type UiStateChangeListener = () => void;
+
+const listeners = new Set<UiStateChangeListener>();
+let pending: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Subscribe to declared-state changes. Returns an unsubscribe.
+ *
+ * Registration is idempotent per function reference, so a component that re-subscribes on every
+ * render does not accumulate listeners — a leak that would only show up in long sessions.
+ */
+export function onUiStateChange(listener: UiStateChangeListener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Drop every listener and any pending notification. For teardown between sessions. */
+export function resetUiStateListeners(): void {
+  listeners.clear();
+  if (pending !== null) {
+    clearTimeout(pending);
+    pending = null;
+  }
+}
+
+/** For assertions that a re-subscribing caller has not leaked. */
+export function uiStateListenerCount(): number {
+  return listeners.size;
+}
+
+function notifyChanged(): void {
+  if (pending !== null) return;
+  pending = setTimeout(() => {
+    pending = null;
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+        /* One bad subscriber must not stop the others, and must never surface to the host: a
+           screenshot is not worth an app crash. */
+      }
+    }
+  }, 0);
+}