Skip to content

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

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

/**
 * @file webInput.ts
 * @input Uses a Playwright `Page` (Chromium or WebKit)
 * @output `webInputDriver(page)`: a wheel step (`wheel({x, y, dx, dy, ctrl})`),
 *   a run of wheel steps as one gesture (`wheelBurst({x, y, steps})`) and a
 *   pen stroke (`pen(points)`) as REAL engine input, for proofs that the same
 *   motion works for every pointer, not only a finger (`spec:AST-100` FR4).
 * @position The non-touch half of the input drivers; touch.ts is the touch
 *   half and owns the input log both are read through. Untrusted DOM events
 *   are not input (a component can tell them apart with `isTrusted`), so both
 *   go through the engine's own input pipeline.
 *
 * Chromium: CDP `Input.dispatchMouseEvent`.
 * - A wheel step is a `mouseWheel` event at (x, y). Chromium divides the
 *   deltas it delivers by the device scale factor times the visual viewport's
 *   scale, so the driver multiplies them back: the page receives exactly `dx`
 *   and `dy` CSS px, in pixel mode (`deltaMode` 0). `ctrl` holds Control, as a
 *   trackpad pinch arrives. On a page whose wheel listeners are all passive
 *   (every page with the input log), Chromium answers the dispatch at once
 *   and delivers the step to the page afterwards, so `wheel` waits, through a
 *   one-shot passive listener, until the page has the step.
 * - A pen stroke is pressed at its first point, moved through every point and
 *   released at the last, with `pointerType: 'pen'`, a pressure and an
 *   optional tilt, each event stamped with its scripted time: the page
 *   receives trusted pen pointer events (and the compatibility mouse events)
 *   with those timestamps. The stroke starts once the page has presented two
 *   frames: the press goes out with no page round trip, so right after a
 *   navigation it could carry the previous document's page scale (about:blank
 *   scales a press at 100 px to 41 px in the phone project).
 * - A pen stroke over a native scroller does not pan it: Chromium sends the
 *   pen through its mouse pipeline, so the stroke scrolls nothing, raises no
 *   `pointercancel` and ends in a `click`.
 *
 * WebKit (Playwright's Linux build): `page.mouse.wheel` in a desktop context
 * (`isMobile: false`, `hasTouch: false`), waiting the same way. The step
 * moves the mouse to (x, y) first (a `pointermove`) and holds Control as a key,
 * which Chromium's step does neither. WebKit's mobile emulation has no
 * wheel input, and Playwright has no pen for WebKit: both throw, naming the
 * reason, so a proof skips on the driver's flags instead.
 *
 * SYNC: Keep the engine limits above equal to the README's table and to the
 *   harness self-test (../src/harness.interaction.browser.spec.ts).
 */

import type {CDPSession, JSHandle, Page} from '@playwright/test';
import type {Engine} from './touch';

/** One wheel step: the page receives exactly `dx`, `dy` CSS px. */
export interface WheelInput {
  readonly x: number;
  readonly y: number;
  readonly dx?: number;
  readonly dy?: number;
  /** Hold Control during the step (a trackpad pinch arrives as a ctrl wheel). */
  readonly ctrl?: boolean;
}

/** A run of wheel steps at one point: one continuous wheel gesture. */
export interface WheelBurst {
  readonly x: number;
  readonly y: number;
  /** Each step's deltas, in order: the page receives exactly these CSS px. */
  readonly steps: readonly {readonly dx?: number; readonly dy?: number}[];
  /** Ms between the steps' dispatch (default 16, a frame). */
  readonly everyMs?: number;
  /** Hold Control through the run. */
  readonly ctrl?: boolean;
  /**
   * The longest gap the page may see between two received steps, ms (see
   * `wheelArrivals`). Past it, the proof's component would treat the run as
   * more than one gesture. Past it `wheelBurst` throws
   * `WheelPageStallError` when the page held the gap, and `WheelPacingError`
   * otherwise. The page holds it while it handles the step before, or while
   * it draws no frame.
   */
  readonly maxGapMs?: number;
}

