refactor(interaction): say which tap point a path has in its resolver's type

The stage door carried two overload declarations and two parameter aliases to say that a path
handing in a resolver returning `Point` gets a `Point` back and a path without one gets `null`.
One constrained generic — `TPoint extends Point | null` on a resolver every path must pass — says
exactly that, with the native-ref fast path writing its own nullability into its resolver instead
of into a signature above the function it calls. No cast, no branch that cannot be reached.

Also removes ceremony the previous commit left behind: the guard rebound `params.tapPoint` to a
local for one use, and the runtime cases lifted the keyboard off the bottom edge twice, once
through a translation knob with one caller and once inline with the offset spelled out again.

Author: thymikee

src/commands/interaction/runtime/keyboard-occlusion.test.ts

@@ -14,19 +14,26 @@ import { createInteractionDevice } from './__tests__/test-utils/index.ts';
 
 const TAB_BAR_RECT: Rect = { x: 148, y: 791, width: 104, height: 83 };
 
-/** The contract fixture with its app-owned rects moved: the variants stay one tree, not copies. */
-function keyboardTree(params: { tabRect?: Rect; keyboardOwnedDy?: number } = {}): SnapshotState {
-  if (!params.tabRect && params.keyboardOwnedDy === undefined)
-    return keyboardCoveredTabBarSnapshot();
+/** The contract fixture with its app-owned button moved, so the variants stay one tree, not copies. */
+function keyboardTree(params: { tabRect?: Rect } = {}): SnapshotState {
+  const tabRect = params.tabRect;
+  if (!tabRect) return keyboardCoveredTabBarSnapshot();
   return makeSnapshotState(
-    keyboardCoveredTabBarSnapshot().nodes.map((node) => {
-      if (params.tabRect && node.index === 1) return { ...node, rect: params.tabRect };
-      const keyboardOwned = node.type === 'Keyboard' || node.type === 'Key';
-      if (params.keyboardOwnedDy !== undefined && keyboardOwned && node.rect) {
-        return { ...node, rect: { ...node.rect, y: node.rect.y + params.keyboardOwnedDy } };
-      }
-      return node;
-    }),
+    keyboardCoveredTabBarSnapshot().nodes.map((node) =>
+      node.index === 1 ? { ...node, rect: tabRect } : node,
+    ),
+  );
+}
+
+/**
+ * Keyboard-owned rects hauled above the docking budget: the tree stops describing a keyboard the
+ * bottom of the screen belongs to, which is what the app-drawn-keypad and aim cases measure against.
+ */
+function liftKeyboardOffBottomEdge(nodes: SnapshotState['nodes']): SnapshotState['nodes'] {
+  return nodes.map((node) =>
+    node.rect && (node.type === 'Keyboard' || node.type === 'Key')
+      ? { ...node, rect: { ...node.rect, y: node.rect.y - 560 } }
+      : node,
   );
 }
 
@@ -119,7 +126,8 @@ test('no keyboard in the tree means nothing to refuse', async () => {
 
 test('an app-drawn keypad that stops short of the bottom edge is not the system keyboard', async () => {
   const calls: Point[] = [];
-  const device = tappedDevice(keyboardTree({ keyboardOwnedDy: -560 }), calls);
+  const appOwnedKeypad = makeSnapshotState(liftKeyboardOffBottomEdge(keyboardTree().nodes));
+  const device = tappedDevice(appOwnedKeypad, calls);
 
   await device.interactions.click(ref('@e2'), { session: 'default' });
 
@@ -143,9 +151,8 @@ test('a coordinate behind the keyboard taps anyway and discloses the reason', as
 });
 
 test('the guard reads the point the interaction dispatches, not the rect center', async () => {
-  const calls: Point[] = [];
-  // The Form button's own center sits 3 pt above the key plane, but its interactive child owns that
-  // upper region, so the aim point the tap dispatches is pushed down into the keyboard's band.
+  // The Form button's own center sits 3 pt above the key plane, and its interactive child owns that
+  // upper region, so the point the tap dispatches is pushed down into the keyboard's band.
   const aimShifted = makeSnapshotState([
     ...keyboardCoveredTabBarSnapshot().nodes,
     {
@@ -157,41 +164,29 @@ test('the guard reads the point the interaction dispatches, not the rect center'
       rect: { x: 148, y: 500, width: 104, height: 83 },
       hittable: true,
     },
-  ]);
-  const shifted = aimShifted.nodes.map((node) =>
+  ]).nodes.map((node) =>
     node.index === 1 ? { ...node, rect: { x: 148, y: 500, width: 104, height: 160 } } : node,
   );
-  const device = tappedDevice(makeSnapshotState(shifted), calls);
 
+  const calls: Point[] = [];
   await assert.rejects(
-    () => device.interactions.click(ref('@e2'), { session: 'default' }),
-    (error: unknown) => {
-      assert.ok(error instanceof Error);
-      assert.match(error.message, /Ref @e2 is behind the visible keyboard/);
-      return true;
-    },
+    () =>
+      tappedDevice(makeSnapshotState(aimShifted), calls).interactions.click(ref('@e2'), {
+        session: 'default',
+      }),
+    /Ref @e2 is behind the visible keyboard/,
   );
   assert.deepEqual(calls, []);
 
-  // The same tree with its keypad lifted off the bottom edge shows where that tap was aiming: below
-  // the key plane, which is what makes this the aim point's refusal rather than the center's.
-  const aimCalls: Point[] = [];
-  const clearDevice = tappedDevice(
-    makeSnapshotState(
-      shifted.map((node) =>
-        node.type === 'Keyboard' || node.type === 'Key'
-          ? { ...node, rect: { ...node.rect!, y: node.rect!.y - 560 } }
-          : node,
-      ),
-    ),
-    aimCalls,
-  );
-  await clearDevice.interactions.click(ref('@e2'), { session: 'default' });
-  assert.equal(aimCalls.length, 1);
-  assert.ok(
-    (aimCalls[0]?.y ?? 0) > 583,
-    `expected the dispatched aim below the key plane at 583, got ${aimCalls[0]?.y}`,
-  );
+  // The same tree with its keyboard hauled off the bottom edge shows where that tap was aiming: below
+  // the key plane, which is what makes this the dispatched point's refusal rather than the center's.
+  const aim: Point[] = [];
+  await tappedDevice(
+    makeSnapshotState(liftKeyboardOffBottomEdge(aimShifted)),
+    aim,
+  ).interactions.click(ref('@e2'), { session: 'default' });
+  assert.equal(aim.length, 1);
+  assert.ok((aim[0]?.y ?? 0) > 583, `expected the dispatched point below 583, got ${aim[0]?.y}`);
 });
 
 test('a coordinate on a reported key is the keyboard the caller asked for', async () => {

src/commands/interaction/runtime/keyboard-occlusion.ts

@@ -31,19 +31,18 @@ export function assertTapTargetClearOfVisibleKeyboard(params: {
   /** How the caller named the target, e.g. `Ref @e40` or `Selector text=Form`. */
   label: string;
   /**
-   * Where this interaction aims: the point a point-dispatching path resolved through the same
-   * resolver it dispatches with, or the rect center for the native-ref fast path, which hands the
-   * element to the platform and lets it pick. Null when the node has no measurable aim.
+   * The point this interaction taps with: the one a coordinate-dispatching path resolved through the
+   * same resolver it dispatches with, or the rect center for the native-ref fast path, which hands the
+   * element to the platform and lets it choose. Null when the node has no measurable point.
    */
   tapPoint: Point | null;
 }): void {
   const targetRect = params.node.rect;
-  const tapPoint = params.tapPoint;
-  if (!targetRect || !tapPoint) return;
+  if (!targetRect || !params.tapPoint) return;
   const occlusion = resolveKeyboardTapOcclusion({
     nodes: params.nodes,
     viewport: createSnapshotVisibility(params.nodes).resolveViewport(targetRect),
-    point: tapPoint,
+    point: params.tapPoint,
     node: params.node,
   });
   if (occlusion.kind !== 'occluded') return;

src/commands/interaction/runtime/resolution.ts

@@ -654,30 +654,20 @@ function describeNonHittableTarget(
  * ref, and the native-ref preflight — enters them here, which is what keeps the native-ref fast
  * path from succeeding on a target the shared rules would refuse.
  *
- * A path that dispatches a coordinate hands in its own aim resolver and gets the measured point
- * back, so the keyboard guard reads the coordinate the interaction will actually send and the
- * dispatch does not derive a second one. The native-ref fast path dispatches by ref and has no
- * point to measure: its guard reads the rect center, which is the aim the platform picks.
+ * Each path hands in the resolver that produces the point it taps with, and taps the point that
+ * comes back, so the keyboard guard measures the coordinate the interaction is actually made of and no
+ * path derives a second one. A path whose point can fail to exist — the native-ref fast path taps by
+ * ref, reading the rect center the platform aims at — says so in its resolver's return type.
  */
-type InteractionStageParams = {
+async function runInteractionPipelineStages<TPoint extends Point | null>(params: {
   policy: SelectorPipelinePolicy;
   nodes: SnapshotState['nodes'];
   node: SnapshotNode;
   action: InteractionAction;
   label: string;
   hooks: SelectorPipelineHooks;
-};
-type InteractionStageOutcome = { node: SnapshotNode };
-
-async function runInteractionPipelineStages(
-  params: InteractionStageParams & { resolveTapPoint: (node: SnapshotNode) => Point },
-): Promise<InteractionStageOutcome & { tapPoint: Point }>;
-async function runInteractionPipelineStages(
-  params: InteractionStageParams & { resolveTapPoint?: undefined },
-): Promise<InteractionStageOutcome & { tapPoint: null }>;
-async function runInteractionPipelineStages(
-  params: InteractionStageParams & { resolveTapPoint?: (node: SnapshotNode) => Point },
-): Promise<InteractionStageOutcome & { tapPoint: Point | null }> {
+  resolveTapPoint: (node: SnapshotNode) => TPoint;
+}): Promise<{ node: SnapshotNode; tapPoint: TPoint }> {
   const target = await runNodePipelineStages(
     params.policy,
     params.nodes,
@@ -691,9 +681,7 @@ async function runInteractionPipelineStages(
       action: params.action,
     });
   }
-  const tapPoint = params.resolveTapPoint
-    ? params.resolveTapPoint(target.node)
-    : (resolveRectCenter(target.node.rect) ?? null);
+  const tapPoint = params.resolveTapPoint(target.node);
   assertTapTargetClearOfVisibleKeyboard({
     nodes: params.nodes,
     node: target.node,
@@ -1021,7 +1009,7 @@ export async function preflightNativeRefInteraction(
   // `resolvedTarget` whatever the command: its `none` promotion is what holds
   // ADR 0011's "the preflight never changes which element the backend acts on".
   const pipeline = SELECTOR_PIPELINE_POLICIES.resolvedTarget;
-  // #1542: dispatches by REF, not coordinate, so no point to re-derive — but
+  // #1542: dispatches by REF, not coordinate, so no point is re-derived for the dispatch — but
   // evidence/annotation below still describes the returned (visible) node.
   const { node: visibleNode } = await runInteractionPipelineStages({
     policy: pipeline,
@@ -1036,6 +1024,7 @@ export async function preflightNativeRefInteraction(
           pipeline,
         }),
     },
+    resolveTapPoint: (node) => resolveRectCenter(node.rect) ?? null,
   });
   return {
     ...describeNonHittableTarget(visibleNode, action),