@ultimat3/cli 20.2.1 → 22.0.0

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)];
+}

package/src/cdp-shot-page.ts

@@ -0,0 +1,230 @@
+// One `ShotPage` over one attached CDP session: navigate, read, act, photograph. The session is
+// the driver's (`cdp-shot-driver.ts`), the rings and the allow list are `cdp-shot-watch.ts`'s, and
+// what "ready to act on" means is `cdp-shot-element.ts`'s. Acts are real input — a click is a
+// mouse press at the element's centre, a keystroke is a key event — because an in-page `.click()`
+// skips `pointerdown`, which is what a dialog's backdrop listens to.
+import { assert, finiteCount, hostDecision } from '@ultimat3/core';
+import type { CdpConnection } from '@ultimat3/testing';
+import { CdpCallFailedError, CdpTimeoutError } from '@ultimat3/testing';
+import type {
+  ElementSnapshot,
+  ShotCapture,
+  ShotColorScheme,
+  ShotPage,
+  ShotSessionInit,
+  WaitOptions,
+} from './browser-launcher-port';
+import { axNodesFor } from './cdp-shot-a11y';
+import { awaitReady, parseSnapshots, snapshotExpression } from './cdp-shot-element';
+import { ShotHostRefusedError } from './cdp-shot-errors';
+import { characterFrames, chordFrames, parseKeyChord } from './cdp-shot-keys';
+import type { PageWatch } from './cdp-shot-watch';
+
+export const DEFAULT_ACCESSIBILITY_MAX = 25;
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
+
+/** What the page threw, when `Runtime.evaluate` answered with an exception rather than a value. */
+const thrownIn = (answer: Readonly<Record<string, unknown>> | undefined): string | undefined => {
+  const thrown = record(answer?.['exceptionDetails']);
+  if (thrown === undefined) return undefined;
+  const description = record(thrown['exception'])?.['description'];
+  if (typeof description === 'string') return description.split('\n')[0];
+  const text = thrown['text'];
+  return typeof text === 'string' ? text : 'the expression threw in the page';
+};
+
+const selectorArg = (selector: string): string => JSON.stringify(selector);
+
+export interface CdpShotPageInput {
+  readonly connection: CdpConnection;
+  readonly sessionId: string;
+  readonly init: ShotSessionInit;
+  readonly watch: PageWatch;
+}
+
+export function cdpShotPage(input: CdpShotPageInput): ShotPage {
+  const { connection, sessionId, init, watch } = input;
+  const defaultTimeout = finiteCount(init.name, 'timeoutMs', init.timeoutMs, 1);
+  const send = async (method: string, params: Record<string, unknown> = {}) =>
+    (await connection.send(method, params, sessionId)).result;
+  let current = 'about:blank';
+
+  const evaluate = async (expression: string): Promise<unknown> => {
+    const answer = await send('Runtime.evaluate', {
+      expression,
+      returnByValue: true,
+      awaitPromise: true,
+    });
+    const threw = thrownIn(answer);
+    if (threw !== undefined) {
+      throw new CdpCallFailedError({ method: 'Runtime.evaluate', detail: threw });
+    }
+    return record(answer?.['result'])?.['value'];
+  };
+
+  const query = async (selector: string): Promise<readonly ElementSnapshot[]> =>
+    parseSnapshots(await evaluate(snapshotExpression(selector)));
+
+  const ready = (
+    selector: string,
+    options: WaitOptions | undefined,
+    before?: () => Promise<unknown>,
+  ): Promise<ElementSnapshot> =>
+    awaitReady({
+      selector,
+      state: options?.state ?? 'actionable',
+      timeoutMs: finiteCount('page.waitFor', 'timeout', options?.timeout ?? defaultTimeout, 1),
+      clock: init.clock,
+      url: () => current,
+      snapshot: async () => {
+        await before?.();
+        return (await query(selector))[0];
+      },
+    });
+
+  const key = async (frame: Readonly<Record<string, unknown>>): Promise<void> => {
+    await send('Input.dispatchKeyEvent', { ...frame });
+  };
+
+  const focusOn = (selector: string): Promise<unknown> =>
+    evaluate(`document.querySelector(${selectorArg(selector)})?.focus()`);
+
+  return {
+    url: () => current,
+    async goto(url, options) {
+      if (!hostDecision(url, init.rules.allowHosts).allowed) {
+        throw new ShotHostRefusedError({ url, allowHosts: init.rules.allowHosts });
+      }
+      const timeoutMs = finiteCount('page.goto', 'timeout', options?.timeout ?? defaultTimeout, 1);
+      // The waiter goes up BEFORE the send, and the reply is raced rather than awaited: Chrome
+      // drops `Page.navigate`'s reply when the navigation swaps the render process
+      // (`@ultimat3/testing`'s `cdp-e2e-page.ts` measured it), and the load event still fires.
+      const loaded = connection.once('Page.loadEventFired', sessionId, timeoutMs);
+      const answered = send('Page.navigate', { url }).then(
+        (answer) => {
+          const failed = answer?.['errorText'];
+          return typeof failed === 'string' && failed !== '' ? failed : undefined;
+        },
+        () => undefined,
+      );
+      const first = await Promise.race([
+        loaded.then((fired) => ({ fired, failed: undefined })),
+        answered.then((failed) => ({ fired: undefined, failed })),
+      ]);
+      if (first.failed !== undefined) {
+        throw new CdpCallFailedError({ method: `Page.navigate to ${url}`, detail: first.failed });
+      }
+      const fired = first.fired ?? (await loaded);
+      // A same-document load may have fired before the waiter existed; the document is asked.
+      if (!fired && (await evaluate('document.readyState')) !== 'complete') {
+        throw new CdpTimeoutError({ method: `Page.navigate to ${url}`, timeoutMs });
+      }
+      const settled = await evaluate('location.href');
+      current = typeof settled === 'string' && settled !== '' ? settled : url;
+    },
+    waitFor: (selector, options) => ready(selector, options),
+    async click(selector, options) {
+      // Scrolled into view on every poll: `elementFromPoint` answers nothing off-screen, so an
+      // element below the fold would read as covered forever.
+      const target = await ready(selector, options, () =>
+        evaluate(
+          `document.querySelector(${selectorArg(selector)})?.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' })`,
+        ),
+      );
+      const box = target.box ?? { x: 0, y: 0, width: 0, height: 0 };
+      const at = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+      await send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...at });
+      const press = { ...at, button: 'left', clickCount: 1 };
+      await send('Input.dispatchMouseEvent', { type: 'mousePressed', buttons: 1, ...press });
+      await send('Input.dispatchMouseEvent', { type: 'mouseReleased', buttons: 0, ...press });
+    },
+    async type(selector, text, options) {
+      await ready(selector, options);
+      await focusOn(selector);
+      for (const character of text) {
+        for (const frame of characterFrames(character)) await key(frame);
+      }
+    },
+    async focus(selector, options) {
+      await ready(selector, options);
+      await focusOn(selector);
+    },
+    async press(chord) {
+      // Parsed before a key goes down: a refusal halfway would leave a modifier held.
+      const frames = chordFrames(parseKeyChord(chord));
+      for (const frame of frames) await key(frame);
+    },
+    accessibility: (selector, options) =>
+      axNodesFor(
+        send,
+        selector,
+        finiteCount('page.accessibility', 'max', options?.max ?? DEFAULT_ACCESSIBILITY_MAX, 1),
+      ),
+    query,
+    evaluate,
+    screenshot: (options?: ShotCapture) => capture(send, options ?? {}),
+    async colorScheme(scheme: ShotColorScheme) {
+      // An EMPTY list is CDP's reset; an explicit `no-preference` would be an override.
+      const features =
+        scheme === 'no-preference' ? [] : [{ name: 'prefers-color-scheme', value: scheme }];
+      await send('Emulation.setEmulatedMedia', { features });
+    },
+    async prepare(expression) {
+      await send('Page.addScriptToEvaluateOnNewDocument', { source: expression });
+    },
+    console: () => watch.console(),
+    pageErrors: () => watch.pageErrors(),
+    pageErrorsDropped: () => watch.pageErrorsDropped(),
+    network: () => watch.network(),
+    networkDropped: () => watch.networkDropped(),
+  };
+}
+
+type Send = (
+  method: string,
+  params?: Record<string, unknown>,
+) => Promise<Readonly<Record<string, unknown>> | undefined>;
+
+/**
+ * PNG bytes of the viewport, the whole document, or one clip — never both of the last two, which
+ * CDP would resolve silently in favour of one. A clip is CSS pixels in page coordinates.
+ */
+async function capture(send: Send, framing: ShotCapture): Promise<Uint8Array> {
+  const clip = framing.clip;
+  assert(
+    !(framing.fullPage === true && clip !== undefined),
+    'a screenshot was asked for the full page AND a clip, and a capture is one or the other',
+    'pass { clip } for one component or { fullPage: true } for the document, never both',
+  );
+  assert(
+    clip === undefined ||
+      ([clip.x, clip.y, clip.width, clip.height].every(Number.isFinite) &&
+        clip.width > 0 &&
+        clip.height > 0),
+    'a screenshot clip has no area or is not four finite numbers',
+    'pass a clip with a positive width and height: { clip: { x: 0, y: 0, width: 320, height: 200 } }',
+  );
+  let region = clip;
+  if (framing.fullPage === true) {
+    const metrics = record((await send('Page.getLayoutMetrics'))?.['cssContentSize']);
+    const width = metrics?.['width'];
+    const height = metrics?.['height'];
+    if (typeof width === 'number' && typeof height === 'number') {
+      region = { x: 0, y: 0, width: Math.ceil(width), height: Math.ceil(height) };
+    }
+  }
+  const answer = await send('Page.captureScreenshot', {
+    format: 'png',
+    ...(region === undefined ? {} : { clip: { ...region, scale: 1 }, captureBeyondViewport: true }),
+  });
+  const data = answer?.['data'];
+  if (typeof data !== 'string') {
+    throw new CdpCallFailedError({
+      method: 'Page.captureScreenshot',
+      detail: 'the browser answered no image data',
+    });
+  }
+  return Uint8Array.fromBase64(data);
+}