/**
 * The page received a wheel burst's steps further apart than the proof's
 * `maxGapMs`, and its wheel listeners did not hold the step back: the step
 * reached the page later than one frame after they finished the one before,
 * or the gap was no wider than the harness's own spacing of the sends (the
 * page can only widen a gap, so a starved renderer that also held the step
 * lands here). The dispatch stalled before the page, so a loaded runner
 * splits what the driver sent as one gesture. Other work between steps that
 * leaves the page's frames running also lands here. Such a stall is the
 * runner's or that work's, never the wheel listeners'.
 */
export class WheelPacingError extends Error {
  constructor(
    readonly maxGapMs: number,
    readonly receivedGapsMs: readonly number[],
  ) {
    super(
      `webInputDriver: the page received the wheel burst with a gap of ${Math.max(...receivedGapsMs).toFixed(0)} ms, over its ${maxGapMs} ms (gaps ${receivedGapsMs.map(g => g.toFixed(0)).join(', ')} ms): the dispatch stalled before the page, so the page saw more than one gesture`,
    );
    this.name = 'WheelPacingError';
  }
}

/**
 * The page received a wheel burst's steps further apart than the proof's
 * `maxGapMs` while its main thread was held. Its own wheel listeners were
 * still handling the step before, or the page drew no frame across the gap.
 * WebKit dispatches the next step only once the thread is free. Both
 * times are page wall time. On a starved runner they include the page's wait
 * for a CPU, and a renderer held from outside draws no frame either. Judge a
 * page stall from a run with CI's CPU limits: there it is the proof's own
 * failure.
 */
export class WheelPageStallError extends Error {
  constructor(
    readonly maxGapMs: number,
    readonly stall: WheelPageStall,
  ) {
    super(
      stall.frameGapMs == null
        ? `webInputDriver: the page's own wheel listeners took ${stall.handlingMs.toFixed(0)} ms of page wall time to handle a step, so the next reached it ${stall.gapMs.toFixed(0)} ms later, over its ${maxGapMs} ms: the page split the run. 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`
        : `webInputDriver: the page drew no frame for ${stall.frameGapMs.toFixed(0)} ms around a ${stall.gapMs.toFixed(0)} ms gap between two wheel steps, over its ${maxGapMs} ms (engine or page work), while its own wheel listeners took ${stall.handlingMs.toFixed(0)} ms: the page split the run. On a starved runner the renderer draws no frame either: judge a page stall from a run with CI's CPU limits`,
    );
    this.name = 'WheelPageStallError';
  }
}

/**
 * A gap the page caused: how long it was, and how long the page spent
 * handling the step before it. `frameGapMs` is set when the page drew no
 * frame across the gap instead.
 */
export interface WheelPageStall {
  readonly gapMs: number;
  readonly handlingMs: number;
  readonly frameGapMs?: number;
}

/**
 * How soon after the page's input listeners finish one event the next must
 * reach the page for the page to have held it back: one frame, with a few ms
 * for the dispatch itself. The wheel and the touch paths both read it.
 */
export const HELD_BACK_MS = 20;

/**
 * When each received step of a burst reached the page, ms on the page clock:
 * its `timeStamp` in Chromium, which stamps a step with its dispatch time; in
 * WebKit, when the page's first listener received it. WebKit coalesces the
 * steps it holds while the page's main thread is busy, and the coalesced step
 * keeps the stamp of the step before it, so its stamp cannot show how long the
 * page made it wait.
 */
export function wheelArrivals(
  engine: Engine,
  stamps: readonly number[],
  receivedAt: readonly number[],
): readonly number[] {
  return engine === 'webkit' ? receivedAt : stamps;
}

/**
 * How far apart the harness sent the steps behind each received gap, ms
 * (`sendGapsMs[i - 1]` for the gap before received step `i`), or `null` where
 * the received steps cannot be matched to the sent ones. A received step is
 * matched to the sent steps its deltas reach: WebKit coalesces the steps it
 * holds into one that carries their summed deltas. The gap is spaced from the
 * last sent step the step before carried to the first sent step this one
 * carries, the send the page could have held: spacing it by the last carried
 * step would let a late first step lend the gap its delay.
 */
