refactor: tighten unified gesture seams

Author: thymikee

src/contracts/gesture-normalization.ts

@@ -2,6 +2,7 @@ import type { Point } from '../kernel/snapshot.ts';
 import { AppError } from '../kernel/errors.ts';
 import type { SwipePreset } from './scroll-gesture.ts';
 import { readGesturePayload, type GesturePayload } from './gesture-input.ts';
+import { GESTURE_FLING_DEFAULT_DISTANCE } from './gesture-plan.ts';
 import type { GestureSemanticInput } from './gesture-plan-types.ts';
 
 export type GestureCompatibilityRule = 'swipe-duration' | 'fling-duration' | 'rotate-velocity';
@@ -101,12 +102,16 @@ export function gesturePayloadToPositionals(input: GesturePayload): string[] {
         input.durationMs,
       ]);
     case 'fling':
+      // `.ad` positionals cannot encode an empty distance slot. Preserve the
+      // planner default when a deprecated duration must occupy the next slot.
       return compact([
         input.kind,
         input.direction,
         input.origin.x,
         input.origin.y,
-        input.durationMs === undefined ? input.distance : (input.distance ?? 180),
+        input.durationMs === undefined
+          ? input.distance
+          : (input.distance ?? GESTURE_FLING_DEFAULT_DISTANCE),
         input.durationMs,
       ]);
     case 'swipe':
@@ -166,7 +171,10 @@ export function normalizePublicGesture(input: GesturePayload): NormalizedPublicG
           gesture: {
             intent: 'pan',
             origin: input.origin,
-            delta: directionDelta(input.direction, input.distance ?? 180),
+            delta: directionDelta(
+              input.direction,
+              input.distance ?? GESTURE_FLING_DEFAULT_DISTANCE,
+            ),
             durationMs: input.durationMs,
           },
           deprecations: [

src/contracts/gesture-plan.ts

@@ -15,6 +15,7 @@ export * from './gesture-plan-types.ts';
 
 export const GESTURE_SAMPLE_INTERVAL_MS = 16;
 export const GESTURE_INITIAL_ANGLE_DEGREES = -90;
+export const GESTURE_FLING_DEFAULT_DISTANCE = 180;
 
 const GESTURE_INITIAL_SPAN_RATIO = 0.25;
 const GESTURE_PINCH_INITIAL_SPAN_RATIO = 0.4;
@@ -117,7 +118,10 @@ function buildFlingPlan(
     );
   }
   const start = finitePoint(input.origin, 'gesture fling origin');