package/src/cdp-shot-watch.ts

@@ -0,0 +1,241 @@
+// What one shot page saw: its console, its uncaught exceptions and its requests, each in a BOUNDED
+// tail with a count of what the bound threw away. And the allow list, enforced in the browser:
+// every request is paused (`Fetch.requestPaused`) and refused unless its host is allowed, so an
+// injected `<img src="http://169.254.169.254/…">` never leaves — it is recorded as `refused`.
+import { hostDecision } from '@ultimat3/core';
+import type { CdpConnection } from '@ultimat3/testing';
+import type {
+  ConsoleLine,
+  NetworkEntry,
+  PageError,
+  ShotClock,
+  ShotResourceType,
+} from './browser-launcher-port';
+
+export const SHOT_RING_CAPACITY = 200;
+
+/** One `PageError` field's cap: one stack overflow's trace is thousands of frames. */
+export const MAX_PAGE_ERROR_CHARS = 4_000;
+
+const clamped = (text: string): string =>
+  text.length <= MAX_PAGE_ERROR_CHARS ? text : `${text.slice(0, MAX_PAGE_ERROR_CHARS - 1)}…`;
+
+/** A bounded, keyed tail: the oldest entry goes first, and every one that goes is counted. */
+class Tail<T> {
+  readonly #items = new Map<string, T>();
+  #dropped = 0;
+  #next = 0;
+
+  put(value: T, key = `#${String(this.#next++)}`): void {
+    this.#items.set(key, value);
+    while (this.#items.size > SHOT_RING_CAPACITY) {
+      const oldest = this.#items.keys().next().value;
+      if (oldest === undefined) break;
+      this.#items.delete(oldest);
+      this.#dropped += 1;
+    }
+  }
+  get(key: string): T | undefined {
+    return this.#items.get(key);
+  }
+  /** Move the entry under `key` to a key of its own at the end, freeing `key` for its successor. */
+  retire(key: string): void {
+    const held = this.#items.get(key);
+    if (held === undefined) return;
+    this.#items.delete(key);
+    this.put(held);
+  }
+  /** Re-set in place: `Map.set` on a present key keeps its position. */
+  update(key: string, value: T): void {
+    if (this.#items.has(key)) this.#items.set(key, value);
+  }
+  entries = (): readonly T[] => [...this.#items.values()];
+  dropped = (): number => this.#dropped;
+}
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
+
+const text = (value: unknown): string | undefined =>
+  typeof value === 'string' ? value : undefined;
+
+const LEVELS: ReadonlyMap<string, ConsoleLine['level']> = new Map([
+  ['warning', 'warn'],
+  ['error', 'error'],
+  ['assert', 'error'],
+  ['debug', 'debug'],
+  ['info', 'info'],
+]);
+
+const RESOURCE_TYPES: ReadonlyMap<string, ShotResourceType> = new Map([
+  ['Document', 'document'],
+  ['Stylesheet', 'stylesheet'],
+  ['Image', 'image'],
+  ['Media', 'media'],
+  ['Font', 'font'],
+  ['Script', 'script'],
+  ['XHR', 'xhr'],
+  ['Fetch', 'fetch'],
+  ['WebSocket', 'websocket'],
+]);
+
+const resourceType = (type: unknown): ShotResourceType =>
+  RESOURCE_TYPES.get(text(type) ?? '') ?? 'other';
+
+/** A console argument as the line a reader is shown: a value, else what the browser described. */
+const argText = (arg: unknown): string => {
+  const remote = record(arg);
+  const value = remote?.['value'];
+  if (typeof value === 'string') return value;
+  if (value !== undefined) return JSON.stringify(value) ?? '';
+  return text(remote?.['unserializableValue']) ?? text(remote?.['description']) ?? '';
+};
+
+/** `Runtime.exceptionThrown`'s details as a `PageError`: message without its `Name: `, stack whole. */
+export const pageErrorOf = (params: Readonly<Record<string, unknown>>, at: number): PageError => {
+  const details = record(params['exceptionDetails']);
+  const exception = record(details?.['exception']);
+  const description = text(exception?.['description']);
+  if (description === undefined) {
+    const thrown = exception?.['value'];
+    const message = thrown === undefined ? (text(details?.['text']) ?? '') : String(thrown);
+    return { message: clamped(message), at };
+  }
+  const first = description.split('\n')[0] ?? '';
+  const name = text(exception?.['className']);
+  const message =
+    name !== undefined && first.startsWith(`${name}: `) ? first.slice(name.length + 2) : first;
+  const stack = description.includes('\n') ? clamped(description) : undefined;
+  return { message: clamped(message), ...(stack === undefined ? {} : { stack }), at };
+};
+
+export interface PageWatch {
+  console(): readonly ConsoleLine[];
+  pageErrors(): readonly PageError[];
+  pageErrorsDropped(): number;
+  network(): readonly NetworkEntry[];
+  networkDropped(): number;
+  /** Stop listening. Idempotent. */
+  stop(): void;
+}
+
+/**
+ * Subscribe BEFORE the domains are enabled (the caller's order), so the first request of the first
+ * navigation is already counted. Only events on `sessionId` are read: a remote browser carries
+ * other people's pages.
+ */
+export function watchPage(input: {
+  readonly connection: CdpConnection;
+  readonly sessionId: string;
+  readonly clock: ShotClock;
+  readonly allowHosts: readonly string[];
+}): PageWatch {
+  const { connection, sessionId } = input;
+  const lines = new Tail<ConsoleLine>();
+  const errors = new Tail<PageError>();
+  const requests = new Tail<NetworkEntry>();
+  const now = (): number => input.clock.now().getTime();
+  const mine =
+    (listener: (params: Readonly<Record<string, unknown>>) => void) =>
+    (params: Record<string, unknown>, on: string | undefined): void => {
+      if (on === sessionId) listener(params);
+    };
+
+  const offs = [
+    connection.on(
+      'Runtime.consoleAPICalled',
+      mine((params) => {
+        const args = params['args'];
+        lines.put({
+          level: LEVELS.get(text(params['type']) ?? '') ?? 'log',
+          text: (Array.isArray(args) ? args : []).map(argText).join(' '),
+          at: now(),
+        });
+      }),
+    ),
+    connection.on(
+      'Runtime.exceptionThrown',
+      mine((params) => errors.put(pageErrorOf(params, now()))),
+    ),
+    connection.on(
+      'Network.requestWillBeSent',
+      mine((params) => {
+        const id = text(params['requestId']) ?? '';
+        const request = record(params['request']);
+        const held = requests.get(id);
+        const entry: NetworkEntry = {
+          method: text(request?.['method']) ?? 'GET',
+          url: text(request?.['url']) ?? '',
+          resourceType: resourceType(params['type']),
+          at: now(),
+          ...(held?.refused === undefined ? {} : { refused: held.refused }),
+        };
+        // A redirect re-sends under the SAME id: the hop before it is a request of its own,
+        // answered with the redirect's status.
+        const hop = record(params['redirectResponse'])?.['status'];
+        if (held !== undefined && held.refused === undefined && typeof hop === 'number') {
+          requests.update(id, { ...held, status: hop });
+          requests.retire(id);
+          requests.put(entry, id);
+        } else if (held === undefined) requests.put(entry, id);
+        else requests.update(id, entry);
+      }),
+    ),
+    connection.on(
+      'Network.responseReceived',
+      mine((params) => {
+        const id = text(params['requestId']) ?? '';
+        const status = record(params['response'])?.['status'];
+        const held = requests.get(id);
+        if (held !== undefined && typeof status === 'number')
+          requests.update(id, { ...held, status });
+      }),
+    ),
+    connection.on(
+      'Fetch.requestPaused',
+      mine((params) => {
+        const pausedId = text(params['requestId']) ?? '';
+        const request = record(params['request']);
+        const url = text(request?.['url']) ?? '';
+        if (hostDecision(url, input.allowHosts).allowed) {
+          void connection
+            .send('Fetch.continueRequest', { requestId: pausedId }, sessionId)
+            .catch(() => undefined);
+          return;
+        }
+        const id = text(params['networkId']) ?? pausedId;
+        const held = requests.get(id);
+        const refused: NetworkEntry = {
+          method: text(request?.['method']) ?? held?.method ?? 'GET',
+          url,
+          resourceType: resourceType(params['resourceType']),
+          at: held?.at ?? now(),
+          refused: 'host',
+        };
+        if (held === undefined) requests.put(refused, id);
+        else requests.update(id, refused);
+        void connection
+          .send(
+            'Fetch.failRequest',
+            { requestId: pausedId, errorReason: 'BlockedByClient' },
+            sessionId,
+          )
+          .catch(() => undefined);
+      }),
+    ),
+  ];
+
+  let stopped = false;
+  return {
+    console: () => lines.entries(),
+    pageErrors: () => errors.entries(),
+    pageErrorsDropped: () => errors.dropped(),
+    network: () => requests.entries(),
+    networkDropped: () => requests.dropped(),
+    stop(): void {
+      if (stopped) return;
+      stopped = true;
+      for (const off of offs) off();
+    },
+  };
+}

package/src/cmd-affected-spec.ts

@@ -0,0 +1,24 @@
+// `x affected`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-affected.ts`, which `registry.ts` imports only when the command runs.
+
+import { DEFAULT_BASE } from './affected';
+import type { CommandSpec } from './parse';
+
+export const affectedSpec: CommandSpec = {
+  name: 'affected',
+  summary: 'the workspaces a diff touches, and every workspace that depends on one of them',
+  usage: 'x affected [--base <ref>] [--dirty] [--paths] [--json]',
+  flags: [
+    {
+      name: 'base',
+      type: 'string',
+      summary: `git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
+    },
+    {
+      name: 'dirty',
+      type: 'boolean',
+      summary: 'also count uncommitted work — every agent sharing this checkout, not only yours',
+    },
+    { name: 'paths', type: 'boolean', summary: 'print bare directories instead of a table' },
+  ],
+};

package/src/cmd-affected.ts

@@ -6,7 +6,8 @@
 // CLI wiring only. What a diff touches is `affected.ts`, what the workspaces are is
 // `workspace-graph.ts` — the `cmd-jobs.ts` / `jobs-report.ts` split, repeated.
 
-import { affectedScope, DEFAULT_BASE } from './affected';
+import { affectedScope } from './affected';
+import { affectedSpec } from './cmd-affected-spec';
 import type { CliCommand, CommandContext } from './command';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
@@ -33,24 +34,7 @@ export const AFFECTED_MESSAGE_KEYS = [
 ] as const;
 
 export const affectedCommand: CliCommand = {
-  spec: {
-    name: 'affected',
-    summary: 'the workspaces a diff touches, and every workspace that depends on one of them',
-    usage: 'x affected [--base <ref>] [--dirty] [--paths] [--json]',
-    flags: [
-      {
-        name: 'base',
-        type: 'string',
-        summary: `git ref to diff against, merge-base style (default: ${DEFAULT_BASE})`,
-      },
-      {
-        name: 'dirty',
-        type: 'boolean',
-        summary: 'also count uncommitted work — every agent sharing this checkout, not only yours',
-      },
-      { name: 'paths', type: 'boolean', summary: 'print bare directories instead of a table' },
-    ],
-  },
+  spec: affectedSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     // The one resolver `x test --affected` narrows with, so this command reports exactly what that
     // one runs. It reads `--base` before git is spawned (a malformed ref must not cost a