export function wheelSendGaps(
  steps: readonly {readonly dx?: number; readonly dy?: number}[],
  sentAt: readonly number[],
  deltas: readonly (readonly [number, number])[],
): (number | null)[] {
  const close = (a: number, b: number) => Math.abs(a - b) < 0.01;
  // What the page has received after each sent step, if it received them all.
  const sentSums: [number, number][] = [];
  let sx = 0;
  let sy = 0;
  for (const {dx = 0, dy = 0} of steps) {
    sx += dx;
    sy += dy;
    sentSums.push([sx, sy]);
  }
  let rx = 0;
  let ry = 0;
  let from = 0;
  const lastSent = deltas.map(([dx, dy]) => {
    rx += dx;
    ry += dy;
    for (let j = from; j < sentSums.length; j++) {
      if (close(sentSums[j][0], rx) && close(sentSums[j][1], ry)) {
        from = j + 1;
        return j;
      }
    }
    return null;
  });
  return lastSent.slice(1).map((j, i) => {
    const before = lastSent[i];
    return j == null || before == null || j <= before
      ? null
      : sentAt[before + 1] - sentAt[before];
  });
}

/**
 * Sorts a burst's gaps past `maxGapMs` by cause. `stamps` are when the
 * received steps reached the page (`wheelArrivals`). `handledAt` is when the
 * page's wheel listeners had finished with each, NaN unseen. For a step whose
 * propagation the page stopped, it is when a task queued at its arrival ran.
 * `sendGapsMs` is how far apart the harness sent the steps behind each gap
 * (`wheelSendGaps`; `null` where unknown). WebKit dispatches a step only once
 * the page's main thread is free. There a gap is the page's when the step
 * reached it within one frame of the listeners finishing the step before. It
 * waited on them. The gap must also be more than a frame wider than the
 * harness's own spacing of those steps. The page can only widen a gap, so one
 * no wider than the send spacing is the dispatch's. That holds even when a
 * starved renderer also held the step, as a runner whose CPU quota holds the
 * page right after its listeners does. A WebKit gap is the page's too when
 * `frames`, the page's frame times, show none across nearly all of it. Then
 * engine or page work held the main thread, or a starved runner held the
 * renderer, not the page's wheel listeners.
 * Every other gap is the dispatch's. In Chromium, which stamps a step with
 * its dispatch time, the page cannot move its stamps, so every gap is. Other
 * work between steps that leaves frames running counts as the dispatch's,
 * unless it ran before a stopped step's marking task.
 */
export function wheelGapCauses(
  engine: Engine,
  stamps: readonly number[],
  handledAt: readonly number[],
  maxGapMs: number,
  sendGapsMs: readonly (number | null)[] = [],
  frames: readonly number[] = [],
): {pageStalls: WheelPageStall[]; dispatchStalls: number[]} {
  const pageStalls: WheelPageStall[] = [];
  const dispatchStalls: number[] = [];
  for (let i = 1; i < stamps.length; i++) {
    const gapMs = stamps[i] - stamps[i - 1];
    if (gapMs <= maxGapMs) {
      continue;
    }
    const sendGapMs = sendGapsMs[i - 1];
    const widened = sendGapMs == null || gapMs > sendGapMs + HELD_BACK_MS;
    const handlingMs = handledAt[i - 1] - stamps[i - 1];
    const heldBack =
      engine === 'webkit' &&
      Number.isFinite(handledAt[i - 1]) &&
      stamps[i] - handledAt[i - 1] <= HELD_BACK_MS &&
      widened;
    const frameGap =
      engine === 'webkit' && widened
        ? frameGapAcross(frames, stamps[i - 1], stamps[i])
        : null;
    if (heldBack) {
      pageStalls.push({gapMs, handlingMs});
    } else if (frameGap != null && frameGap.covered >= gapMs - HELD_BACK_MS) {
      pageStalls.push({
        gapMs,
        handlingMs: Number.isFinite(handlingMs) ? handlingMs : 0,
        frameGapMs: frameGap.gapMs,
      });
    } else {
      dispatchStalls.push(gapMs);
    }
  }
  return {pageStalls, dispatchStalls};
}

