@scalebun/react-native 2.0.0 → 2.0.2

package/src/features/journey/interactionProtocol.ts

@@ -14,7 +14,52 @@ export interface InteractionStartContext {
     y: number;
     target?: string;
     targetId?: string;
+    /**
+     * WHICH kind of identity `targetId` is: an authored `testID`, a structural component path, or
+     * a bare component name.
+     *
+     * Carried because they are not equally trustworthy — a testID is a promise from the app's
+     * authors, a path is an inference that breaks when the tree is refactored — and a consumer
+     * that cannot tell them apart renders a refactor-fragile guess as a confident target.
+     */
+    targetSource?: 'testID' | 'path' | 'component' | 'none';
     screenName?: string;
+    /** RN-8: where `screenName` came from, so low coverage is diagnosable rather than merely visible. */
+    screenSource?: 'manual' | 'navigation' | 'none';
+    /**
+     * RN-13: the target control's rectangle as fractions of the capture base, or undefined when it
+     * could not be measured synchronously. Comparable to the tap's own normalized point, which is
+     * what makes 'heat is on this control' checkable rather than assumed.
+     */
+    targetRect?: { x: number; y: number; width: number; height: number };
+    /**
+     * RN-3: the content offset of the nearest ancestor scroller at finger-down, so two taps at the
+     * same screen coordinate one viewport apart do not merge. Absent when no ancestor reported one
+     * — never defaulted to 0, which is a real scroll position (the top of a list).
+     */
+    scrollX?: number;
+    scrollY?: number;
+    /** Whether a scroll offset was available at all. 'none' means no wrapped scroller was an ancestor. */
+    scrollSource?: 'wrapper' | 'none';
+    /**
+     * RN-4: the list row's key, taken from the app's own `keyExtractor` via the cell's `cellKey`
+     * prop. Distinguishes two taps that share a RECYCLED native view — the same slot showing a
+     * different row after scrolling — which would otherwise merge into one hotspot.
+     */
+    itemKey?: string;
+    /** The row's index at render time. Same index + different key = a recycled slot. */
+    itemIndex?: number;
+    /**
+     * RN-15: the tap's position INSIDE the target control — (0,0) its top-left, (1,1) its
+     * bottom-right. Resolution-independent, so one control is one distribution across every device
+     * size rather than a separate cloud of heat per screen width.
+     *
+     * NOT clamped. A value outside 0..1 means the tap landed outside the control's visual box and
+     * was still attributed to it, which is what `hitSlop` does — and a control whose taps cluster
+     * outside its own bounds is drawn too small, which is a finding rather than noise.
+     */
+    localU?: number;
+    localV?: number;
     ui?: string;
     stateStatus: InteractionStateStatus;
     emitAutomaticAnalytics: boolean;
@@ -24,22 +69,155 @@ export function generateInteractionId(): string {
     return `ixj-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
 
+/**
+ * RN-6 — THE CORRELATION CONTRACT.
+ *
+ * WHAT IS BEING JOINED, AND WHY IT IS HARD. A physical tap is observed twice: natively, by
+ * a window callback that sees ACTION_DOWN/UP and produces the coordinates; and in JS, by a
+ * capture-phase touch handler that produces the IDENTITY — which control was hit, what UI
+ * state was declared, which screen. Both sides mint their own id and neither can derive
+ * the other's: native builds `ixn-a-<process nonce>-<MotionEvent ts>` from a clock JS
+ * cannot read, and JS builds `ixj-<Date.now()>-<random>`. So the two observations have to
+ * be JOINED, and the only shared quantity is time.
+ *
+ * WHY THE OLD JOIN WAS DANGEROUS RATHER THAN MERELY APPROXIMATE. It took whichever start
+ * was nearest in time within ±1500 ms and used it unconditionally. The fields it carries
+ * across are `target`, `targetId`, `ui`, `stateStatus` and `screenName`; the coordinates
+ * come from the native side and are always right. So a wrong pairing does not produce
+ * obviously broken data — it produces heat in the CORRECT position attributed to the
+ * WRONG control, in the wrong UI state, on the wrong screen. Nothing downstream can
+ * detect that, because every field is individually well-formed.
+ *
+ * 1500 ms is a very long time on a touch surface. A deliberate double-tap is 150–300 ms
+ * apart; an impatient tapper is faster. So "nearest within 1500 ms" routinely had more
+ * than one candidate, and picked one with no record that it had a choice.
+ *
+ * WHAT THIS REPLACES IT WITH — three outcomes instead of one, and a refusal:
+ *
+ *   'exact'      one candidate is clearly closest: the runner-up is at least
+ *                `marginMs` further away. The join is used.
+ *   'ambiguous'  two candidates are within `marginMs` of each other, so choosing
+ *                between them is a coin flip. The join is REFUSED and the caller must
+ *                emit the interaction WITHOUT js-derived identity. A tap with no target
+ *                is honest and visibly incomplete; a tap with the wrong target is
+ *                indistinguishable from a correct one and corrupts every aggregate it
+ *                enters.
+ *   'none'       nothing within tolerance. Same refusal, different reason — worth
+ *                separating because 'none' means the JS handler never fired (a real
+ *                capture gap) while 'ambiguous' means it fired too often to attribute.
+ *
+ * It also reports `deltaMs` and `runnerUpDeltaMs` so the outcome is auditable after the
+ * fact rather than being a claim this comment makes.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: use position to disambiguate. The native event carries
+ * raw px in the capture view and normalized 0..1 coordinates; the JS start carries its own
+ * x/y in a different space (dp in the root view). Comparing them needs a proven scale
+ * factor between the two, and getting it wrong would REJECT valid pairings — strictly
+ * worse than today. That calibration needs a device run, so it is a follow-up, not a
+ * guess made here.
+ */
+export type CorrelationOutcome = 'exact' | 'ambiguous' | 'none';
+
+export interface CorrelationResult<T> {
+    /** Present only when `outcome` is 'exact'. Never a best-guess. */
+    start?: T;
+    /** Index into the input array, so the caller can consume it. -1 unless 'exact'. */
+    index: number;
+    outcome: CorrelationOutcome;
+    /** Distance to the chosen (or best rejected) candidate; null when there was none. */
+    deltaMs: number | null;
+    /** Distance to the second candidate — what makes 'ambiguous' auditable. */
+    runnerUpDeltaMs: number | null;
+}
+
+/**
+ * How far apart a native event and a JS start may be and still be the same touch.
+ *
+ * Unchanged at 1500 ms from the previous implementation, deliberately: narrowing it is a
+ * separate, measurable decision about how late the JS handler can run on a slow device,
+ * and bundling it into this change would make any regression impossible to attribute.
+ */
+export const CORRELATION_TOLERANCE_MS = 1500;
+
+/**
+ * How much closer the winner must be than the runner-up to count as identified.
+ *
+ * 100 ms because that is comfortably below the fastest deliberate double-tap (~150 ms):
+ * when two candidate starts are within 100 ms of each other in distance, the native event
+ * sits effectively between them and the "nearest" one is a coin flip.
+ */
+export const CORRELATION_MARGIN_MS = 100;
+
 /** Match a native bridge event to the JS evidence sampled at the same finger-down. */
-export function nearestInteractionStart<T extends InteractionStartContext>(
+export function correlateInteraction<T extends InteractionStartContext>(
     starts: readonly T[],
     occurredAt: number,
-    toleranceMs = 1500,
-): T | undefined {
-    let best: T | undefined;
-    let bestDelta = toleranceMs + 1;
-    for (const start of starts) {
+    toleranceMs = CORRELATION_TOLERANCE_MS,
+    marginMs = CORRELATION_MARGIN_MS,
+): CorrelationResult<T> {
+    const candidates: Array<{ index: number; delta: number }> = [];
+    for (let i = 0; i < starts.length; i++) {
+        const start = starts[i];
+        if (!start) continue;
         const delta = Math.abs(start.occurredAt - occurredAt);
-        if (delta < bestDelta) {
-            best = start;
-            bestDelta = delta;
+        if (delta <= toleranceMs) candidates.push({ index: i, delta });
+    }
+
+    if (candidates.length === 0) {
+        return { index: -1, outcome: 'none', deltaMs: null, runnerUpDeltaMs: null };
+    }
+
+    /* Stable ordering: equal deltas resolve by index so a repeated run cannot produce a
+       different answer from the same inputs. A non-deterministic correlation would make
+       every downstream measurement unreproducible. */
+    candidates.sort((a, b) => (a.delta - b.delta) || (a.index - b.index));
+    const best = candidates[0]!;
+    const runnerUp = candidates[1];
+
+    if (runnerUp && runnerUp.delta - best.delta < marginMs) {
+        return {
+            index: -1,
+            outcome: 'ambiguous',
+            deltaMs: best.delta,
+            runnerUpDeltaMs: runnerUp.delta,
+        };
+    }
+
+    return {
+        start: starts[best.index],
+        index: best.index,
+        outcome: 'exact',
+        deltaMs: best.delta,
+        runnerUpDeltaMs: runnerUp ? runnerUp.delta : null,
+    };
+}
+
+/**
+ * Drop starts that can no longer match anything, in place.
+ *
+ * WHY IT MATTERS BEYOND MEMORY. A start older than the tolerance is unreachable, but while
+ * it sits in the list it is still a CANDIDATE for the ambiguity test — so a stale entry can
+ * turn a perfectly clear pairing into a refusal, and an accumulating list makes that more
+ * likely the longer a session runs. Pruning is therefore part of the correctness of the
+ * join, not housekeeping.
+ *
+ * Mutates rather than returning a copy because the caller holds it in a ref that the native
+ * listener and the touch handler both read.
+ */
+export function pruneInteractionStarts<T extends InteractionStartContext>(
+    starts: T[],
+    now: number,
+    toleranceMs = CORRELATION_TOLERANCE_MS,
+): number {
+    let removed = 0;
+    for (let i = starts.length - 1; i >= 0; i--) {
+        const start = starts[i];
+        if (!start || now - start.occurredAt > toleranceMs) {
+            starts.splice(i, 1);
+            removed++;
         }
     }
-    return bestDelta <= toleranceMs ? best : undefined;
+    return removed;
 }
 
 /** Analytics is a projection of the same evidence; no second click is invented. */

package/src/features/journey/scrollContext.ts

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+
+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;
+  const n = node as { __nativeTag?: unknown; _nativeTag?: unknown };
+  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;
+}

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
+  );
+}