Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
55.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file touch.ts
 * @input Uses a Playwright `Page` (Chromium or WebKit) and a touch script from
 *   ./scripts
 * @output `touchDriver(page)` — plays touch scripts as REAL browser touch input
 *   — and `installInputLog` / `readInputLog`, the page-side record of what the
 *   page actually received.
 * @position The input half of every interaction proof. Untrusted DOM events
 *   are not input: they never start native scrolling, never claim a gesture,
 *   and a component can tell them apart (`isTrusted`). Both drivers here go
 *   through the engine's own input pipeline instead.
 *
 * Chromium: CDP `Input.dispatchTouchEvent` with an explicit `timestamp` per
 *   event. The page's `event.timeStamp` IS that timestamp, whatever the
 *   dispatch latency, so a velocity profile reaches the page exactly. The
 *   events go through the compositor's gesture detection: native scrolling,
 *   flings (velocity from those timestamps), `touch-action`, pointer events
 *   and `pointercancel` all behave as for a finger.
 *
 * WebKit (Playwright's Linux build): the engine's own inspector command
 *   `Input.dispatchTouchEvent` on the page proxy. Touches and the pointer
 *   events derived from them are trusted and cancelable, multi-touch works.
 *   Limits, measured with WebKit 26.5: no timestamp parameter (the page sees
 *   the real dispatch time, so velocity comes from real-time pacing: within
 *   ~1 ms on an idle runner; after a slow dispatch each step waits for its
 *   gap, less 2 ms, after WebKit answered the step before, so a stall
 *   stretches the gesture instead of bunching it, unless a `'schedule'` play
 *   watches each step, `onEvent`);
 *   integer coordinates only; no native scrolling, fling or pinch-zoom from
 *   these touches; a `touchstart` lists only the fingers that landed in it
 *   (pointer events are exact); no click synthesised from a raw touch sequence (use
 *   `tap`, which dispatches WebKit's tap gesture and does produce the
 *   compatibility mouse events and click). The command is reached through
 *   Playwright's in-process server object, so it needs a locally launched
 *   browser (the default), not a remote `connect()`.
 *
 * SYNC: Keep the engine limits above equal to the README's table and to the
 *   harness self-test (../src/harness.interaction.browser.spec.ts). Keep
 *   `coreRelease` equal to Core's filter
 *   (/packages/core/src/gestures/VelocityTracker.ts); Core's
 *   VelocityTracker.harness.test.ts compares the two.
 */

import type {CDPSession, JSHandle, Page} from '@playwright/test';
import {FRAME_STARVATION_MS} from './frame-starvation';
import {
  toTouchEvents,
  type Finger,
  type Point,
  type TouchEventStep,
  type TouchScript,
} from './scripts';
import {
  armInputRun,
  HELD_BACK_MS,
  installInputStart,
  installInputStartBeforeLoad,
  type InputRun,
} from './webInput';

export type Engine = 'chromium' | 'webkit';

/**
 * How real-time pacing catches up after a slow dispatch (`PlayOptions.pacing`):
 * `'schedule'` sends each event at its scripted time from the start, and
 * `'spacing'` its scripted interval after the event before it left. Under
 * `'spacing'` an event also waits for its interval, less ANSWER_SLACK_MS,
 * after the engine answered the event before. WebKit stamps a touch no later
 * than its answer, so a stall stretches the gesture instead of bunching it.
 * A WebKit `'schedule'` play waits for the answer too.
 */
export type TouchPacing = 'schedule' | 'spacing';

/**
 * The answer time, ms, under which a touch play keeps the script's spacing
 * exactly; a slower answer stretches the next gap. A page that stamps
 * touches on arrival reads no gap shorter than the script's by more than
 * this (see `pacedDeadline`).
 */
export const ANSWER_SLACK_MS = 2;

/**
 * The release filter's stillness interval, 40 ms: a contact that has not
 * moved for longer than this before it lifts releases at 0.
 *
 * SYNC: Keep equal to `UIKIT_VELOCITY.stillness` in
 *   packages/core/src/motion/uikit/gestures.ts.
 */
export const TOUCH_STILLNESS_MS = 40;

/**
 * The newest move's share of the release velocity; the move before it
 * carries the rest.
 *
 * SYNC: Keep equal to `UIKIT_VELOCITY.currentWeight` in
 *   packages/core/src/motion/uikit/gestures.ts.
 */
export const TOUCH_RELEASE_NEWEST_WEIGHT = 0.2;

/**
 * The newest pan value's share of a scrolling surface's release, such as a
 * pager's; the pan value before it carries the rest (`PlayOptions.release`).
 *
 * SYNC: Keep equal to `UIKIT_VELOCITY.scrollReleaseWeight` in
 *   packages/core/src/motion/uikit/gestures.ts.
 */
export const TOUCH_SCROLL_RELEASE_NEWEST_WEIGHT = 0.25;

/**
 * Which of Core's release filters a page reads (`PlayOptions.release`): a
 * dragged surface's (`'pan'`) or a scrolling surface's, such as a pager's
 * (`'scroll'`).
 */
export type TouchReleaseFilter = 'pan' | 'scroll';

export interface PlayOptions {
  /**
   * Pace dispatch on the wall clock so each event leaves at its scripted time
   * (default true). Required in WebKit for a velocity to mean anything; in
   * Chromium the page sees the scripted timestamps either way, but native
   * behaviors that run on the compositor clock (a fling) want real pacing.
   */
  readonly realtime?: boolean;
  /**
   * How real-time pacing catches up after a slow dispatch (default
   * `'schedule'`; see `TouchPacing`). A proof whose result depends on a
   * release velocity (a flick, a coast) passes `'spacing'`: on a driver
   * without scripted timestamps the page reads the velocity from when events
   * arrive, and `'spacing'` keeps each gap from the event before even in a
   * play that watches each step. There, a paced play reads the release as
   * the page did once its last event is out (the lift's
   * `PlayedEvent.release`). It throws when the
   * page read a resting finger where the script moves, a throw where the
   * script rests, or fewer than two moves. Given `releaseTolerance`, it also
   * throws when the page's release strays further than that share. The error
   * is `TouchLiftStallError` when the play's own `onEvent` held the lift back.
   * It is `TouchPageStallError` when the page's own touch and pointer
   * listeners held an event back. It is `TouchStarvationError` when the page
   * drew no frame across the late gap and no page work held the event, else
   * `TouchPacingError` (see `touchPacingFault`). A `'spacing'` play also
   * throws when the page received fewer touch events than it sent; any other
   * play is then not judged.
   */
  readonly pacing?: TouchPacing;
  /**
   * How far the page's release may stray from the script's, as a share of
   * it, before a paced play fails. WebKit delivers touches at its own
   * cadence, so the release a page reads strays widely from a fast script's:
   * a proof that depends on the exact release gives one; a proof that only
   * needs a throw reads the page's release from the lift.
   */
  readonly releaseTolerance?: number;
  /**
   * The proof reads no release from this play's lift, such as a pinch's end
   * (default false). Then the play does not judge the release its page read
   * (see `pacing`).
   */
  readonly releaseUnread?: boolean;
  /**
   * Which release the page reads (default `'pan'`, a dragged surface's). A
   * scrolling surface, such as a pager, reads `'scroll'`: Core's
   * `scrollVelocity` blends the newest pan value with the one before it.
   */
  readonly release?: TouchReleaseFilter;
  /**
   * The thresholds the component under test decides on: a release speed it
   * pages from (`releasePxPerS`), a hold it catches after (`holdMs`). The
   * play fails by name when the page read the release on the other side of
   * a threshold from the script. The first finger's hold from touch-down to
   * lift fails the same way. Then the proof never judges a gesture the page
   * did not receive. Only a driver whose page stamps touches on arrival
   * (WebKit) judges them.
   */
  readonly boundaries?: {
    readonly releasePxPerS?: number;
    readonly holdMs?: number;
  };
  /**
   * Called after each event is dispatched, before the next one (storyboards).
   * The next event waits for it, so page work here delays that event by a
   * round trip. On a page that stamps touches on arrival, that delay before a
   * lift can read as a resting finger. Record what the page did in a listener
   * of its own instead.
   */
  readonly onEvent?: (
    step: TouchEventStep,
    index: number,
  ) => Promise<void> | void;
}

export interface PlayedEvent extends TouchEventStep {
  /** Wall-clock milliseconds (epoch) at which the event was dispatched. */
  readonly dispatchedAt: number;
  /**
   * Wall-clock milliseconds (epoch) at which the dispatch command returned:
   * the page has the event by then.
   */
  readonly returnedAt: number;
  /**
   * When the event left, on the clock a play paces on: the test process's
   * `performance.now()`, ms, to a fraction of a millisecond.
   */
  readonly pacedSentAt: number;
  /** When the dispatch command returned, on that same clock, ms. */
  readonly pacedReturnedAt: number;
  /** The timestamp handed to the engine, epoch ms (Chromium only). */
  readonly timestamp: number | null;
  /**
   * On a paced play's lift, where the page reads arrival times: the release
   * the page read and the script's, px/s.
   */
  readonly release?: {
    readonly pagePxPerS: number;
    readonly scriptPxPerS: number;
  };
}

export interface TouchDriver {
  readonly engine: Engine;
  /** True when the page's `event.timeStamp` follows the script exactly. */
  readonly scriptedTimestamps: boolean;
  /** True when these touches can scroll, fling and pinch-zoom natively. */
  readonly drivesNativeGestures: boolean;
  /**
   * True when lifting one finger while others stay down reaches the page as
   * iOS sends it: a `touchend` whose `touches` still lists the fingers down.
   * Skip such proofs with `PARTIAL_LIFT_SKIP` where it is false.
   */
  readonly partialLifts: boolean;
  /** Plays a script; resolves when its last event has been dispatched. */
  play(script: TouchScript, options?: PlayOptions): Promise<PlayedEvent[]>;
  /** A tap through the engine's tap path (WebKit synthesises click only from this). */
  tap(at: Point): Promise<void>;
  /**
   * Puts a finger down at `at` and keeps it there: only the touch-down is
   * sent, as a play's first step. The finger moves and lifts through the
   * handle, each call one event. Its timing is the caller's, so it is never
   * judged for pacing. A lift that `holdInputUntil` places then races the
   * hold alone, after the page is thawed.
   */
  press(at: Point, options?: {readonly id?: number}): Promise<HeldTouch>;
}

/** A finger that `TouchDriver.press` holds down. */
export interface HeldTouch {
  readonly id: number;
  /** Moves the finger to `to`; every other finger held stays where it is. */
  move(to: Point): Promise<void>;
  /** Lifts the finger: only its touch-up is sent. */
  lift(): Promise<void>;
}

/**
 * The fingers a driver holds down between calls. `dispatch` sends one event
 * with the finger that changed and every finger down after it.
 */
function heldFingers(
  dispatch: (
    type: TouchEventStep['type'],
    changed: Finger,
    down: readonly Finger[],
  ) => Promise<void>,
) {
  const down = new Map<number, Finger>();
  return {
    get size() {
      return down.size;
    },
    async press(at: Point, {id = 0}: {readonly id?: number} = {}) {
      if (down.has(id)) {
        throw new Error(`touchDriver: finger ${id} is already down`);
      }
      const finger = {id, x: at.x, y: at.y};
      down.set(id, finger);
      await dispatch('touchStart', finger, [...down.values()]);
      let lifted = false;
      const live = () => {
        if (lifted) {
          throw new Error(`touchDriver: finger ${id} was lifted`);
        }
      };
      const held: HeldTouch = {
        id,
        async move(to) {
          live();
          const moved = {id, x: to.x, y: to.y};
          down.set(id, moved);
          await dispatch('touchMove', moved, [...down.values()]);
        },
        async lift() {
          live();
          lifted = true;
          const last = down.get(id) ?? finger;
          down.delete(id);
          await dispatch('touchEnd', last, [...down.values()]);
        },
      };
      return held;
    },
  };
}

/** A play or a tap cannot share the screen with fingers `press` holds down. */
function assertNoneHeld(held: {readonly size: number}): void {
  if (held.size > 0) {
    throw new Error(
      `touchDriver: lift the ${held.size} finger${held.size === 1 ? '' : 's'} press holds down before a play or a tap`,
    );
  }
}

/**
 * The skip reason for a proof that lifts one finger while another stays down,
 * on a driver whose `partialLifts` is false: Playwright's WebKit (Linux build)
 * sends that lift's `touchend` with no remaining `touches`, an emulation quirk
 * iOS does not have. Those cases need a simulator capture.
 */
export const PARTIAL_LIFT_SKIP =
  'injected WebKit touches report no remaining touches when one finger of several lifts (README: engine limits); capture it on the iOS simulator';

const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

/** Waits until `performance.now()` reaches `deadline` with ~0.1 ms precision. */
async function until(deadline: number): Promise<void> {
  const remaining = deadline - performance.now();
  if (remaining > 3) {
    await sleep(remaining - 2);
  }
  while (performance.now() < deadline) {
    // spin: setTimeout alone is ±1-4 ms late
  }
}

/**
 * When event `index` of `steps` goes out, in performance.now() ms. Under
 * `'schedule'` it goes at its scripted time from `origin`. Under `'spacing'`
 * it goes its scripted interval after the event before it left. Under
 * `'spacing'`, or with `keepsGaps`, it also waits for its interval, less
 * ANSWER_SLACK_MS, after the engine answered the event before. WebKit stamps
 * an event no later than it answers, and the next one no sooner than it
 * leaves. So no gap reaches the page more than ANSWER_SLACK_MS short of the
 * script's: a stall stretches the gesture.
 */
export function pacedDeadline(
  pacing: TouchPacing,
  origin: number,
  steps: readonly {readonly t: number}[],
  index: number,
  previous: {readonly sentAt: number; readonly returnedAt: number} | null,
  keepsGaps = false,
): number {
  const scripted = origin + steps[index].t;
  if (index === 0 || previous == null) {
    return scripted;
  }
  const interval = steps[index].t - steps[index - 1].t;
  const afterAnswer = previous.returnedAt + interval - ANSWER_SLACK_MS;
  if (pacing === 'spacing') {
    return Math.max(previous.sentAt + interval, afterAnswer);
  }
  return keepsGaps ? Math.max(scripted, afterAnswer) : scripted;
}

/** What the page saw of one touch event of a paced play. */
export interface TouchArrival {
  /**
   * When the page's gesture host read the step, in WebKit. A move or a lift
   * reads at its pointer event's `timeStamp`, a touch-down at its touch
   * event's. A step with no pointer event reads at its touch event's.
   */
  readonly stamp: number;
  /**
   * The step's earliest `timeStamp`, its pointer event's; `stamp` when the
   * step had none. A touch-down reads later than this when the page's own
   * pointer listeners held its touch event.
   */
  readonly firstStamp?: number;
  /**
   * When the page's own touch and pointer listeners had finished with it;
   * NaN unseen.
   */
  readonly handledAt: number;
  /**
   * When the page's listeners began on the step's first event, NaN unseen.
   * Before it, the step waited for the main thread.
   */
  readonly startedAt?: number;
}

/** Where the release a paced play's page read strays from the script's. */
export interface TouchPacingFault {
  /**
   * `'rest'`: the page read a resting finger; `'throw'`: a throw where the
   * script rests; `'moves'`: fewer than two moves; `'release'`: another
   * speed. `'boundary'` and `'hold'`: a release or a hold on the other side
   * of a play's `boundaries` from the script's.
   */
  readonly kind: 'rest' | 'throw' | 'moves' | 'release' | 'boundary' | 'hold';
  /** The release the page read, px/s (0 for a rest or too few moves). */
  readonly pageReleasePxPerS: number;
  /** The script's release, px/s. */
  readonly scriptReleasePxPerS: number;
  /** The gaps the release reads, as the page received them, ms. */
  readonly gapsMs: readonly number[];
  /** The same gaps as the script spaces them, ms. */
  readonly scriptedGapsMs: readonly number[];
  /**
   * The widest of those gaps when the page's own touch and pointer listeners held its
   * event back (they were still handling the event before), or null.
   */
  readonly heldByPage: {
    readonly gapMs: number;
    readonly handlingMs: number;
  } | null;
  /** For `'boundary'` and `'hold'`: the threshold crossed, px/s or ms. */
  readonly threshold?: number;
  /** For `'hold'`: the first finger's hold as the page read it, and as scripted, ms. */
  readonly holdMs?: {readonly page: number; readonly script: number};
  /**
   * The longest time the page drew no frame during the gesture, ms, or null
   * unread. A gap far past a frame means the renderer was starved: no
   * dispatch can deliver a gesture's timing then.
   */
  readonly frameGapMs?: number | null;
  /**
   * The gap that strays furthest past the script's: the step it ends at, and
   * the gap as the page received it and as scripted, ms.
   */
  readonly late?: {
    readonly index: number;
    readonly gapMs: number;
    readonly scriptedGapMs: number;
  };
  /**
   * The widest gap that an event's wait for the main thread accounts for,
   * when the listeners alone do not, or null. The wait ends when the page's
   * listeners begin. Another page task, or a starved runner, held the event.
   */
  readonly waited?: {
    readonly gapMs: number;
    readonly waitMs: number;
  } | null;
}

/** The lifting finger's release, read from the page's stamps and the script's. */
export interface ReleaseReading {
  readonly pagePxPerS: number;
  readonly scriptPxPerS: number;
  /** The page read a resting finger. */
  readonly rests: boolean;
  /**
   * The script rests before the lift, but the page read a throw: its last
   * move reached the page within the stillness interval of the lift.
   */
  readonly throws: boolean;
  /**
   * The page read fewer than two moves where the script makes more: its
   * moves arrived at one time, so it reads no release.
   */
  readonly fewMoves: boolean;
  /** The page's release strays from the script's by this share of it. */
  readonly strayShare: number;
  /** The events whose gaps the release reads (each gap ends at one). */
  readonly span: readonly number[];
}

/** One sample of the lifting finger: its position and when it was read. */
interface FingerSample {
  readonly index: number;
  readonly x: number;
  readonly y: number;
  readonly time: number;
}

/** What Core's velocity tracker reads from a finger's samples at its lift. */
interface CoreReading {
  readonly x: number;
  readonly y: number;
  /** Moved samples after the touch-down. */
  readonly moves: number;
  /** The finger was still for longer than the stillness interval. */
  readonly rests: boolean;
  /**
   * The moved samples the release reads, oldest first: up to three for a
   * pan's release, four for a scrolling surface's.
   */
  readonly moved: readonly FingerSample[];
}

/**
 * The release Core's velocity tracker reads, px/s. It copies that filter:
 * Core's `VelocityTracker` is internal to the core package, so the harness
 * cannot call it. Keep the two equal (`add`, `releases`, `panVelocity`,
 * `scrollVelocity`): Core's VelocityTracker.harness.test.ts reads the same
 * samples with both. Only a sample that moves
 * counts, and a sample at the newest moved sample's time replaces it. The
 * newest interval weighs 0.2 and the one before it 0.8, and an interval
 * across no time reads 0. A scrolling surface's release blends the newest
 * pan value, 0.25, with the one before it. The release is 0 with fewer than
 * two moves after the touch-down, or after a rest longer than the stillness
 * interval.
 */
function coreRelease(
  samples: readonly FingerSample[],
  liftTime: number,
  filter: TouchReleaseFilter = 'pan',
): CoreReading {
  const moved: FingerSample[] = [];
  let moves = 0;
  let newest = Number.NEGATIVE_INFINITY;
  for (const sample of samples) {
    if (sample.time < newest) {
      continue;
    }
    newest = sample.time;
    const last = moved[moved.length - 1];
    if (last != null && sample.x === last.x && sample.y === last.y) {
      continue;
    }
    if (last != null && sample.time === last.time) {
      moved[moved.length - 1] = sample;
    } else {
      moved.push(sample);
      if (moved.length > 4) {
        moved.shift();
      }
      if (last != null) {
        moves += 1;
      }
    }
  }
  const read = filter === 'scroll' ? moved : moved.slice(-3);
  const last = moved[moved.length - 1];
  const rests = last != null && liftTime - last.time > TOUCH_STILLNESS_MS;
  if (moves < 2 || last == null || rests) {
    return {x: 0, y: 0, moves, rests, moved: read};
  }
  const pair = (a: FingerSample, b: FingerSample) => {
    const seconds = (b.time - a.time) / 1000;
    return seconds > 0
      ? {x: (b.x - a.x) / seconds, y: (b.y - a.y) / seconds}
      : {x: 0, y: 0};
  };
  // The pan's value over the last three of `upTo`, as Core updates it on
  // each moved sample.
  const pan = (upTo: readonly FingerSample[]) => {
    const n = upTo.length;
    if (n < 2) {
      return {x: 0, y: 0};
    }
    const current = pair(upTo[n - 2], upTo[n - 1]);
    const before = n >= 3 ? pair(upTo[n - 3], upTo[n - 2]) : current;
    const w = TOUCH_RELEASE_NEWEST_WEIGHT;
    return {
      x: w * current.x + (1 - w) * before.x,
      y: w * current.y + (1 - w) * before.y,
    };
  };
  const current = pan(moved.slice(-3));
  if (filter === 'pan') {
    return {...current, moves, rests, moved: read};
  }
  const previous = pan(moved.slice(0, -1).slice(-3));
  const w = TOUCH_SCROLL_RELEASE_NEWEST_WEIGHT;
  return {
    x: w * current.x + (1 - w) * previous.x,
    y: w * current.y + (1 - w) * previous.y,
    moves,
    rests,
    moved: read,
  };
}

/**
 * Reads a paced play's release as Core's velocity tracker reads it, from the
 * page's stamps and from the script's times. Both read the same positions,
 * rounded once: WebKit delivers whole pixels. Each reading has its own rest,
 * so a page that does not rest where the script does fails the play.
 */
export function readRelease(
  steps: readonly TouchEventStep[],
  arrivals: readonly TouchArrival[],
  filter: TouchReleaseFilter = 'pan',
): ReleaseReading | null {
  const lift = steps.length - 1;
  const id =
    steps[lift]?.type === 'touchEnd' ? steps[lift].changed[0]?.id : undefined;
  if (id == null || arrivals.length !== steps.length) {
    return null;
  }
  const positions: {index: number; x: number; y: number}[] = [];
  steps.forEach((step, index) => {
    const finger =
      step.type === 'touchStart' || step.type === 'touchMove'
        ? step.changed.find(f => f.id === id)
        : undefined;
    if (finger != null) {
      positions.push({index, x: Math.round(finger.x), y: Math.round(finger.y)});
    }
  });
  if (positions.length === 0) {
    return null;
  }
  const script = coreRelease(
    positions.map(p => ({...p, time: steps[p.index].t})),
    steps[lift].t,
    filter,
  );
  const page = coreRelease(
    positions.map(p => ({...p, time: arrivals[p.index].stamp})),
    arrivals[lift].stamp,
    filter,
  );
  const scriptPxPerS = Math.hypot(script.x, script.y);
  const first = page.moved[0]?.index ?? positions[0].index;
  return {
    pagePxPerS: Math.hypot(page.x, page.y),
    scriptPxPerS,
    // One move releases at 0 for the script and the page alike, so a late
    // lift after it changes nothing.
    rests: script.moves >= 2 && !script.rests && page.rests,
    throws: script.rests && !page.rests && page.moves >= 2,
    fewMoves:
      !script.rests && !page.rests && page.moves < 2 && script.moves >= 2,
    strayShare:
      scriptPxPerS > 0
        ? Math.hypot(page.x - script.x, page.y - script.y) / scriptPxPerS
        : 0,
    span: Array.from({length: lift - first}, (_, k) => first + 1 + k),
  };
}

/**
 * Reads a paced play's release as the page did and returns its fault, or
 * null. The kinds: `rest`, a resting finger where the script moves; `throw`,
 * a throw where the script rests; `moves`, fewer than two moves. Given
 * `tolerance`, `release` is a release that strays further than that share.
 * The release blends the lifting finger's last two move intervals (its
 * touch-down counts as the first event). It is 0 once the finger was still
 * past the stillness interval before it lifts. So only those gaps decide it,
 * and an earlier stall leaves it intact. Each reading keeps its own rest.
 * WebKit dispatches a touch only once the page's main thread is free, so a
 * gap is the page's when the page's listeners spent longer on the event
 * before it than the script's interval to the next, and that handling
 * accounts for the gap's excess over the script within a frame. Under
 * `'spacing'` the harness itself waits out a late answer, so its send
 * spacing cannot tell a page stall from a runner stall, as the wheel path's
 * does (`wheelGapCauses`); the page's handling time can. The fault is the
 * page's when any gap the release reads is.
 */
export function touchPacingFault(
  steps: readonly TouchEventStep[],
  arrivals: readonly TouchArrival[],
  tolerance?: number,
  {
    release = 'pan',
    boundaries = {},
  }: Pick<PlayOptions, 'release' | 'boundaries'> = {},
): TouchPacingFault | null {
  const reading = readRelease(steps, arrivals, release);
  const sides = (threshold: number, page: number, script: number) =>
    page >= threshold !== script >= threshold;
  const releaseBound = boundaries.releasePxPerS;
  const crossesRelease =
    reading != null &&
    releaseBound != null &&
    sides(releaseBound, reading.pagePxPerS, reading.scriptPxPerS);
  const hold =
    arrivals.length === steps.length ? readHold(steps, arrivals) : null;
  const crossesHold =
    hold != null &&
    boundaries.holdMs != null &&
    sides(boundaries.holdMs, hold.page, hold.script);
  const releaseFault =
    reading != null &&
    (reading.rests ||
      reading.throws ||
      reading.fewMoves ||
      (tolerance != null && reading.strayShare > tolerance) ||
      crossesRelease);
  if (!releaseFault && !crossesHold) {
    return null;
  }
  // The gaps the fault reads: the release's, or for a hold every gap from
  // touch-down to the lift.
  const span =
    releaseFault && reading != null
      ? reading.span
      : Array.from({length: steps.length - 1}, (_, k) => k + 1);
  const gapsMs = span.map(i => arrivals[i].stamp - arrivals[i - 1].stamp);
  const scriptedGapsMs = span.map(i => steps[i].t - steps[i - 1].t);
  let heldByPage: TouchPacingFault['heldByPage'] = null;
  let waited: TouchPacingFault['waited'] = null;
  span.forEach((i, k) => {
    const holds = (ms: number) =>
      Number.isFinite(ms) &&
      ms > scriptedGapsMs[k] &&
      ms + HELD_BACK_MS >= gapsMs[k] - scriptedGapsMs[k];
    // The event before held this one back, or this step's own pointer
    // listeners held its touch event (a lift read at its touchend). Each runs
    // from a stamp to the end of the listeners. The part before the
    // listeners began is a wait for the main thread, not listener time.
    const terms = [
      [
        arrivals[i - 1].stamp,
        arrivals[i - 1].startedAt,
        arrivals[i - 1].handledAt,
      ],
      [
        arrivals[i].firstStamp ?? arrivals[i].stamp,
        arrivals[i].startedAt,
        arrivals[i].stamp,
      ],
    ] as const;
    for (const [from, began, to] of terms) {
      const totalMs = to - from;
      const handlingMs =
        began != null && Number.isFinite(began)
          ? to - Math.max(began, from)
          : totalMs;
      if (holds(handlingMs)) {
        if (heldByPage == null || handlingMs > heldByPage.handlingMs) {
          heldByPage = {gapMs: gapsMs[k], handlingMs};
        }
      } else if (holds(totalMs)) {
        const waitMs = totalMs - handlingMs;
        if (waited == null || waitMs > waited.waitMs) {
          waited = {gapMs: gapsMs[k], waitMs};
        }
      }
    }
  });
  const lateK = gapsMs.reduce(
    (best, gap, k) =>
      gap - scriptedGapsMs[k] > gapsMs[best] - scriptedGapsMs[best] ? k : best,
    0,
  );
  const late =
    span.length > 0
      ? {
          index: span[lateK],
          gapMs: gapsMs[lateK],
          scriptedGapMs: scriptedGapsMs[lateK],
        }
      : undefined;
  if (!releaseFault || reading == null) {
    return {
      kind: 'hold',
      pageReleasePxPerS: reading?.pagePxPerS ?? 0,
      scriptReleasePxPerS: reading?.scriptPxPerS ?? 0,
      gapsMs,
      scriptedGapsMs,
      heldByPage,
      waited,
      late,
      threshold: boundaries.holdMs,
      holdMs: hold ?? undefined,
    };
  }
  const strays = tolerance != null && reading.strayShare > tolerance;
  return {
    kind: reading.rests
      ? 'rest'
      : reading.throws
        ? 'throw'
        : reading.fewMoves
          ? 'moves'
          : strays
            ? 'release'
            : 'boundary',
    pageReleasePxPerS: reading.pagePxPerS,
    scriptReleasePxPerS: reading.scriptPxPerS,
    gapsMs,
    scriptedGapsMs,
    heldByPage,
    waited,
    late,
    threshold: strays ? undefined : releaseBound,
  };
}

/**
 * The first finger's hold from touch-down to the lift that ends the play, ms.
 * It gives the page's reading and the script's: a tap's hold, or a drag's
 * whole span.
 */
export function readHold(
  steps: readonly TouchEventStep[],
  arrivals: readonly TouchArrival[],
): {readonly page: number; readonly script: number} | null {
  const lift = steps.length - 1;
  if (
    lift < 1 ||
    steps[0].type !== 'touchStart' ||
    steps[lift].type !== 'touchEnd' ||
    arrivals.length !== steps.length
  ) {
    return null;
  }
  return {
    page: arrivals[lift].stamp - arrivals[0].stamp,
    script: steps[lift].t - steps[0].t,
  };
}

function describeFault(fault: TouchPacingFault): string {
  const frames =
    fault.frameGapMs == null
      ? ''
      : `; the page drew no frame for ${fault.frameGapMs.toFixed(0)} ms during the gesture`;
  return `${describeReading(fault)}${frames}`;
}

function describeReading(fault: TouchPacingFault): string {
  const gaps = `gaps ${fault.gapsMs.map(g => g.toFixed(0)).join(', ')} ms where the script spaces ${fault.scriptedGapsMs.map(g => g.toFixed(0)).join(', ')} ms`;
  if (fault.kind === 'hold' && fault.holdMs != null) {
    return `the page read a hold of ${fault.holdMs.page.toFixed(0)} ms where the script holds ${fault.holdMs.script.toFixed(0)} ms, on the other side of the ${fault.threshold} ms the component decides on`;
  }
  if (fault.kind === 'boundary') {
    return `the page read a release of ${fault.pageReleasePxPerS.toFixed(0)} px/s where the script throws ${fault.scriptReleasePxPerS.toFixed(0)} px/s, on the other side of the ${fault.threshold} px/s the component decides on (${gaps})`;
  }
  if (fault.kind === 'rest') {
    return `the page read a resting finger: the lift reached it more than ${TOUCH_STILLNESS_MS} ms after the last move (${gaps})`;
  }
  if (fault.kind === 'throw') {
    return `the page read a throw of ${fault.pageReleasePxPerS.toFixed(0)} px/s where the script rests more than ${TOUCH_STILLNESS_MS} ms before the lift (${gaps})`;
  }
  if (fault.kind === 'moves') {
    return `the page read fewer than two moves, so no release, where the script throws ${fault.scriptReleasePxPerS.toFixed(0)} px/s: its moves reached it at one time (${gaps})`;
  }
  return `the page read a release of ${fault.pageReleasePxPerS.toFixed(0)} px/s where the script throws ${fault.scriptReleasePxPerS.toFixed(0)} px/s (${gaps})`;
}

/**
 * A paced play's page read a release that is not the script's. Its own touch
 * and pointer listeners did not hold the events back: a dispatch stalled
 * before the page. When an event waited for the main thread before the page's
 * listeners began, the error says how long. Another page task, or a starved
 * runner, held it there. A gap with no wait, across which the page drew no
 * frame, is `TouchStarvationError`.
 */
export class TouchPacingError extends Error {
  constructor(readonly fault: TouchPacingFault) {
    super(
      `touchDriver: ${describeFault(fault)}: ${fault.waited == null ? 'a dispatch stalled before the page' : `an event waited ${fault.waited.waitMs.toFixed(0)} ms for the main thread before the page's listeners began, so the next reached it ${fault.waited.gapMs.toFixed(0)} ms later: another page task held the thread, or the runner starved it`}`,
    );
    this.name = 'TouchPacingError';
  }
}

/**
 * A paced play's page read a release that is not the script's, and its own
 * touch and pointer listeners held an event back. They were still handling
 * the event before, and WebKit dispatches the next touch only once the page
 * is free. The handling time runs from when the listeners began, so a wait
 * for the main thread before them is not counted. It is page wall time,
 * which on a starved runner includes a listener's wait for a CPU. Judge a
 * page stall from a run with CI's CPU limits: there it is the proof's own
 * failure.
 */
export class TouchPageStallError extends Error {
  constructor(
    readonly fault: TouchPacingFault & {
      readonly heldByPage: NonNullable<TouchPacingFault['heldByPage']>;
    },
  ) {
    super(
      `touchDriver: the page's own touch and pointer listeners took ${fault.heldByPage.handlingMs.toFixed(0)} ms of page wall time to handle an event, so the next reached it ${fault.heldByPage.gapMs.toFixed(0)} ms later, and ${describeFault(fault)}. On a starved runner that time includes the page's wait for a CPU: judge a page stall from a run with CI's CPU limits`,
    );
    this.name = 'TouchPageStallError';
  }
}

/**
 * A paced play's page read a release that is not the script's, and the
 * runner starved the page. Across the gap that strays furthest, the page drew
 * no frame for longer than `FRAME_STARVATION_MS`. Neither its own listeners
 * nor a page task held the event before it. No pacing reaches a page that
 * draws nothing, so the play cannot judge the component. It fails by name,
 * as a busy proof's `FrameStarvationError` does. Judge the proof from a run
 * with CI's CPU limits.
 */
export class TouchStarvationError extends Error {
  constructor(
    readonly fault: TouchPacingFault & {
      readonly late: NonNullable<TouchPacingFault['late']>;
      /** The longest time the page drew no frame across that gap, ms. */
      readonly starvedMs: number;
    },
  ) {
    super(
      `touchDriver: the page drew no frame for ${fault.starvedMs.toFixed(0)} ms across a ${fault.late.gapMs.toFixed(0)} ms gap where the script spaces ${fault.late.scriptedGapMs.toFixed(0)} ms, and ${describeFault(fault)}. Neither the page's listeners nor a page task held the event: the runner starved the page. Judge the proof from a run with CI's CPU limits`,
    );
    this.name = 'TouchStarvationError';
  }
}

/**
 * A play's lift reached the page more than the stillness interval after its
 * finger's last move, where the script throws. The scripted gap plus the time
 * the play's own `onEvent` ran passes that interval. Page work there holds the
 * next event back by a round trip. A loaded runner can stretch the
 * gap more, and the error still names `onEvent`. On a page that stamps
 * touches on arrival (WebKit), the page then reads a resting finger and
 * releases at 0.
 */
export class TouchLiftStallError extends Error {
  constructor(
    readonly numbers: {
      /** The gap the script spaces from the last move to the lift, ms. */
      readonly scriptedGapMs: number;
      /** The same gap as the page received it, ms. */
      readonly gapMs: number;
      /** How long `onEvent` ran in that gap, ms. */
      readonly onEventMs: number;
      /** As in `TouchPacingFault`: the longest frame gap, ms, or null unread. */
      readonly frameGapMs?: number | null;
    },
  ) {
    const {scriptedGapMs, gapMs, onEventMs, frameGapMs} = numbers;
    const frames =
      frameGapMs == null
        ? ''
        : `; the page drew no frame for ${frameGapMs.toFixed(0)} ms during the gesture`;
    super(
      `touchDriver: the lift reached the page ${gapMs.toFixed(0)} ms after its finger's last move, where the script spaces ${scriptedGapMs.toFixed(0)} ms: past the ${TOUCH_STILLNESS_MS} ms stillness interval, the page reads a resting finger. onEvent ran ${onEventMs.toFixed(0)} ms in that gap: page work there holds the next event back${frames}. Read the page in a listener of its own, or rest the script before the lift`,
    );
    this.name = 'TouchLiftStallError';
  }
}

/**
 * The `TouchLiftStallError` for a fault the play's own `onEvent` explains. The
 * page read a rest, and the scripted gap plus `onEvent`'s run passes the
 * stillness interval. A loaded runner that stretched the gap more changes
 * nothing: the lift stall is the more specific cause, so it comes before any
 * pacing error. Null for any other fault.
 */
export function liftStallError(
  steps: readonly TouchEventStep[],
  arrivals: readonly TouchArrival[],
  fault: TouchPacingFault,
  onEventMs: readonly number[],
): TouchLiftStallError | null {
  if (fault.kind !== 'rest') {
    return null;
  }
  const lift = steps.length - 1;
  const id = steps[lift].changed[0]?.id;
  let lastMoved = 0;
  let at = '';
  steps.forEach((step, k) => {
    const finger =
      step.type === 'touchStart' || step.type === 'touchMove'
        ? step.changed.find(f => f.id === id)
        : undefined;
    const key =
      finger == null ? at : `${Math.round(finger.x)},${Math.round(finger.y)}`;
    if (key !== at) {
      lastMoved = k;
      at = key;
    }
  });
  const scriptedGapMs = steps[lift].t - steps[lastMoved].t;
  const gapMs = arrivals[lift].stamp - arrivals[lastMoved].stamp;
  const ranMs = onEventMs
    .slice(lastMoved, lift)
    .reduce((sum, ms) => sum + ms, 0);
  return scriptedGapMs + ranMs > TOUCH_STILLNESS_MS
    ? new TouchLiftStallError({
        scriptedGapMs,
        gapMs,
        onEventMs: ranMs,
        frameGapMs: fault.frameGapMs,
      })
    : null;
}

/**
 * The error a paced play's fault throws. The lift stall comes first, since
 * it is the more specific cause. Then a gap the page's own listeners held is
 * the page's. A starved page drew no frame for longer than
 * `FRAME_STARVATION_MS` across the late gap. With no wait for the main
 * thread, that fault is the starved runner's. Any other gap is a dispatch
 * that stalled before the page.
 * `frames` are the times the page drew a frame during the play.
 */
export function touchPlayError(
  steps: readonly TouchEventStep[],
  arrivals: readonly TouchArrival[],
  fault: TouchPacingFault,
  onEventMs: readonly number[],
  frames: readonly number[] = [],
):
  | TouchLiftStallError
  | TouchPageStallError
  | TouchStarvationError
  | TouchPacingError {
  const lift = liftStallError(steps, arrivals, fault, onEventMs);
  if (lift != null) {
    return lift;
  }
  if (fault.heldByPage != null) {
    return new TouchPageStallError({...fault, heldByPage: fault.heldByPage});
  }
  const {late} = fault;
  const starvedMs =
    late == null || late.index < 1 || fault.waited != null
      ? null
      : longestFrameGap(frames, [
          arrivals[late.index - 1],
          arrivals[late.index],
        ]);
  return late != null && starvedMs != null && starvedMs > FRAME_STARVATION_MS
    ? new TouchStarvationError({...fault, late, starvedMs})
    : new TouchPacingError(fault);
}

/** Records what the page saw of a paced play's touches (WebKit). */
interface TouchArrivalProbe {
  arm(): Promise<void>;
  /** Each touch event's arrival, and when the page drew each frame meanwhile. */
  read(): Promise<{arrivals: TouchArrival[]; frames: number[]}>;
}

/**
 * The longest time the page drew no frame while the gesture reached it, ms.
 * The span runs from the last frame before the first touch to the first
 * frame after the lift. With no such frame, the touch or the lift itself
 * bounds it. Null with no frame read.
 */
export function longestFrameGap(
  frames: readonly number[],
  arrivals: readonly TouchArrival[],
): number | null {
  if (frames.length === 0 || arrivals.length === 0) {
    return null;
  }
  const from = arrivals[0].stamp;
  const to = arrivals[arrivals.length - 1].stamp;
  const sorted = [...frames].sort((a, b) => a - b);
  const before = sorted.filter(t => t <= from).at(-1) ?? from;
  const after = sorted.find(t => t >= to) ?? to;
  const edges = [before, ...sorted.filter(t => t > from && t < to), after];
  let longest = 0;
  for (let i = 1; i < edges.length; i += 1) {
    longest = Math.max(longest, edges[i] - edges[i - 1]);
  }
  return longest;
}

async function playSteps(
  script: TouchScript,
  options: PlayOptions,
  dispatch: (step: TouchEventStep, timestamp: number) => Promise<void>,
  stampFor: (t: number) => number,
  probe: TouchArrivalProbe | null,
): Promise<PlayedEvent[]> {
  const {
    realtime = true,
    onEvent,
    pacing = 'schedule',
    releaseTolerance,
    releaseUnread = false,
    release = 'pan',
    boundaries,
  } = options;
  const steps = toTouchEvents(script);
  // Only where the page reads a velocity from arrival times: scripted
  // timestamps carry it. Every real-time play is judged there, unless its
  // proof reads no release.
  const judges = probe != null && realtime && !releaseUnread;
  // A driver gives a probe only where the page stamps touches on arrival.
  // There, a play behind its schedule never shrinks a scripted gap, so page
  // work in `onEvent` cannot eat the rest before a lift.
  const keepsGaps = probe != null;
  if (judges) {
    await probe.arm();
  }
  const played: PlayedEvent[] = [];
  const origin = performance.now();
  let previous: {sentAt: number; returnedAt: number} | null = null;
  const onEventMs: number[] = [];
  for (const [index, step] of steps.entries()) {
    if (realtime) {
      await until(
        pacedDeadline(pacing, origin, steps, index, previous, keepsGaps),
      );
    }
    const timestamp = stampFor(step.t);
    const dispatchedAt = Date.now();
    const sentAt = performance.now();
    await dispatch(step, timestamp);
    const answered = performance.now();
    previous = {sentAt, returnedAt: answered};
    played.push({
      ...step,
      dispatchedAt,
      returnedAt: Date.now(),
      pacedSentAt: sentAt,
      pacedReturnedAt: answered,
      timestamp,
    });
    const watched = performance.now();
    await onEvent?.(step, index);
    onEventMs.push(performance.now() - watched);
  }
  // Judged once the lift is out, so no finger is left down.
  if (judges) {
    const {arrivals, frames} = await probe.read();
    // A page that lost events, such as a target removed mid-gesture, gives no
    // release to read. Only a `'spacing'` play, which asks for the
    // judgment, fails then.
    if (arrivals.length !== steps.length && pacing === 'spacing') {
      throw new Error(
        `touchDriver: the page received ${arrivals.length} of a paced play's ${steps.length} touch events`,
      );
    }
    const found = touchPacingFault(steps, arrivals, releaseTolerance, {
      release,
      boundaries,
    });
    if (found != null) {
      const fault = {...found, frameGapMs: longestFrameGap(frames, arrivals)};
      throw touchPlayError(steps, arrivals, fault, onEventMs, frames);
    }
    const reading = readRelease(steps, arrivals, release);
    if (reading != null) {
      played[played.length - 1] = {
        ...played[played.length - 1],
        release: {
          pagePxPerS: reading.pagePxPerS,
          scriptPxPerS: reading.scriptPxPerS,
        },
      };
    }
  }
  return played;
}

async function chromiumDriver(page: Page): Promise<TouchDriver> {
  const cdp: CDPSession = await page.context().newCDPSession(page);
  const touchPoints = (fingers: readonly Finger[]) =>
    fingers.map(f => ({
      x: f.x,
      y: f.y,
      id: f.id,
      radiusX: 1,
      radiusY: 1,
      force: 1,
    }));
  // A start or move lists every finger down. An end lists the finger that
  // lifts while others stay down, and none for the last lift, as play does.
  const held = heldFingers(async (type, changed, down) => {
    await cdp.send('Input.dispatchTouchEvent', {
      type,
      touchPoints:
        type !== 'touchEnd'
          ? touchPoints(down)
          : down.length > 0
            ? touchPoints([changed])
            : [],
      timestamp: Date.now() / 1000,
    });
  });
  return {
    engine: 'chromium',
    scriptedTimestamps: true,
    drivesNativeGestures: true,
    partialLifts: true,
    press: (at, options) => held.press(at, options),
    async play(script, options = {}) {
      assertNoneHeld(held);
      // Stamps follow the wall clock the page's own clock is on: with real-time
      // pacing an event's stamp and its dispatch agree to ~0.1 ms.
      const base = Date.now();
      return playSteps(
        script,
        options,
        async (step, timestamp) => {
          // A start or move lists every finger down (CDP presses the new ones).
          // An end lists the fingers that lift: that releases exactly those
          // while the rest stay down and keep moving; the last lift lists none.
          // (A move that omits a finger does not release it.)
          await cdp.send('Input.dispatchTouchEvent', {
            type: step.type,
            touchPoints:
              step.type !== 'touchEnd'
                ? touchPoints(step.fingers)
                : step.fingers.length > 0
                  ? touchPoints(step.changed)
                  : [],
            timestamp: timestamp / 1000,
          });
        },
        t => base + t,
        null,
      );
    },
    async tap(at) {
      assertNoneHeld(held);
      await page.touchscreen.tap(at.x, at.y);
    },
  };
}

interface WebKitPageProxySession {
  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
  on(event: string, listener: (payload: unknown) => void): unknown;
  off?(event: string, listener: (payload: unknown) => void): unknown;
}

/**
 * Playwright's server-side WebKit page session, reached through the in-process
 * connection. Exported for helpers that use WebKit's own inspector protocol.
 */
export function webkitPageSession(page: Page): WebKitPageProxySession {
  const connection = (
    page as unknown as {_connection?: {toImpl?: (o: unknown) => unknown}}
  )._connection;
  const impl = connection?.toImpl?.(page) as
    {delegate?: {_pageProxySession?: WebKitPageProxySession}} | undefined;
  const session = impl?.delegate?._pageProxySession;
  if (session == null) {
    throw new Error(
      "WebKit touch input needs Playwright's in-process server (a locally launched browser); this page has none.",
    );
  }
  return session;
}

/**
 * The events a paced play's probe records: a gesture host samples a finger
 * from its pointer events, and a page can handle either kind.
 */
const TOUCH_TYPES = [
  'pointerdown',
  'pointermove',
  'pointerup',
  'pointercancel',
  'touchstart',
  'touchmove',
  'touchend',
  'touchcancel',
];

/**
 * One arrival for each touch event a probe recorded, in dispatch order. WebKit
 * dispatches each step's pointer events just before its touch event, and
 * stamps the touch event only once the page's pointer listeners are done.
 * Core's gesture host reads a finger's moves from its pointer events, and
 * its lift from the pointerup paired with them. It reads the touch-down from
 * its touch event. So a move or a lift arrives at the earliest stamp of its
 * step, and a touch-down at its touch event's own stamp. Each takes the
 * latest handling mark of its step.
 */
export function touchArrivalsFrom(record: {
  readonly eventTypes: readonly string[];
  readonly pointerTypes: readonly string[];
  readonly stamps: readonly number[];
  readonly handledAt: readonly number[];
  readonly receivedAt?: readonly number[];
}): TouchArrival[] {
  const arrivals: TouchArrival[] = [];
  let stamp = Number.POSITIVE_INFINITY;
  let handledAt = Number.NaN;
  let startedAt = Number.POSITIVE_INFINITY;
  record.eventTypes.forEach((type, i) => {
    // A mouse's or a pen's pointer event is not this play's.
    if (!type.startsWith('touch') && record.pointerTypes[i] !== 'touch') {
      return;
    }
    stamp = Math.min(stamp, record.stamps[i]);
    startedAt = Math.min(startedAt, record.receivedAt?.[i] ?? Number.NaN);
    const mark = record.handledAt[i];
    if (Number.isFinite(mark)) {
      handledAt = Number.isNaN(handledAt) ? mark : Math.max(handledAt, mark);
    }
    if (type.startsWith('touch')) {
      arrivals.push({
        stamp: type === 'touchstart' ? record.stamps[i] : stamp,
        firstStamp: stamp,
        handledAt,
        ...(record.receivedAt == null
          ? {}
          : {startedAt: Number.isFinite(startedAt) ? startedAt : Number.NaN}),
      });
      stamp = Number.POSITIVE_INFINITY;
      handledAt = Number.NaN;
      startedAt = Number.POSITIVE_INFINITY;
    }
  });
  return arrivals;
}

/**
 * Records, for each touch event of a paced play, when it reached the page
 * and when the page's own listeners had finished with it. It also records
 * the page's frames (`armInputRun`).
 */
function touchArrivalProbe(page: Page): TouchArrivalProbe {
  let armed: JSHandle<InputRun> | null = null;
  return {
    async arm() {
      await armed?.evaluate(run => run.stop());
      await armed?.dispose();
      armed = await armInputRun(page, TOUCH_TYPES, {frames: true});
      // Waits for the run's first frame, so the frames read one before the
      // gesture. The harness's own frames run on the real timers: a frozen
      // timer gate (story.ts) holds only the page's.
      await armed.evaluate(
        run =>
          new Promise<void>(resolve => {
            const gate = (
              window as unknown as {
                __harnessTimerGate?: {frame?: typeof requestAnimationFrame};
              }
            ).__harnessTimerGate;
            const frame =
              gate?.frame ?? window.requestAnimationFrame.bind(window);
            const check = () =>
              run.frames.length > 0 ? resolve() : frame(check);
            check();
          }),
      );
    },
    async read() {
      if (armed == null) {
        return {arrivals: [], frames: []};
      }
      const run = armed;
      armed = null;
      const {frames, ...record} = await run.evaluate(recorded => {
        recorded.stop();
        return {
          eventTypes: recorded.eventTypes.slice(),
          pointerTypes: recorded.pointerTypes.slice(),
          stamps: recorded.stamps.slice(),
          handledAt: recorded.handledAt.slice(),
          frames: recorded.frames.slice(),
          // Only a mark added before the page's scripts comes before every
          // page listener. Without it, the hold counts from the stamp.
          ...(recorded.startsFirst
            ? {receivedAt: recorded.receivedAt.slice()}
            : {}),
        };
      });
      await run.dispose();
      return {arrivals: touchArrivalsFrom(record), frames};
    },
  };
}

async function webkitDriver(page: Page): Promise<TouchDriver> {
  const session = webkitPageSession(page);
  await installInputStart(page, TOUCH_TYPES);
  // WebKit's command takes integer CSS px and applies the event's phase to
  // every point it lists: a start lists only the fingers that land (listing a
  // finger already down presses it again), an end only the fingers that lift
  // (an empty list releases nothing), a move every finger down.
  const points = (fingers: readonly Finger[]) =>
    fingers.map(f => ({x: Math.round(f.x), y: Math.round(f.y), id: f.id}));
  const held = heldFingers(async (type, changed, down) => {
    await session.send('Input.dispatchTouchEvent', {
      type,
      touchPoints: points(type === 'touchMove' ? down : [changed]),
    });
  });
  return {
    engine: 'webkit',
    scriptedTimestamps: false,
    drivesNativeGestures: false,
    partialLifts: false,
    press: (at, options) => held.press(at, options),
    async play(script, options = {}) {
      assertNoneHeld(held);
      return playSteps(
        script,
        options,
        async step => {
          await session.send('Input.dispatchTouchEvent', {
            type: step.type,
            touchPoints: points(
              step.type === 'touchMove' ? step.fingers : step.changed,
            ),
          });
        },
        () => Date.now(),
        touchArrivalProbe(page),
      ).then(played => played.map(p => ({...p, timestamp: null})));
    },
    async tap(at) {
      assertNoneHeld(held);
      await page.touchscreen.tap(Math.round(at.x), Math.round(at.y));
    },
  };
}

/**
 * Adds the WebKit driver's listener-start mark to each page the tab loads
 * next, before the page's scripts. A driver created after that load then tells
 * a wait for the main thread from the page's listeners. `openStory` calls it.
 * Other engines read no mark, so it adds none there.
 */
export async function installTouchStartBeforeLoad(page: Page): Promise<void> {
  if (page.context().browser()?.browserType().name() === 'webkit') {
    await installInputStartBeforeLoad(page, TOUCH_TYPES);
  }
}

/** A touch driver for the page's engine. Firefox is not supported (no touch input path). */
export async function touchDriver(page: Page): Promise<TouchDriver> {
  const name = page.context().browser()?.browserType().name();
  if (name === 'chromium') {
    return chromiumDriver(page);
  }
  if (name === 'webkit') {
    return webkitDriver(page);
  }
  throw new Error(
    `touchDriver: no real touch input path for ${name ?? 'this browser'}`,
  );
}

export interface InputRecord {
  readonly type: string;
  /** The event's own `timeStamp`, ms since the page's time origin. */
  readonly timeStamp: number;
  readonly isTrusted: boolean;
  readonly cancelable: boolean;
  readonly defaultPrevented: boolean;
  readonly pointerId?: number;
  readonly pointerType?: string;
  readonly x?: number;
  readonly y?: number;
  readonly touches?: number;
  /** A pointer event's pressure (a pen's, 0–1). */
  readonly pressure?: number;
  /** A wheel step's deltas, mode and Control key (webInput.ts). */
  readonly deltaX?: number;
  readonly deltaY?: number;
  readonly deltaMode?: number;
  readonly ctrlKey?: boolean;
  readonly target: string;
}

const INPUT_LOG_SCRIPT = `(() => {
  if (window.__harnessInput) return;
  const log = [];
  window.__harnessInput = log;
  const describe = node => node instanceof Element
    ? node.tagName.toLowerCase() + (node.id ? '#' + node.id : '') + (node.getAttribute('aria-label') ? '[' + node.getAttribute('aria-label') + ']' : '')
    : String(node && node.nodeName);
  const types = ['pointerdown', 'pointermove', 'pointerup', 'pointercancel', 'touchstart', 'touchmove',
    'touchend', 'touchcancel', 'click', 'contextmenu', 'gotpointercapture', 'lostpointercapture', 'wheel'];
  for (const type of types) {
    // Bubble phase on window, so defaultPrevented reflects the page's own handlers.
    window.addEventListener(type, event => {
      const record = {type, timeStamp: event.timeStamp, isTrusted: event.isTrusted, cancelable: event.cancelable,
        defaultPrevented: event.defaultPrevented, target: describe(event.target)};
      if ('pointerId' in event) Object.assign(record, {pointerId: event.pointerId, pointerType: event.pointerType, x: event.clientX, y: event.clientY, pressure: event.pressure});
      if (type === 'wheel') Object.assign(record, {deltaX: event.deltaX, deltaY: event.deltaY, deltaMode: event.deltaMode, ctrlKey: event.ctrlKey, x: event.clientX, y: event.clientY});
      if (event.touches) Object.assign(record, {touches: event.touches.length, x: event.changedTouches[0] && event.changedTouches[0].clientX, y: event.changedTouches[0] && event.changedTouches[0].clientY});
      log.push(record);
    }, {passive: true});
  }
})()`;

/** Records every pointer, touch, click and wheel step the page receives (install before navigation). */
export async function installInputLog(page: Page): Promise<void> {
  await page.addInitScript(INPUT_LOG_SCRIPT);
}

/** What the page received since navigation (or since the last `clear`). */
export async function readInputLog(
  page: Page,
  {clear = false}: {clear?: boolean} = {},
): Promise<InputRecord[]> {
  return page.evaluate(shouldClear => {
    const log =
      (window as unknown as {__harnessInput?: InputRecord[]}).__harnessInput ??
      [];
    const copy = log.slice();
    if (shouldClear) {
      log.length = 0;
    }
    return copy;
  }, clear);
}