/**
 * The page's longest stretch without a frame inside `from` to `to`. It gives
 * how much of that span the stretch covers, and the whole gap between its two
 * frames. Null with fewer than two frames.
 */
function frameGapAcross(
  frames: readonly number[],
  from: number,
  to: number,
): {covered: number; gapMs: number} | null {
  let best: {covered: number; gapMs: number} | null = null;
  for (let k = 1; k < frames.length; k++) {
    const covered = Math.min(frames[k], to) - Math.max(frames[k - 1], from);
    if (covered > 0 && (best == null || covered > best.covered)) {
      best = {covered, gapMs: frames[k] - frames[k - 1]};
    }
  }
  return best;
}

/** A point of a pen stroke. */
export interface PenPoint {
  readonly x: number;
  readonly y: number;
  /** Ms after the stroke's first point. */
  readonly t: number;
  /** 0–1 (default 0.5) while the pen touches. */
  readonly pressure?: number;
  /** Degrees, -90–90 (default 0). */
  readonly tiltX?: number;
  readonly tiltY?: number;
}

export interface WebInputDriver {
  readonly engine: Engine;
  /** Whether `wheel` works in this page (WebKit's mobile emulation has none). */
  readonly wheels: boolean;
  /** Whether `pen` works in this page (Chromium only). */
  readonly pens: boolean;
  wheel(input: WheelInput): Promise<void>;
  /**
   * Sends a run of steps at one point on its schedule, without waiting for
   * each step's round trip as `wheel` does, and resolves once the page has
   * received the run's whole delta. Awaited steps land as far apart as a
   * round trip takes on a loaded runner (49 to 141 ms in WebKit), past the
   * 100 ms a proof may allow between the steps of one gesture. Where the page still
   * handles one step when the next arrives, the engine coalesces them, as it
   * does a trackpad's: the page can receive fewer, larger steps with the same
   * total. Returns how many steps the page received and the gaps between
   * their arrivals (`wheelArrivals`), ms. With `maxGapMs`, a longer gap throws
   * `WheelPageStallError` when the page held it, and `WheelPacingError`
   * otherwise. The page holds a gap while it handles the step before, or
   * while it draws no frame.
   */
  wheelBurst(burst: WheelBurst): Promise<{
    readonly receivedSteps: number;
    readonly receivedGapsMs: readonly number[];
  }>;
  /** Presses at the first point, moves through all of them, releases at the last; paced on the wall clock. */
  pen(points: readonly PenPoint[]): Promise<void>;
}

/** Why a proof skips when the driver has no wheel in this page. */
export const WHEEL_SKIP =
  "WebKit's mobile emulation has no wheel input: run wheel proofs in a desktop context";
/** Why a proof skips when the driver has no pen. */
export const PEN_SKIP =
  'Playwright has no pen input for WebKit: pen proofs run in Chromium';

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

/** How long `wheel` waits for the page to receive its step. */
const WHEEL_DELIVERY_MS = 2000;

/**
 * Arms a one-shot passive capture listener for the page's next wheel step,
 * before the step is dispatched. Passive, so the page's own listeners keep
 * deciding whether the engine waits for it. (The promise sits in an object:
 * a handle to a bare promise would wait for it to settle.)
 */
function armWheel(page: Page): Promise<JSHandle<{received: Promise<void>}>> {
  return page.evaluateHandle(() => ({
    received: new Promise<void>(resolve => {
      window.addEventListener('wheel', () => resolve(), {
        capture: true,
        once: true,
        passive: true,
      });
    }),
  }));
}

/** Waits until the armed listener has seen the step; throws past the limit. */
async function untilReceived(
  page: Page,
  armed: JSHandle<{received: Promise<void>}>,
): Promise<void> {
  const received = await page.evaluate(
    ([box, ms]) => {
      // The harness's own wait runs on the real timer: a frozen timer gate
      // (story.ts) holds only the page's.
      const later =
        (
          window as unknown as {
            __harnessTimerGate?: {timeout?: typeof setTimeout};
          }
        ).__harnessTimerGate?.timeout ?? window.setTimeout.bind(window);
      return Promise.race([
        box.received.then(() => true),
        new Promise<boolean>(resolve => later(() => resolve(false), ms)),
      ]);
    },
    [armed, WHEEL_DELIVERY_MS] as const,
  );
  await armed.dispose();
  if (!received) {
    throw new Error(
      `webInputDriver: the page did not receive the wheel step within ${WHEEL_DELIVERY_MS} ms (is the point inside the viewport, over the main document?)`,
    );
  }
}

