@ultimat3/cli 21.0.0 → 22.0.0

package/src/cdp-shot-a11y.ts

@@ -0,0 +1,77 @@
+// The accessibility tree, read over the page's own CDP session: what the BROWSER computed for a
+// screen reader, after ARIA, label association and `aria-hidden` pruning. A `<div onclick>`
+// answers no role and no name, which is the finding — no read of the markup can reproduce it.
+import type { AxNode } from './browser-launcher-port';
+
+/** One session-scoped CDP call. Every answer is somebody else's JSON, read and never cast. */
+export type SessionSend = (
+  method: string,
+  params?: Record<string, unknown>,
+) => Promise<Readonly<Record<string, unknown>> | undefined>;
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
+
+/** CDP's `AXValue.value` is any scalar; a reader is told text. */
+const textOf = (wrapped: unknown): string | undefined => {
+  const value = record(wrapped)?.['value'];
+  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+    ? String(value)
+    : undefined;
+};
+
+const flagOf = (node: Readonly<Record<string, unknown>>, name: string): boolean | undefined => {
+  const properties = node['properties'];
+  if (!Array.isArray(properties)) return undefined;
+  const found = properties.map(record).find((property) => property?.['name'] === name);
+  return found === undefined ? undefined : record(found['value'])?.['value'] === true;
+};
+
+/**
+ * `nodes[0]` is the element's own node when `fetchRelatives` is false. An EMPTY list is a real
+ * answer — an element that never entered the tree — and is kept as ignored, so the count the
+ * caller gets is the count of matches.
+ */
+export const toAxNode = (answer: Readonly<Record<string, unknown>> | undefined): AxNode => {
+  const nodes = answer?.['nodes'];
+  const node = Array.isArray(nodes) ? record(nodes[0]) : undefined;
+  if (node === undefined) return { role: '', name: '', ignored: true };
+  const description = textOf(node['description']);
+  const value = textOf(node['value']);
+  const focused = flagOf(node, 'focused');
+  const disabled = flagOf(node, 'disabled');
+  return {
+    role: textOf(node['role']) ?? '',
+    name: textOf(node['name']) ?? '',
+    ...(description === undefined ? {} : { description }),
+    ...(value === undefined ? {} : { value }),
+    ...(focused === undefined ? {} : { focused }),
+    ...(disabled === undefined ? {} : { disabled }),
+    ignored: node['ignored'] === true,
+  };
+};
+
+/** Every match of `selector`, in document order, at most `max` — one round trip per match. */
+export async function axNodesFor(
+  send: SessionSend,
+  selector: string,
+  max: number,
+): Promise<readonly AxNode[]> {
+  const root = record(record((await send('DOM.getDocument', { depth: 0 }))?.['root']));
+  const nodeIds = (await send('DOM.querySelectorAll', { nodeId: root?.['nodeId'], selector }))?.[
+    'nodeIds'
+  ];
+  const out: AxNode[] = [];
+  for (const nodeId of Array.isArray(nodeIds) ? nodeIds.slice(0, max) : []) {
+    const described = record((await send('DOM.describeNode', { nodeId }))?.['node']);
+    out.push(
+      toAxNode(
+        await send('Accessibility.getPartialAXTree', {
+          backendNodeId: described?.['backendNodeId'],
+          fetchRelatives: false,
+        }),
+      ),
+    );
+  }
+  return out;
+}

package/src/cdp-shot-clock.ts

@@ -0,0 +1,14 @@
+// The clock a shot session runs on, and the page deadline a run uses when it names none. The
+// system clock and `Bun.sleep`: a test hands `open()` its own `ShotClock`, where sleeping IS
+// advancing, so a 30-second deadline under test finishes in microseconds.
+import { systemClock } from '@ultimat3/core';
+import type { ShotClock } from './browser-launcher-port';
+
+/** A navigation or a wait with no `timeout` of its own gets this. */
+export const DEFAULT_PAGE_TIMEOUT_MS = 30_000;
+
+export const systemShotClock: ShotClock = Object.freeze({
+  now: () => systemClock.now(),
+  monotonic: () => systemClock.monotonic(),
+  sleep: (ms: number) => Bun.sleep(ms),
+});

