refactor: move touch commands to platform runtime

Author: thymikee

packages/contracts/package.json

@@ -300,6 +300,10 @@
       "types": "./src/type-text-runtime.ts",
       "default": "./src/type-text-runtime.ts"
     },
+    "./touch-runtime": {
+      "types": "./src/touch-runtime.ts",
+      "default": "./src/touch-runtime.ts"
+    },
     "./viewport-runtime": {
       "types": "./src/viewport-runtime.ts",
       "default": "./src/viewport-runtime.ts"

packages/contracts/src/facades/interaction.ts

@@ -14,6 +14,7 @@ export {
   resolveClickButton,
 } from '../click-button.ts';
 export type { ClickButton } from '../click-button.ts';
+export type { PressPointOptions } from '../interactor-types.ts';
 export type { ClipboardCommandResult } from '../clipboard.ts';
 export { COORDINATE_GESTURE_KINDS, GESTURE_KINDS, readGesturePayload } from '../gesture-input.ts';
 export type {

packages/contracts/src/facades/platform.ts

@@ -72,6 +72,7 @@ export {
   providerRuntimeOwner,
   runtimeOwnerKey,
   sameRuntimeOwner,
+  whenAdmitted,
 } from '../platform-runtime.ts';
 export type {
   BoundDeviceRuntime,
@@ -252,13 +253,30 @@ export type {
 export {
   bootTargetHeadlessUse,
   bootTargetUse,
+  capturedFillUse,
+  capturedHoverUse,
+  capturedLongPressUse,
+  capturedTapUse,
+  clickRuntimeUses,
   deviceBootRuntimeUses,
+  fillPointUse,
+  fillRuntimeUses,
+  hoverPointUse,
+  hoverRuntimeUses,
+  longPressPointUse,
+  longPressRuntimeUses,
+  pressRuntimeUses,
   resolveDeviceReadinessRuntimePlan,
+  resolveTouchRuntimePlan,
   appStateRuntimeUses,
   appStateUse,
   shutdownTargetUse,
+  tapPointUse,
+} from '../platform-runtime-operations.ts';
+export type {
+  DeviceReadinessRuntimePlan,
+  TouchRuntimePlan,
 } from '../platform-runtime-operations.ts';
-export type { DeviceReadinessRuntimePlan } from '../platform-runtime-operations.ts';
 export {
   bindLocalScreenshotInteractor,
   bindProviderScreenshotInteractor,
@@ -316,6 +334,25 @@ export {
   bindProviderTypeTextInteractor,
   typeTextRuntimeOperationFacts,
 } from '../type-text-runtime.ts';
+export {
+  bindLocalTouchInteractor,
+  bindProviderTouchInteractor,
+  HOVER_UNAVAILABLE_HINT,
+  pressJitter,
+  touchRuntimeOperationFacts,
+} from '../touch-runtime.ts';
+export type {
+  FillPointInput,
+  FillRefInput,
+  HoverPointInput,
+  HoverRefInput,
+  LongPressPointInput,
+  TapElementSelectorInput,
+  TapPointInput,
+  TapRefInput,
+  TouchRuntimeOperationFacts,
+  TouchRuntimeOperations,
+} from '../touch-runtime.ts';
 export type {
   LocalTypeTextInteractorResolver,
   ProviderTypeTextInteractorResolver,

packages/contracts/src/interaction-guarantees.ts

@@ -298,8 +298,8 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
   },
   'direct-ios-selector': {
     description:
-      'Simple press selectors on iOS are sent to the XCTest runner, which queries and taps natively without a daemon tree capture. Fill deliberately resolves through the runtime tree so AX-hostile text inputs carry typed target evidence into coordinate entry.',
-    commands: ['press'],
+      'Simple press and click selectors use the bound owner preferred tapElementSelector operation when its exact facts advertise it, querying and tapping without a daemon tree capture. Fill deliberately resolves through the runtime tree so AX-hostile text inputs carry typed target evidence into coordinate entry.',
+    commands: ['press', 'click'],
     guarantees: {
       disambiguation: {
         kind: 'delegated',
@@ -366,7 +366,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
     // 2026-07-04 while designing the #1088 retirement experiment, which this
     // finding dissolved: there is no iOS runner round trip to retire.
     description:
-      'click @ref / fill @ref / hover @ref dispatch to backend.tapTarget/fillTarget/hoverTarget (web provider clickRef/fillRef/hoverRef only; no mobile backend implements these) without runtime resolution when no non-default options are set. A zero-round-trip preflight (preflightNativeRefInteraction) runs the shared guards against the stored session snapshot node first; no snapshot / no usable rect makes the preflight a no-op.',
+      'click @ref / fill @ref / hover @ref dispatch through the bound touch operation, whose web runtime owner selects clickRef/fillRef/hoverRef internally; no mobile owner advertises native-ref support. The route bypasses runtime resolution when no non-default options are set. A zero-round-trip preflight (preflightNativeRefInteraction) runs the shared guards against the stored session snapshot node first; no snapshot / no usable rect makes the preflight a no-op.',
     commands: ['click', 'fill', 'hover'],
     guarantees: {
       disambiguation: {

packages/contracts/src/interactor-types.ts

@@ -65,6 +65,16 @@ export type ElementSelectorTapOptions = {
   expectedPoint?: Point;
 };
 
+export type PressPointOptions = Readonly<{
+  button: 'primary' | 'secondary' | 'middle';
+  count: number;
+  intervalMs: number;
+  holdMs: number;
+  jitterPx: number;
+  doubleTap: boolean;
+  surface?: SessionSurface;
+}>;
+
 /**
  * Legacy success text retained for compatibility when the XCTest runner used
  * the Maestro non-hittable coordinate fallback. Usage itself is carried by
@@ -126,7 +136,7 @@ export type TypeTextBackendResult = {
  *   to enter text unwitnessed.
  *
  * Closed set: the cloud interactor is its only producer and the boundary that
- * narrows it (readFillBackendResult, src/core/dispatch-interactions.ts) drops a
+ * narrows it (readFillBackendResult in the touch handler) drops a
  * value it cannot name.
  */
 export const CLOUD_TEXT_ENTRY_READINESS = ['focused-element', 'keyboard-shown'] as const;
@@ -252,6 +262,15 @@ export type Interactor = {
   openDevice(): Promise<void>;
   close(app: string): Promise<void>;
   tap(x: number, y: number): Promise<Record<string, unknown> | void>;
+  /** Complete point-press semantics for owners with fused series, alternate buttons, or surfaces. */
+  pressPoint?(point: Point, options: PressPointOptions): Promise<Record<string, unknown> | void>;
+  /** Alternate mouse buttons for owners that otherwise use the shared point-press series. */
+  alternateClick?(
+    point: Point,
+    button: 'secondary' | 'middle',
+  ): Promise<Record<string, unknown> | void>;
+  /** Owner-native ref routes; currently the managed web runtime is their only local owner. */
+  tapRef?(ref: string): Promise<Record<string, unknown> | void>;
   tapElementSelector?(selector: ElementSelectorTapOptions): Promise<Record<string, unknown> | void>;
   doubleTap(x: number, y: number): Promise<Record<string, unknown> | void>;
   longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
@@ -261,20 +280,17 @@ export type Interactor = {
    * and leave it undefined, which the `hover` command reports as unsupported.
    */
   hover?(x: number, y: number): Promise<Record<string, unknown> | void>;
+  hoverRef?(ref: string): Promise<Record<string, unknown> | void>;
   focus(x: number, y: number): Promise<Record<string, unknown> | void>;
   type(text: string, delayMs?: number): Promise<TypeTextBackendResult | void>;
-  fillElementSelector?(
-    selector: ElementSelectorTapOptions,
-    text: string,
-    delayMs?: number,
-  ): Promise<Record<string, unknown> | void>;
   fill(
     x: number,
     y: number,
     text: string,
     delayMs?: number,
     options?: { allowNonHittableCoordinateFallback?: boolean },
   ): Promise<Record<string, unknown> | void>;
+  fillRef?(ref: string, text: string, delayMs?: number): Promise<Record<string, unknown> | void>;
   scroll(
     direction: ScrollDirection,
     options?: ScrollExecutionOptions,

packages/contracts/src/platform-runtime-operations.ts

@@ -24,6 +24,7 @@ import type { HomeRuntimeOperations } from './home-runtime.ts';
 import type { OrientationRuntimeOperations } from './orientation-runtime.ts';
 import type { TvRemoteRuntimeOperations } from './tv-remote-runtime.ts';
 import type { KeyboardRuntimeOperations } from './keyboard-runtime.ts';
+import type { TouchRuntimeOperations } from './touch-runtime.ts';
 import type {
   DeviceReadinessRuntimeHost,
   DeviceReadinessRuntimeOperations,
@@ -65,6 +66,7 @@ export type PlatformRuntimeOperations = AppLogRuntimeOperations &
   OrientationRuntimeOperations &
   TvRemoteRuntimeOperations &
   KeyboardRuntimeOperations &
+  TouchRuntimeOperations &
   DeviceReadinessRuntimeOperations &
   DeviceShutdownRuntimeOperations &
   ApplicationLifecycleRuntimeOperations;
@@ -93,6 +95,81 @@ export const tvRemoteRuntimeUse = defineUse({ required: ['tvRemote'] });
 export const keyboardStatusUse = defineUse({ required: ['keyboardStatus'] });
 export const keyboardDismissUse = defineUse({ required: ['keyboardDismiss'] });
 export const keyboardEnterUse = defineUse({ required: ['keyboardEnter'] });
+export const tapPointUse = defineUse({ required: ['tapPoint'] });
+export const capturedTapUse = defineUse({
+  required: ['captureSnapshot', 'tapPoint'],
+  preferred: ['tapElementSelector', 'tapRef'],
+});
+export const longPressPointUse = defineUse({ required: ['longPressPoint'] });
+export const capturedLongPressUse = defineUse({
+  required: ['captureSnapshot', 'longPressPoint'],
+});
+export const hoverPointUse = defineUse({ required: ['hoverPoint'] });
+export const capturedHoverUse = defineUse({
+  required: ['captureSnapshot', 'hoverPoint'],
+  preferred: ['hoverRef'],
+});
+export const fillPointUse = defineUse({ required: ['fillPoint'] });
+export const capturedFillUse = defineUse({
+  required: ['captureSnapshot', 'fillPoint'],
+  preferred: ['fillRef'],
+});
+
+export const clickRuntimeUses = Object.freeze([tapPointUse, capturedTapUse] as const);
+export const pressRuntimeUses = clickRuntimeUses;
+export const longPressRuntimeUses = Object.freeze([
+  longPressPointUse,
+  capturedLongPressUse,
+] as const);
+export const hoverRuntimeUses = Object.freeze([hoverPointUse, capturedHoverUse] as const);
+export const fillRuntimeUses = Object.freeze([fillPointUse, capturedFillUse] as const);
+
+export type TouchRuntimePlan =
+  | Readonly<{ kind: 'tap-point'; operation: 'tapPoint'; use: typeof tapPointUse }>
+  | Readonly<{ kind: 'captured-tap'; operation: 'tapPoint'; use: typeof capturedTapUse }>
+  | Readonly<{
+      kind: 'long-press-point';
+      operation: 'longPressPoint';
+      use: typeof longPressPointUse;
+    }>
+  | Readonly<{
+      kind: 'captured-long-press';
+      operation: 'longPressPoint';
+      use: typeof capturedLongPressUse;
+    }>
+  | Readonly<{ kind: 'hover-point'; operation: 'hoverPoint'; use: typeof hoverPointUse }>
+  | Readonly<{
+      kind: 'captured-hover';
+      operation: 'hoverPoint';
+      use: typeof capturedHoverUse;
+    }>
+  | Readonly<{ kind: 'fill-point'; operation: 'fillPoint'; use: typeof fillPointUse }>
+  | Readonly<{ kind: 'captured-fill'; operation: 'fillPoint'; use: typeof capturedFillUse }>;
+
+export function resolveTouchRuntimePlan(
+  command: 'click' | 'press' | 'fill' | 'longpress' | 'hover',
+  requiresCapture: boolean,
+): TouchRuntimePlan {
+  switch (command) {
+    case 'click':
+    case 'press':
+      return requiresCapture
+        ? { kind: 'captured-tap', operation: 'tapPoint', use: capturedTapUse }
+        : { kind: 'tap-point', operation: 'tapPoint', use: tapPointUse };
+    case 'fill':
+      return requiresCapture
+        ? { kind: 'captured-fill', operation: 'fillPoint', use: capturedFillUse }
+        : { kind: 'fill-point', operation: 'fillPoint', use: fillPointUse };
+    case 'longpress':
+      return requiresCapture
+        ? { kind: 'captured-long-press', operation: 'longPressPoint', use: capturedLongPressUse }
+        : { kind: 'long-press-point', operation: 'longPressPoint', use: longPressPointUse };
+    case 'hover':
+      return requiresCapture
+        ? { kind: 'captured-hover', operation: 'hoverPoint', use: capturedHoverUse }
+        : { kind: 'hover-point', operation: 'hoverPoint', use: hoverPointUse };
+  }
+}
 const captureSnapshotWithCustomActionsUse = defineUse({
   required: ['captureSnapshot', 'captureSnapshotWithCustomActions'],
 });

packages/contracts/src/platform-runtime-unavailable.test.ts

@@ -33,6 +33,7 @@ test('generic unavailable binding preserves exact provider ownership and mode',
     viewport: { available: false, reason: 'unsupported-platform-leaf' },
     focus: { available: false, reason: 'unsupported-provider-mode' },
     typeText: { available: false, reason: 'unsupported-provider-mode' },
+    touch: { available: false, reason: 'unsupported-provider-mode' },
     elementText: { available: false, reason: 'unsupported-provider-mode' },
     back: { available: false, reason: 'unsupported-provider-mode' },
     home: { available: false, reason: 'unsupported-provider-mode' },

packages/contracts/src/platform-runtime-unavailable.ts

@@ -22,6 +22,7 @@ import { homeRuntimeOperationFacts } from './home-runtime.ts';
 import { orientationRuntimeOperationFacts } from './orientation-runtime.ts';
 import { tvRemoteRuntimeOperationFacts } from './tv-remote-runtime.ts';
 import { keyboardRuntimeOperationFacts } from './keyboard-runtime.ts';
+import { touchRuntimeOperationFacts } from './touch-runtime.ts';
 
 /**
  * A runtime-contract helper for provider ownership gaps. It never assigns lifecycle semantics:
@@ -39,6 +40,7 @@ export type UnavailablePlatformRuntimeFacts = Readonly<{
   viewport: RuntimeOperationUnavailability;
   focus: RuntimeOperationUnavailability;
   typeText: RuntimeOperationUnavailability;
+  touch: RuntimeOperationUnavailability;
   elementText: RuntimeOperationUnavailability;
   back: RuntimeOperationUnavailability;
   home: RuntimeOperationUnavailability;
@@ -92,6 +94,7 @@ export function createUnavailablePlatformRuntimeFacts(
     viewport,
     focus,
     typeText,
+    touch,
     elementText,
     back,
     home,
@@ -141,6 +144,16 @@ export function createUnavailablePlatformRuntimeFacts(
       ...viewportRuntimeOperationFacts({ setViewport: viewport }),
       ...focusRuntimeOperationFacts({ focus }),
       ...typeTextRuntimeOperationFacts({ type: typeText }),
+      ...touchRuntimeOperationFacts({
+        tap: touch,
+        tapRef: touch,
+        longPress: touch,
+        hover: touch,
+        hoverRef: touch,
+        fill: touch,
+        fillRef: touch,
+        tapElementSelector: touch,
+      }),
       ...elementTextRuntimeOperationFacts({ readTextAtPoint: elementText }),
       ...backRuntimeOperationFacts({ back }),
       ...homeRuntimeOperationFacts({ home }),
@@ -182,6 +195,7 @@ function freezeUnavailableFacts(
     // exact kinds, and one that cannot must say why rather than inherit a transport gap.
     focus: Object.freeze({ ...unavailable.focus }),
     typeText: Object.freeze({ ...unavailable.typeText }),
+    touch: Object.freeze({ ...unavailable.touch }),
     readiness: orNetwork(unavailable.readiness),
     shutdown: orNetwork(unavailable.shutdown),
     elementText: Object.freeze({ ...unavailable.elementText }),

packages/contracts/src/platform-runtime.ts

@@ -313,3 +313,11 @@ function unsupportedRuntimeOperation(key: string, fact: RuntimeOperationUnavaila
     hint: fact.hint,
   });
 }
+
+/** Include an operation binding only when the owning runtime's published fact admits it. */
+export function whenAdmitted<T extends object>(
+  fact: RuntimeOperationFact,
+  build: () => T,
+): T | Record<string, never> {
+  return fact.available ? build() : {};
+}

packages/contracts/src/scroll-command.ts

@@ -72,7 +72,7 @@ export function honoredScrollDurationMs(
 
 /**
  * `scroll` — the generic-route result built by `buildDispatchedScrollResult`
- * (src/core/dispatch-interactions.ts): the resolved direction, the edge-pass
+ * (src/core/dispatch-scroll.ts): the resolved direction, the edge-pass
  * bookkeeping for `top`/`bottom` scrolls, the honored distance/timing echo,
  * and the success message. Platform leaves add gesture-plan coordinates
  * (`x1`/`y1`/`x2`/`y2`, reference frame) on top; the output schema stays