/** What the page saw of each input event of one run (`armInputRun`). */
export interface InputRun {
  /** The event types the run records. */
  types: string[];
  /** Each event's own `timeStamp`. */
  stamps: number[];
  /** When the page's first listener received each event. */
  receivedAt: number[];
  /** When the page drew each frame during the run, with `frames` asked. */
  frames: number[];
  /**
   * True while every event of the run carries the mark `installInputStart`
   * added before the page's scripts. Then `receivedAt` comes before every
   * page listener.
   */
  startsFirst: boolean;
  /**
   * When the page's own listeners had finished with each event, NaN until
   * seen. An event whose propagation the page stops is marked by a task
   * queued when it arrived, and never later than the next event's arrival.
   * So page work queued before that task, such as a timer, counts as its
   * handling.
   */
  handledAt: number[];
  /** Each event's type. */
  eventTypes: string[];
  /** Each event's pointer type, or '' for an event that has none. */
  pointerTypes: string[];
  /** Each wheel step's deltas, CSS px: a coalesced step carries the sum. */
  deltas: [number, number][];
  dx: number;
  dy: number;
  /** Removes the listeners and settles every handling mark. */
  stop: () => void;
}

/**
 * Marks when the page's listeners begin on each trusted event of `types`,
 * with a passive window capture listener. Added before the page's scripts, it
 * runs before every page listener, a window capture one included, and
 * `armInputRun` uses its mark. A page already loaded gets it too. There it
 * runs after the window capture listeners the page added at load, such as a
 * gesture host's, so its mark is not used.
 */
export async function installInputStart(
  page: Page,
  types: readonly string[],
): Promise<void> {
  await installInputStartBeforeLoad(page, types);
  await page.evaluate(inputStartScript(types, false));
}

/**
 * Adds the `installInputStart` mark to each page the tab loads next, before
 * the page's scripts. The page loaded now gets no mark. A driver created after
 * the next load then uses the mark.
 */
export async function installInputStartBeforeLoad(
  page: Page,
  types: readonly string[],
): Promise<void> {
  await page.addInitScript(inputStartScript(types, true));
}

function inputStartScript(types: readonly string[], first: boolean): string {
  return `(() => {
  if (window.__harnessInputStart) return;
  const starts = new WeakMap();
  window.__harnessInputStart = {starts, first: ${first}};
  for (const type of ${JSON.stringify([...types])}) {
    window.addEventListener(type, event => {
      if (event.isTrusted && !starts.has(event)) starts.set(event, performance.now());
    }, {capture: true, passive: true});
  }
})()`;
}

/**
 * Arms two passive listeners on the window before a run is dispatched. A
 * capture listener stamps each trusted event of `types` before the page's
 * own listeners. A bubble listener, after them, notes when the page has
 * finished with the event. The wheel and touch drivers share it. Where
 * `installInputStart` marked, before the page's scripts, when the page's
 * listeners began on an event, that mark is the event's `receivedAt`.
 */