package/src/cdp-shot-driver.ts

@@ -0,0 +1,150 @@
+// `x shot`'s browser, over raw CDP and with no library: launch Chrome here on its debugging pipe
+// (`@ultimat3/testing`'s launcher, the one the e2e step already runs on) or ATTACH to one somebody
+// else runs over `--cdp-url`. One `open()` is one browser and one page, so a picture's console and
+// network are its own. The page is `cdp-shot-page.ts`; this file is the session around it.
+import type { CdpConnection, LaunchedBrowser } from '@ultimat3/testing';
+import {
+  CdpBrowserMissingError,
+  CdpCallFailedError,
+  CHROME_CANDIDATES,
+  cdpConnect,
+  launchChrome,
+} from '@ultimat3/testing';
+import type { ShotDriver, ShotSession, ShotSessionInit } from './browser-launcher-port';
+import { cdpShotPage } from './cdp-shot-page';
+import { watchPage } from './cdp-shot-watch';
+
+export const CDP_SHOT_DRIVER = 'cdp';
+
+/** What a picture is laid out in when nothing declares a size — the size every earlier shot had. */
+export const DEFAULT_SHOT_VIEWPORT = Object.freeze({ width: 800, height: 600 });
+
+export interface CdpShotDriverOptions {
+  /** Launch this binary here. Ignored when `cdpUrl` is set. */
+  readonly executablePath?: string | undefined;
+  /** Attach here: a provider's `wss://` session, or a sidecar's `http://host:9222`. */
+  readonly cdpUrl?: string | undefined;
+  readonly viewport?: { readonly width: number; readonly height: number } | undefined;
+  /** Test seams: the two ways a connection comes to exist, so no test needs a browser. */
+  readonly launch?:
+    | ((executable: string, timeoutMs: number) => Promise<LaunchedBrowser>)
+    | undefined;
+  readonly connect?: ((endpoint: string, timeoutMs: number) => Promise<CdpConnection>) | undefined;
+  readonly fetchJson?: ((url: string) => Promise<unknown>) | undefined;
+}
+
+const field = (value: unknown, key: string): string | undefined => {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const found = (value as Record<string, unknown>)[key];
+  return typeof found === 'string' ? found : undefined;
+};
+
+/**
+ * A sidecar publishes `http://host:9222`, and the socket is what `/json/version` names. A provider
+ * hands out the socket itself. Either way the answer is one `ws:`/`wss:` url.
+ */
+async function socketUrl(
+  cdpUrl: string,
+  fetchJson: (url: string) => Promise<unknown>,
+): Promise<string> {
+  if (cdpUrl.startsWith('ws://') || cdpUrl.startsWith('wss://')) return cdpUrl;
+  const version = new URL('/json/version', cdpUrl).toString();
+  const socket = field(await fetchJson(version), 'webSocketDebuggerUrl');
+  if (socket === undefined) {
+    throw new CdpCallFailedError({
+      method: `GET ${version}`,
+      detail: 'the endpoint answered no webSocketDebuggerUrl',
+    });
+  }
+  return socket;
+}
+
+const defaultFetchJson = async (url: string): Promise<unknown> => (await fetch(url)).json();
+
+export function cdpShotDriver(options: CdpShotDriverOptions): ShotDriver {
+  const viewport = options.viewport ?? DEFAULT_SHOT_VIEWPORT;
+  const launch =
+    options.launch ??
+    ((executable: string, timeoutMs: number) => launchChrome({ executable, timeoutMs }));
+  const connect =
+    options.connect ??
+    ((endpoint: string, timeoutMs: number) => cdpConnect({ endpoint, timeoutMs }));
+
+  /** The browser half of a session: its connection, and how to end it. */
+  const browser = async (
+    timeoutMs: number,
+  ): Promise<{ connection: CdpConnection; end: () => Promise<void> }> => {
+    if (options.cdpUrl !== undefined) {
+      const endpoint = await socketUrl(options.cdpUrl, options.fetchJson ?? defaultFetchJson);
+      const connection = await connect(endpoint, timeoutMs);
+      return {
+        connection,
+        // BOTH halves: a remote browser is somebody else's bill, and a close that only hung up
+        // would leave it running until the provider timed it out.
+        end: async () => {
+          await connection.send('Browser.close').catch(() => undefined);
+          connection.close();
+        },
+      };
+    }
+    if (options.executablePath === undefined) {
+      throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
+    }
+    const launched = await launch(options.executablePath, timeoutMs);
+    return { connection: launched.connection, end: async () => launched.close() };
+  };
+
+  return {
+    name: CDP_SHOT_DRIVER,
+    async open(init: ShotSessionInit): Promise<ShotSession> {
+      const { connection, end } = await browser(init.timeoutMs);
+      let closed = false;
+      let stopWatch: () => void = () => undefined;
+      const close = async (): Promise<void> => {
+        if (closed) return;
+        closed = true;
+        stopWatch();
+        await end().catch(() => undefined);
+      };
+      try {
+        const created = await connection.send('Target.createTarget', { url: 'about:blank' });
+        const targetId = field(created.result, 'targetId');
+        const attached = await connection.send('Target.attachToTarget', {
+          targetId,
+          flatten: true,
+        });
+        const sessionId = field(attached.result, 'sessionId');
+        if (targetId === undefined || sessionId === undefined) {
+          throw new CdpCallFailedError({
+            method: 'Target.attachToTarget',
+            detail: 'the browser opened a page and answered no target or session id',
+          });
+        }
+        // Watching BEFORE the domains are on, so the first request is already counted.
+        const watch = watchPage({
+          connection,
+          sessionId,
+          clock: init.clock,
+          allowHosts: init.rules.allowHosts,
+        });
+        stopWatch = () => watch.stop();
+        const on = (method: string, params: Record<string, unknown> = {}) =>
+          connection.send(method, params, sessionId);
+        await on('Runtime.enable');
+        await on('Page.enable');
+        await on('Network.enable');
+        await on('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] });
+        await on('Emulation.setDeviceMetricsOverride', {
+          width: viewport.width,
+          height: viewport.height,
+          deviceScaleFactor: 1,
+          mobile: false,
+        });
+        return { page: cdpShotPage({ connection, sessionId, init, watch }), close };
+      } catch (error) {
+        await close();
+        throw error;
+      }
+    },
+  };
+}

package/src/cdp-shot-element.ts

@@ -0,0 +1,147 @@
+// What "the element is ready" means for the raw-CDP shot page: the in-page snapshot of every match
+// (layout box and hit-test included, which no DOM-only check can see), and the poll that waits for
+// the first match to reach a state. Two refusals, because they are two questions: the page does
+// not have the element, or it does and something keeps it from being acted on.
+import type { ActionabilityState, ElementSnapshot, ShotClock } from './browser-launcher-port';
+import { ShotElementMissingError, ShotElementUnreadyError } from './cdp-shot-errors';
+
+/** JSON text, so the answer has one deserialiser: `parseSnapshots` below. */
+export const snapshotExpression = (selector: string): string => `(() => {
+  const out = [];
+  for (const el of document.querySelectorAll(${JSON.stringify(selector)})) {
+    const style = getComputedStyle(el);
+    const rect = el.getBoundingClientRect();
+    const attrs = [];
+    for (const attribute of el.attributes) attrs.push([attribute.name, attribute.value]);
+    const top = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+    out.push({
+      tag: el.tagName.toLowerCase(),
+      attrs,
+      text: (el.textContent || '').replace(/\\s+/g, ' ').trim(),
+      value: typeof el.value === 'string' ? el.value : '',
+      visible: style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0',
+      enabled: el.disabled !== true && el.getAttribute('aria-disabled') !== 'true',
+      box: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
+      hitTarget: top !== null && (top === el || el.contains(top)),
+    });
+  }
+  return JSON.stringify(out);
+})()`;
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+const str = (value: unknown): string => (typeof value === 'string' ? value : '');
+const num = (value: unknown): number => (typeof value === 'number' ? value : 0);
+
+/** Attribute pairs, rebuilt with `fromEntries` so a page's `constructor="…"` stays an own key. */
+const attrsOf = (value: unknown): Readonly<Record<string, string>> =>
+  Object.fromEntries(
+    (Array.isArray(value) ? value : [])
+      .filter((pair): pair is [string, string] => Array.isArray(pair) && pair.length === 2)
+      .map(([name, attr]) => [str(name), str(attr)]),
+  );
+
+/** The page's answer is `unknown` until this reads it. A row that is not an element is dropped. */
+export function parseSnapshots(raw: unknown): readonly ElementSnapshot[] {
+  let rows: unknown;
+  try {
+    rows = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(rows)) return [];
+  const out: ElementSnapshot[] = [];
+  for (const row of rows) {
+    const el = record(row);
+    if (el === undefined || typeof el['tag'] !== 'string') continue;
+    const box = record(el['box']);
+    out.push({
+      tag: el['tag'],
+      attrs: attrsOf(el['attrs']),
+      text: str(el['text']),
+      value: str(el['value']),
+      visible: el['visible'] === true,
+      enabled: el['enabled'] === true,
+      box: {
+        x: num(box?.['x']),
+        y: num(box?.['y']),
+        width: num(box?.['width']),
+        height: num(box?.['height']),
+      },
+      hitTarget: el['hitTarget'] === true,
+    });
+  }
+  return out;
+}
+
+const sameBox = (a: ElementSnapshot, b: ElementSnapshot): boolean =>
+  a.box?.x === b.box?.x &&
+  a.box?.y === b.box?.y &&
+  a.box?.width === b.box?.width &&
+  a.box?.height === b.box?.height;
+
+/** Why this snapshot is not yet at `state`, or `undefined` when it is. Still = two polls agree. */
+export function unreadiness(
+  current: ElementSnapshot,
+  previous: ElementSnapshot | undefined,
+  state: ActionabilityState,
+): string | undefined {
+  if (state === 'attached') return undefined;
+  if (!current.visible) return 'not visible';
+  if (current.box !== undefined && (current.box.width === 0 || current.box.height === 0)) {
+    return 'a zero-sized box';
+  }
+  if (state === 'visible') return undefined;
+  if (!current.enabled) return 'disabled';
+  if (state === 'enabled') return undefined;
+  if (current.hitTarget === false) return 'covered by another element at its centre';
+  if (previous === undefined || !sameBox(current, previous)) return 'moving';
+  return undefined;
+}
+
+export const READY_POLL_MS = 50;
+
+export interface ReadyWait {
+  readonly selector: string;
+  readonly state: ActionabilityState;
+  readonly timeoutMs: number;
+  readonly clock: ShotClock;
+  /** Re-read on every poll: never a handle captured before the loop. */
+  readonly snapshot: () => Promise<ElementSnapshot | undefined>;
+  readonly url: () => string;
+}
+
+/** Poll until the first match reaches `state`, or refuse with the reason it never did. */
+export async function awaitReady(wait: ReadyWait): Promise<ElementSnapshot> {
+  const started = wait.clock.monotonic();
+  let previous: ElementSnapshot | undefined;
+  let problem: string | undefined;
+  let seen = false;
+  for (;;) {
+    const current = await wait.snapshot();
+    if (current !== undefined) {
+      seen = true;
+      problem = unreadiness(current, previous, wait.state);
+      if (problem === undefined) return current;
+      previous = current;
+    }
+    const left = wait.timeoutMs - (wait.clock.monotonic() - started);
+    if (!(left > 0)) break;
+    await wait.clock.sleep(Math.max(1, Math.min(READY_POLL_MS, left)));
+  }
+  if (!seen) {
+    throw new ShotElementMissingError({
+      selector: wait.selector,
+      url: wait.url(),
+      timeoutMs: wait.timeoutMs,
+    });
+  }
+  throw new ShotElementUnreadyError({
+    selector: wait.selector,
+    problem: problem ?? 'not ready',
+    timeoutMs: wait.timeoutMs,
+  });
+}

package/src/cdp-shot-errors.ts

@@ -0,0 +1,62 @@
+// The four ways `x shot`'s raw-CDP page refuses a verb. A browser that is
+// missing, dies or never answers is `@ultimat3/testing`'s `X_CDP_*` — the wire is the same one the
+// e2e driver runs on. These four are what only a shot can be wrong about: which host it may open,
+// which element it was pointed at, and which key it was asked to press. Their codes and titles are
+// registered with every other CLI code, in `error-codes.ts` — never a second registration here.
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+
+/** A navigation to a host the run did not allow. Refused before a byte leaves. */
+export class ShotHostRefusedError extends UltimateError {
+  constructor(input: { readonly url: string; readonly allowHosts: readonly string[] }) {
+    super({
+      code: 'X_SHOT_HOST_REFUSED',
+      cause: `${renderCauseValue(input.url)} is on no host in the allow list ${renderCauseValue(input.allowHosts)}`,
+      fix: 'x shot /route --allow-hosts cdn.example.com   # name every extra host the page needs; the app host is always allowed',
+      meta: { allowHosts: [...input.allowHosts] },
+    });
+  }
+}
+
+/** Nothing ever matched: the markup changed, or the selector was never right. */
+export class ShotElementMissingError extends UltimateError {
+  constructor(input: {
+    readonly selector: string;
+    readonly url: string;
+    readonly timeoutMs: number;
+  }) {
+    super({
+      code: 'X_SHOT_ELEMENT_MISSING',
+      cause: `nothing on ${renderCauseValue(input.url)} matched ${renderCauseValue(input.selector)} within ${String(input.timeoutMs)}ms`,
+      fix: 'run ui.inspect on the route first and copy a selector it reports with count >= 1',
+      meta: { selector: input.selector },
+    });
+  }
+}
+
+/** It matched, and something kept it from being acted on: hidden, disabled, covered, moving. */
+export class ShotElementUnreadyError extends UltimateError {
+  constructor(input: {
+    readonly selector: string;
+    readonly problem: string;
+    readonly timeoutMs: number;
+  }) {
+    super({
+      code: 'X_SHOT_ELEMENT_UNREADY',
+      cause: `${renderCauseValue(input.selector)} was still ${renderCauseValue(input.problem)} after ${String(input.timeoutMs)}ms`,
+      fix: 'run ui.inspect with the selector and "a11y": true to see what covers or disables it, then act on that element first',
+      meta: { selector: input.selector, problem: input.problem },
+    });
+  }
+}
+
+/** A chord the grammar refuses — the caller's own literal, so the refusal is terminal. */
+export class ShotKeyInvalidError extends UltimateError {
+  constructor(input: { readonly chord: string; readonly reason: string }) {
+    super({
+      code: 'X_SHOT_KEY_INVALID',
+      cause: `the key chord ${renderCauseValue(input.chord)} ${input.reason}`,
+      fix: "spell it as modifiers then one key, in the browser's names: 'Meta+K', 'Control+Enter', 'Shift+Tab', 'Escape'",
+      meta: { chord: input.chord },
+    });
+  }
+}

package/src/cdp-shot-keys.ts

@@ -0,0 +1,152 @@
+// A key chord — `'Meta+K'`, `'Shift+Tab'`, `'Escape'` — parsed once and turned into the
+// `Input.dispatchKeyEvent` frames a real keyboard would send. Parsed BEFORE any key goes down: a
+// refusal halfway through would leave a modifier held for every later verb on the page.
+import { ShotKeyInvalidError } from './cdp-shot-errors';
+
+/** The four modifiers, in the browser's own names. */
+type Modifier = 'Alt' | 'Control' | 'Meta' | 'Shift';
+
+/** CDP's bit for each modifier. A `Map`, so a chord word like `constructor` is simply absent. */
+const MODIFIER_BITS: ReadonlyMap<string, number> = new Map([
+  ['Alt', 1],
+  ['Control', 2],
+  ['Meta', 4],
+  ['Shift', 8],
+]);
+
+const isModifier = (word: string): word is Modifier => MODIFIER_BITS.has(word);
+
+const bitOf = (modifier: Modifier): number => MODIFIER_BITS.get(modifier) ?? 0;
+
+/** The modifiers that make a key a SHORTCUT rather than a character. */
+const SHORTCUT_BITS = bitOf('Alt') | bitOf('Control') | bitOf('Meta');
+
+/** The named keys a shot presses: code, Windows virtual key code, and the text it types if any. */
+const NAMED_KEYS: ReadonlyMap<string, { code: string; keyCode: number; text?: string }> = new Map([
+  ['Enter', { code: 'Enter', keyCode: 13, text: '\r' }],
+  ['Tab', { code: 'Tab', keyCode: 9 }],
+  ['Escape', { code: 'Escape', keyCode: 27 }],
+  ['Backspace', { code: 'Backspace', keyCode: 8 }],
+  ['Delete', { code: 'Delete', keyCode: 46 }],
+  ['Insert', { code: 'Insert', keyCode: 45 }],
+  ['Home', { code: 'Home', keyCode: 36 }],
+  ['End', { code: 'End', keyCode: 35 }],
+  ['PageUp', { code: 'PageUp', keyCode: 33 }],
+  ['PageDown', { code: 'PageDown', keyCode: 34 }],
+  ['ArrowUp', { code: 'ArrowUp', keyCode: 38 }],
+  ['ArrowDown', { code: 'ArrowDown', keyCode: 40 }],
+  ['ArrowLeft', { code: 'ArrowLeft', keyCode: 37 }],
+  ['ArrowRight', { code: 'ArrowRight', keyCode: 39 }],
+  ['Space', { code: 'Space', keyCode: 32, text: ' ' }],
+  ['Alt', { code: 'AltLeft', keyCode: 18 }],
+  ['Control', { code: 'ControlLeft', keyCode: 17 }],
+  ['Meta', { code: 'MetaLeft', keyCode: 91 }],
+  ['Shift', { code: 'ShiftLeft', keyCode: 16 }],
+  ...Array.from({ length: 12 }, (_, i): [string, { code: string; keyCode: number }] => [
+    `F${String(i + 1)}`,
+    { code: `F${String(i + 1)}`, keyCode: 112 + i },
+  ]),
+]);
+
+/** One key, as the dispatch frames need it. `key` is what `KeyboardEvent.key` will read. */
+export interface KeyDefinition {
+  readonly key: string;
+  readonly code: string;
+  readonly keyCode: number;
+  readonly text?: string | undefined;
+}
+
+/** A printable character, or a named key; `undefined` for a name the browser does not have. */
+export function keyDefinition(key: string): KeyDefinition | undefined {
+  const named = NAMED_KEYS.get(key);
+  if (named !== undefined) return { key: key === 'Space' ? ' ' : key, ...named };
+  if ([...key].length !== 1) return undefined;
+  if (key === ' ') return { key, code: 'Space', keyCode: 32, text: ' ' };
+  const upper = key.toUpperCase();
+  if (/^[A-Z]$/.test(upper))
+    return { key, code: `Key${upper}`, keyCode: upper.charCodeAt(0), text: key };
+  if (/^[0-9]$/.test(key))
+    return { key, code: `Digit${key}`, keyCode: key.charCodeAt(0), text: key };
+  return { key, code: '', keyCode: 0, text: key };
+}
+
+export interface KeyChord {
+  /** In the order written, which is the order they go down; they come up in reverse. */
+  readonly modifiers: readonly Modifier[];
+  readonly key: KeyDefinition;
+}
+
+/** Refuses an empty chord, a trailing `+`, an unknown modifier or key, and a modifier held twice. */
+export function parseKeyChord(chord: string): KeyChord {
+  if (chord === '') throw new ShotKeyInvalidError({ chord, reason: 'is empty' });
+  const parts = chord.split('+');
+  const last = parts.at(-1) ?? '';
+  if (last === '') {
+    throw new ShotKeyInvalidError({ chord, reason: "ends in '+', so it names no key to press" });
+  }
+  const modifiers: Modifier[] = [];
+  for (const word of parts.slice(0, -1)) {
+    if (!isModifier(word)) {
+      throw new ShotKeyInvalidError({
+        chord,
+        reason: `names ${JSON.stringify(word)} as a modifier, and the browser holds only Meta, Control, Alt, Shift`,
+      });
+    }
+    if (modifiers.includes(word)) {
+      throw new ShotKeyInvalidError({ chord, reason: `holds ${word} twice` });
+    }
+    modifiers.push(word);
+  }
+  const key = keyDefinition(last);
+  if (key === undefined) {
+    throw new ShotKeyInvalidError({
+      chord,
+      reason: `names ${JSON.stringify(last)}, which is neither one character nor a key the browser names`,
+    });
+  }
+  return { modifiers, key };
+}
+
+/** One `Input.dispatchKeyEvent` payload. */
+export type KeyFrame = Readonly<Record<string, unknown>>;
+
+const frame = (type: string, key: KeyDefinition, bits: number, text?: string): KeyFrame => ({
+  type,
+  key: key.key,
+  code: key.code,
+  windowsVirtualKeyCode: key.keyCode,
+  modifiers: bits,
+  ...(text === undefined ? {} : { text, unmodifiedText: text }),
+});
+
+/**
+ * Every frame of one chord, in order: each modifier down, the key down and up, the modifiers up in
+ * reverse. A key under Control, Alt or Meta sends NO text — a shortcut types nothing, and a
+ * `keyDown` carrying text would put the letter into whatever field holds focus.
+ */
+export function chordFrames(chord: KeyChord): readonly KeyFrame[] {
+  const frames: KeyFrame[] = [];
+  let bits = 0;
+  for (const modifier of chord.modifiers) {
+    bits |= bitOf(modifier);
+    const held = keyDefinition(modifier);
+    if (held !== undefined) frames.push(frame('rawKeyDown', held, bits));
+  }
+  const shortcut = (bits & SHORTCUT_BITS) !== 0;
+  const text = shortcut ? undefined : chord.key.text;
+  frames.push(frame(text === undefined ? 'rawKeyDown' : 'keyDown', chord.key, bits, text));
+  frames.push(frame('keyUp', chord.key, bits));
+  for (const modifier of [...chord.modifiers].reverse()) {
+    const held = keyDefinition(modifier);
+    bits &= ~bitOf(modifier);
+    if (held !== undefined) frames.push(frame('keyUp', held, bits));
+  }
+  return frames;
+}
+
+/** The frames that type one character into whatever holds focus. */
+export function characterFrames(character: string): readonly KeyFrame[] {
+  const key = keyDefinition(character) ?? { key: character, code: '', keyCode: 0, text: character };
+  const text = key.text ?? character;
+  return [frame('keyDown', key, 0, text), frame('keyUp', key, 0)];
+}