-  const distance = positiveNumber(input.distance ?? 180, 'gesture fling distance');
+  const distance = positiveNumber(
+    input.distance ?? GESTURE_FLING_DEFAULT_DISTANCE,
+    'gesture fling distance',
+  );
   return buildSinglePointerPlan(
     'fling',
     start,

src/core/dispatch.ts

@@ -44,17 +44,7 @@ export async function dispatchCommand(
   outPath?: string,
   context?: DispatchContext,
 ): Promise<Record<string, unknown> | void> {
-  const runnerCtx: RunnerContext = {
-    requestId: context?.requestId,
-    appBundleId: context?.appBundleId,
-    verbose: context?.verbose,
-    logPath: context?.logPath,
-    traceLogPath: context?.traceLogPath,
-    iosXctestrunFile: context?.iosXctestrunFile,
-    iosXctestDerivedDataPath: context?.iosXctestDerivedDataPath,
-    iosXctestEnvDir: context?.iosXctestEnvDir,
-    runnerLeaseContext: context?.runnerLeaseContext,
-  };
+  const runnerCtx = runnerContextFromDispatchContext(context);
   const interactor = await getInteractor(device, runnerCtx);
   emitDiagnostic({
     level: 'debug',
@@ -90,17 +80,7 @@ export async function dispatchGesturePlan(
   plan: GesturePlan,
   context?: DispatchContext,
 ): Promise<Record<string, unknown> | void> {
-  const interactor = await getInteractor(device, {
-    requestId: context?.requestId,
-    appBundleId: context?.appBundleId,
-    verbose: context?.verbose,
-    logPath: context?.logPath,
-    traceLogPath: context?.traceLogPath,
-    iosXctestrunFile: context?.iosXctestrunFile,
-    iosXctestDerivedDataPath: context?.iosXctestDerivedDataPath,
-    iosXctestEnvDir: context?.iosXctestEnvDir,
-    runnerLeaseContext: context?.runnerLeaseContext,
-  });
+  const interactor = await getInteractor(device, runnerContextFromDispatchContext(context));
   if (!interactor.performGesture) {
     throw new AppError('UNSUPPORTED_OPERATION', 'Gesture execution is unavailable');
   }
@@ -111,7 +91,12 @@ export async function dispatchGestureViewport(
   device: DeviceInfo,
   context?: DispatchContext,
 ): Promise<Rect | undefined> {
-  const interactor = await getInteractor(device, {
+  const interactor = await getInteractor(device, runnerContextFromDispatchContext(context));
+  return await interactor.gestureViewport?.();
+}
+
+function runnerContextFromDispatchContext(context?: DispatchContext): RunnerContext {
+  return {
     requestId: context?.requestId,
     appBundleId: context?.appBundleId,
     verbose: context?.verbose,
@@ -121,8 +106,7 @@ export async function dispatchGestureViewport(
     iosXctestDerivedDataPath: context?.iosXctestDerivedDataPath,
     iosXctestEnvDir: context?.iosXctestEnvDir,
     runnerLeaseContext: context?.runnerLeaseContext,
-  });
-  return await interactor.gestureViewport?.();
+  };
 }
 
 type DispatchCommand = DescriptorDispatchCommandName;

src/daemon/handlers/interaction-gesture.ts

@@ -3,6 +3,7 @@ import {
   gesturePayloadToPositionals,
   normalizePublicGesture,
   normalizePublicSwipeMotion,
+  type GestureDeprecation,
   type SwipePayload,
 } from '../../contracts/gesture-normalization.ts';
 import { requireGestureSupported } from '../../core/capabilities.ts';
@@ -17,139 +18,138 @@ import { readOptionalInteger } from '../../kernel/input-validation.ts';
 import type { Point } from '../../kernel/snapshot.ts';
 import { isActiveProviderDevice } from '../../provider-device-runtime.ts';
 import { sleep } from '../../utils/timeouts.ts';
-import type { DaemonResponse } from '../types.ts';
+import type { DaemonResponse, SessionState } from '../types.ts';
 import { ensureAndroidBlockingSystemDialogReady } from '../android-system-dialog.ts';
 import type { InteractionHandlerParams } from './interaction-common.ts';
 import { finalizeTouchInteraction } from './interaction-common.ts';
 import { createInteractionRuntime } from './interaction-runtime.ts';
 import type { CaptureSnapshotForSession } from './interaction-snapshot.ts';
 import { noActiveSessionError } from './response.ts';
 
+type GestureHandlerParams = InteractionHandlerParams & {
+  captureSnapshotForSession: CaptureSnapshotForSession;
+};
+
+type GestureRuntime = ReturnType<typeof createInteractionRuntime>;
+type GestureRuntimeResult = Awaited<ReturnType<GestureRuntime['interactions']['gesture']>>;
+
+type GestureInteractionOutcome = {
+  positionals: string[];
+  flags: InteractionHandlerParams['req']['flags'];
+  responseData: Record<string, unknown>;
+  recordingResultExtra?: Record<string, unknown>;
+};
+
 export async function dispatchGestureViaRuntime(
-  params: InteractionHandlerParams & {
-    captureSnapshotForSession: CaptureSnapshotForSession;
-  },
+  params: GestureHandlerParams,
 ): Promise<DaemonResponse> {
-  const session = params.sessionStore.get(params.sessionName);
-  if (!session) return noActiveSessionError();
-  const startedAt = Date.now();
-  try {
+  return await dispatchGestureInteraction(params, 'gesture', async (session) => {
     const input = readGesturePayload(params.req.input);
     const normalized = normalizePublicGesture(input);
     requireGestureSupported(normalized.gesture, session.device);
-    const providerDevice = isActiveProviderDevice(session.device);
-    const readiness = providerDevice
-      ? ({ status: 'clear' } as const)
-      : await ensureAndroidBlockingSystemDialogReady({
-          session,
-          command: 'gesture',
-          phase: 'before-command',
-        });
     const result = await createInteractionRuntime(params).interactions.gesture({
       session: params.sessionName,
       requestId: params.req.meta?.requestId,
       gesture: normalized.gesture,
     });
-    if (!providerDevice) {
-      await ensureAndroidBlockingSystemDialogReady({
-        session,
-        command: 'gesture',
-        phase: 'after-command',
-      });
-    }
-    const responseData: Record<string, unknown> = {
-      kind: result.kind,
-      durationMs: result.durationMs,
-      pointerCount: result.pointerCount,
-      from: result.from,
-      to: result.to,
-      ...(result.backendResult ?? {}),
-      ...(normalized.deprecations.length > 0 ? { deprecations: normalized.deprecations } : {}),
-      message: result.message,
-    };
-    if (readiness.status === 'recovered') responseData.warning = readiness.warning;
-    return finalizeTouchInteraction({
-      session,
-      sessionStore: params.sessionStore,
-      command: 'gesture',
-      actionCommand: 'gesture',
+    return {
       positionals: gesturePayloadToPositionals(input),
       flags: gestureReplayFlags(input, params.req.flags),
-      result: {
-        ...responseData,
-        ...(input.kind === 'pinch' ? { scale: input.scale } : {}),
-      },
-      responseData,
-      actionStartedAt: startedAt,
-      actionFinishedAt: Date.now(),
-    });
-  } catch (error) {
-    return { ok: false, error: normalizeError(error) };
-  }
+      responseData: gestureResponseData(result, normalized.deprecations),
+      ...(input.kind === 'pinch' ? { recordingResultExtra: { scale: input.scale } } : {}),
+    };
+  });
 }
 
 export async function dispatchSwipeViaRuntime(
-  params: InteractionHandlerParams & {
-    captureSnapshotForSession: CaptureSnapshotForSession;
-  },
+  params: GestureHandlerParams,
 ): Promise<DaemonResponse> {
-  const session = params.sessionStore.get(params.sessionName);
-  if (!session) return noActiveSessionError();
-  const startedAt = Date.now();
-  try {
+  return await dispatchGestureInteraction(params, 'swipe', async (session) => {
     const input = readSwipeInput(params.req.input);
     requireGestureSupported(normalizePublicSwipeMotion(input).gesture, session.device);
     const count = input.count ?? 1;
     const pauseMs = input.pauseMs ?? 0;
     const pattern = input.pattern ?? 'one-way';
+    const runtime = createInteractionRuntime(params);
+    const result = await runSwipeRepetitions(runtime, params, input, count, pauseMs, pattern);
+    return {
+      positionals: swipeReplayPositionals(input),
+      flags: params.req.flags,
+      responseData: gestureResponseData(result, result.deprecations ?? [], {
+        count,
+        pauseMs,
+        pattern,
+      }),
+    };
+  });
+}
+
+async function dispatchGestureInteraction(
+  params: GestureHandlerParams,
+  command: 'gesture' | 'swipe',
+  run: (session: SessionState) => Promise<GestureInteractionOutcome>,
+): Promise<DaemonResponse> {
+  const session = params.sessionStore.get(params.sessionName);
+  if (!session) return noActiveSessionError();
+  const actionStartedAt = Date.now();
+  try {
     const providerDevice = isActiveProviderDevice(session.device);
     const readiness = providerDevice
       ? ({ status: 'clear' } as const)
       : await ensureAndroidBlockingSystemDialogReady({
           session,
-          command: 'swipe',
+          command,
           phase: 'before-command',
         });
-    const runtime = createInteractionRuntime(params);
-    const result = await runSwipeRepetitions(runtime, params, input, count, pauseMs, pattern);
+    const outcome = await run(session);
     if (!providerDevice) {
       await ensureAndroidBlockingSystemDialogReady({
         session,
-        command: 'swipe',
+        command,
         phase: 'after-command',
       });
     }
-    const responseData: Record<string, unknown> = {
-      kind: result.kind,
-      durationMs: result.durationMs,
-      pointerCount: result.pointerCount,
-      from: result.from,
-      to: result.to,
-      count,
-      pauseMs,
-      pattern,
-      ...(result.backendResult ?? {}),
-      ...(result.deprecations ? { deprecations: result.deprecations } : {}),
-      message: result.message,
-    };
-    if (readiness.status === 'recovered') responseData.warning = readiness.warning;
+    const responseData = { ...outcome.responseData };
+    if (readiness.status === 'recovered') {
+      const existingWarning =
+        typeof responseData.warning === 'string' ? `${responseData.warning} ` : '';
+      responseData.warning = `${existingWarning}${readiness.warning}`;
+    }
     return finalizeTouchInteraction({
       session,
       sessionStore: params.sessionStore,
-      command: 'swipe',
-      actionCommand: 'swipe',
-      positionals: swipeReplayPositionals(input),
-      flags: params.req.flags,
-      result: responseData,
+      command,
+      actionCommand: command,
+      positionals: outcome.positionals,
+      flags: outcome.flags,
+      result: { ...responseData, ...(outcome.recordingResultExtra ?? {}) },
       responseData,
-      actionStartedAt: startedAt,
+      actionStartedAt,
       actionFinishedAt: Date.now(),
     });
   } catch (error) {
     return { ok: false, error: normalizeError(error) };
   }
 }
 
+function gestureResponseData(
+  result: GestureRuntimeResult,
+  deprecations: readonly GestureDeprecation[],
+  extra: Record<string, unknown> = {},
+): Record<string, unknown> {
+  return {
+    kind: result.kind,
+    durationMs: result.durationMs,
+    pointerCount: result.pointerCount,
+    from: result.from,
+    to: result.to,
+    ...extra,
+    ...(result.backendResult ?? {}),
+    ...(deprecations.length > 0 ? { deprecations } : {}),
+    message: result.message,
+  };
+}
+
 function readSwipeInput(input: unknown): SwipePayload {
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
     throw new AppError('INVALID_ARGS', 'swipe requires structured object input');