export function armInputRun(
  page: Page,
  types: readonly string[],
  {frames = false}: {readonly frames?: boolean} = {},
): Promise<JSHandle<InputRun>> {
  return page.evaluateHandle(
    ([eventTypes, recordFrames]) => {
      const first = {capture: true, passive: true};
      const last = {capture: false, passive: true};
      const index = new WeakMap<Event, number>();
      // A message runs as a task of its own, after the dispatch that queued
      // it: it marks an event whose bubble listener never ran.
      const channel = new MessageChannel();
      const mark = (
        window as unknown as {
          __harnessInputStart?: {
            starts: WeakMap<Event, number>;
            first: boolean;
          };
        }
      ).__harnessInputStart;
      let drawing = recordFrames;
      const run = {
        types: [...eventTypes],
        stamps: [] as number[],
        receivedAt: [] as number[],
        startsFirst: mark?.first === true,
        frames: [] as number[],
        handledAt: [] as number[],
        eventTypes: [] as string[],
        pointerTypes: [] as string[],
        deltas: [] as [number, number][],
        dx: 0,
        dy: 0,
        stop: () => {
          drawing = false;
          for (const type of eventTypes) {
            window.removeEventListener(type, received, first);
            window.removeEventListener(type, handled, last);
          }
          channel.port1.onmessage = null;
          channel.port1.close();
          for (let i = 0; i + 1 < run.handledAt.length; i++) {
            run.handledAt[i] = Math.min(
              run.handledAt[i],
              run.receivedAt[i + 1],
            );
          }
        },
      };
      channel.port1.onmessage = (message: MessageEvent<number>) => {
        if (Number.isNaN(run.handledAt[message.data])) {
          run.handledAt[message.data] = performance.now();
        }
      };
      const received = (event: Event) => {
        if (!event.isTrusted) {
          return;
        }
        const i = run.stamps.length;
        index.set(event, i);
        run.stamps.push(event.timeStamp);
        const markedAt = run.startsFirst ? mark?.starts.get(event) : undefined;
        // A page that reopens its document drops the mark's listener but
        // keeps the mark. Its events go unmarked, and the run reads as before.
        if (markedAt == null) {
          run.startsFirst = false;
        }
        run.receivedAt.push(markedAt ?? performance.now());
        run.handledAt.push(Number.NaN);
        run.eventTypes.push(event.type);
        run.pointerTypes.push(
          'pointerType' in event ? String(event.pointerType) : '',
        );
        const wheel = event.type === 'wheel' ? (event as WheelEvent) : null;
        run.deltas.push([wheel?.deltaX ?? 0, wheel?.deltaY ?? 0]);
        run.dx += wheel?.deltaX ?? 0;
        run.dy += wheel?.deltaY ?? 0;
        channel.port2.postMessage(i);
      };
      const handled = (event: Event) => {
        const i = index.get(event);
        if (i != null) {
          run.handledAt[i] = performance.now();
        }
      };
      for (const type of eventTypes) {
        window.addEventListener(type, received, first);
        window.addEventListener(type, handled, last);
      }
      // The page's own frames, on the real frame loop: a frozen timer gate
      // (story.ts) holds only the page's.
      const frame =
        (
          window as unknown as {
            __harnessTimerGate?: {frame?: typeof requestAnimationFrame};
          }
        ).__harnessTimerGate?.frame ??
        window.requestAnimationFrame.bind(window);
      const draw = () => {
        if (drawing) {
          run.frames.push(performance.now());
          frame(draw);
        }
      };
      if (recordFrames) {
        frame(draw);
      }
      return run;
    },
    [[...types], frames] as const,
  );
}

/**
 * Waits until the armed listener has summed the run's whole delta and returns
 * what it received; throws past the limit, naming how much arrived.
 */
async function untilRunReceived(
  page: Page,
  engine: Engine,
  armed: JSHandle<InputRun>,
  {steps, maxGapMs}: Pick<WheelBurst, 'steps' | 'maxGapMs'>,
  sentAt: readonly number[],
): Promise<{receivedSteps: number; receivedGapsMs: number[]}> {
  const want = steps.reduce<{dx: number; dy: number}>(
    (sum, {dx = 0, dy = 0}) => ({dx: sum.dx + dx, dy: sum.dy + dy}),
    {dx: 0, dy: 0},
  );
  const got = await page.evaluate(
    ([run, total, ms]) =>
      new Promise<{
        stamps: number[];
        receivedAt: number[];
        frames: number[];
        handledAt: number[];
        deltas: [number, number][];
        dx: number;
        dy: number;
      }>(resolve => {
        // The harness's own wait runs on the real timer: a frozen timer gate
        // (story.ts) holds only the page's.
        const gate = (
          window as unknown as {
            __harnessTimerGate?: {
              now?: () => number;
              timeout?: typeof setTimeout;
            };
          }
        ).__harnessTimerGate;
        const later = gate?.timeout ?? window.setTimeout.bind(window);
        // The deadline reads the real clock, which a page freeze does not stop.
        const realNow = gate?.now ?? (() => performance.now());
        const deadline = realNow() + ms;
        const whole = () =>
          Math.abs(run.dx - total.dx) < 0.01 &&
          Math.abs(run.dy - total.dy) < 0.01;
        const check = () => {
          if (whole() || realNow() > deadline) {
            run.stop();
            resolve({
              stamps: run.stamps.slice(),
              receivedAt: run.receivedAt.slice(),
              frames: run.frames.slice(),
              handledAt: run.handledAt.slice(),
              deltas: run.deltas.slice(),
              dx: run.dx,
              dy: run.dy,
            });
          } else {
            later(check, 10);
          }
        };
        check();
      }),
    [armed, want, WHEEL_DELIVERY_MS] as const,
  );
  await armed.dispose();
  if (
    Math.abs(got.dx - want.dx) >= 0.01 ||
    Math.abs(got.dy - want.dy) >= 0.01
  ) {
    throw new Error(
      `webInputDriver: the page received ${got.dx}, ${got.dy} px of the run's ${want.dx}, ${want.dy} px within ${WHEEL_DELIVERY_MS} ms (is the point inside the viewport, over the main document?)`,
    );
  }
  const arrivals = wheelArrivals(engine, got.stamps, got.receivedAt);
  const receivedGapsMs = arrivals.slice(1).map((t, i) => t - arrivals[i]);
  if (maxGapMs != null) {
    const {pageStalls, dispatchStalls} = wheelGapCauses(
      engine,
      arrivals,
      got.handledAt,
      maxGapMs,
      wheelSendGaps(steps, sentAt, got.deltas),
      got.frames,
    );
    if (pageStalls.length > 0) {
      throw new WheelPageStallError(maxGapMs, pageStalls[0]);
    }
    if (dispatchStalls.length > 0) {
      throw new WheelPacingError(maxGapMs, receivedGapsMs);
    }
  }
  return {receivedSteps: got.stamps.length, receivedGapsMs};
}

/**
 * Sends each step at its scheduled time without awaiting the one before, then
 * waits until every dispatch is answered. Resolves with when each step left
 * (`Date.now()`, ms).
 */
async function dispatchOnSchedule<T>(
  steps: readonly T[],
  everyMs: number,
  send: (step: T) => Promise<unknown>,
): Promise<number[]> {
  const start = Date.now();
  const sent: Promise<unknown>[] = [];
  const sentAt: number[] = [];
  for (const [i, step] of steps.entries()) {
    const wait = start + i * everyMs - Date.now();
    if (wait > 0) {
      await sleep(wait);
    }
    sentAt.push(Date.now());
    sent.push(send(step));
  }
  await Promise.all(sent);
  return sentAt;
}

async function chromiumWebInput(page: Page): Promise<WebInputDriver> {
  const cdp: CDPSession = await page.context().newCDPSession(page);
  return {
    engine: 'chromium',
    wheels: true,
    pens: true,
    async wheel({x, y, dx = 0, dy = 0, ctrl = false}) {
      const scale = await page.evaluate(
        () => window.devicePixelRatio * (window.visualViewport?.scale ?? 1),
      );
      const armed = await armWheel(page);
      await cdp.send('Input.dispatchMouseEvent', {
        type: 'mouseWheel',
        x,
        y,
        deltaX: dx * scale,
        deltaY: dy * scale,
        modifiers: ctrl ? 2 : 0,
      });
      await untilReceived(page, armed);
    },
    async wheelBurst({x, y, steps, everyMs = 16, ctrl = false, maxGapMs}) {
      const scale = await page.evaluate(
        () => window.devicePixelRatio * (window.visualViewport?.scale ?? 1),
      );
      const armed = await armInputRun(page, ['wheel']);
      const sentAt = await dispatchOnSchedule(
        steps,
        everyMs,
        ({dx = 0, dy = 0}) =>
          cdp.send('Input.dispatchMouseEvent', {
            type: 'mouseWheel',
            x,
            y,
            deltaX: dx * scale,
            deltaY: dy * scale,
            modifiers: ctrl ? 2 : 0,
          }),
      );
      return untilRunReceived(
        page,
        'chromium',
        armed,
        {steps, maxGapMs},
        sentAt,
      );
    },
    async pen(points) {
      if (points.length === 0) {
        return;
      }
      // Two presented frames first: the press reaches the compositor with no
      // page round trip, and right after a navigation it could still carry
      // the previous document's page scale. The harness's own frames, not a
      // frozen timer gate's (story.ts).
      await page.evaluate(
        () =>
          new Promise<void>(resolve => {
            const gate = (
              window as unknown as {
                __harnessTimerGate?: {frame?: typeof requestAnimationFrame};
              }
            ).__harnessTimerGate;
            const frame =
              gate?.frame ?? window.requestAnimationFrame.bind(window);
            frame(() => frame(() => resolve()));
          }),
      );
      const startWall = Date.now();
      const startStamp = Date.now() / 1000;
      const events = [
        {type: 'mousePressed' as const, point: points[0]},
        ...points.slice(1).map(point => ({type: 'mouseMoved' as const, point})),
        {type: 'mouseReleased' as const, point: points[points.length - 1]},
      ];
      for (const {type, point} of events) {
        const wait = startWall + point.t - Date.now();
        if (wait > 0) {
          await sleep(wait);
        }
        await cdp.send('Input.dispatchMouseEvent', {
          type,
          x: point.x,
          y: point.y,
          button: 'left',
          buttons: type === 'mouseReleased' ? 0 : 1,
          clickCount: type === 'mouseMoved' ? 0 : 1,
          pointerType: 'pen',
          force: type === 'mouseReleased' ? 0 : (point.pressure ?? 0.5),
          tiltX: point.tiltX ?? 0,
          tiltY: point.tiltY ?? 0,
          timestamp: startStamp + point.t / 1000,
        });
      }
    },
  };
}

async function webkitWebInput(page: Page): Promise<WebInputDriver> {
  // Playwright refuses a wheel in a WebKit context that emulates a phone: read
  // the option it reads, the context's `isMobile`.
  const mobile =
    (page.context() as unknown as {_options?: {isMobile?: boolean}})._options
      ?.isMobile === true;
  return {
    engine: 'webkit',
    wheels: !mobile,
    pens: false,
    async wheel({x, y, dx = 0, dy = 0, ctrl = false}) {
      if (mobile) {
        throw new Error(`webInputDriver: ${WHEEL_SKIP}`);
      }
      await page.mouse.move(x, y);
      if (ctrl) {
        await page.keyboard.down('Control');
      }
      try {
        const armed = await armWheel(page);
        await page.mouse.wheel(dx, dy);
        await untilReceived(page, armed);
      } finally {
        if (ctrl) {
          await page.keyboard.up('Control');
        }
      }
    },
    async wheelBurst({x, y, steps, everyMs = 16, ctrl = false, maxGapMs}) {
      if (mobile) {
        throw new Error(`webInputDriver: ${WHEEL_SKIP}`);
      }
      await page.mouse.move(x, y);
      if (ctrl) {
        await page.keyboard.down('Control');
      }
      try {
        const armed = await armInputRun(page, ['wheel'], {frames: true});
        const sentAt = await dispatchOnSchedule(
          steps,
          everyMs,
          ({dx = 0, dy = 0}) => page.mouse.wheel(dx, dy),
        );
        return await untilRunReceived(
          page,
          'webkit',
          armed,
          {steps, maxGapMs},
          sentAt,
        );
      } finally {
        if (ctrl) {
          await page.keyboard.up('Control');
        }
      }
    },
    async pen() {
      throw new Error(`webInputDriver: ${PEN_SKIP}`);
    },
  };
}

/** Wheel and pen input for the page's engine. Firefox is not supported (no project). */
export async function webInputDriver(page: Page): Promise<WebInputDriver> {
  const name = page.context().browser()?.browserType().name();
  if (name === 'chromium') {
    return chromiumWebInput(page);
  }
  if (name === 'webkit') {
    return webkitWebInput(page);
  }
  throw new Error(
    `webInputDriver: no wheel or pen input path for ${name ?? 'this browser'}`,
  );
}