@ultimat3/cli 20.2.1 → 22.0.0

package/src/budgets.ts

@@ -48,8 +48,21 @@ export interface RouteStats {
 
 export interface BuildStats {
   readonly routes: readonly RouteStats[];
+  /** The measurement rules that wrote the file — `BUILD_STATS_RULES` at the time. */
+  readonly measuredBy?: number;
+  /** Set by `readBuildStats` on a file an earlier rule wrote: there are no numbers to read. */
+  readonly stale?: true;
 }
 
+/**
+ * The version of the rules `measureDocumentJs` measures by. BUMP IT whenever what is charged
+ * changes — a script exempted, a kind of tag excluded — so every stats file written under the old
+ * rule stops being read as a measurement. `.x/` survives across framework upgrades, and
+ * `examples/dummy` was charged 250 B for `/x-sw-register.js` by a file written before
+ * `FRAMEWORK_SCRIPTS` exempted it. `2`: that exemption and the page-boot decision (ledger #28).
+ */
+export const BUILD_STATS_RULES = 2;
+
 const chainOf = (stats: RouteStats): string =>
   stats.heaviestChain === undefined ? 'unknown import chain' : stats.heaviestChain.join(' -> ');
 
@@ -78,7 +91,16 @@ function declaredBudgets(js: number | null, lcp: number | undefined): string {
  * second build's. Reporting the first as the second is what sends a reader to re-run a build that
  * already did everything it was going to do.
  */
-function unmeasuredFinding(url: string, declared: string, built: boolean): Finding {
+function unmeasuredFinding(url: string, declared: string, built: boolean, stale = false): Finding {
+  if (stale) {
+    return {
+      code: 'X_BUDGET_UNMEASURED',
+      cause: `${url} declares a ${declared} budget and ${BUILD_STATS_FILE} was written by an earlier measurement rule than this gate's (v${String(BUILD_STATS_RULES)}), so its numbers are not this gate's to read`,
+      fix: 'x build --target static --json && x verify --json',
+      docs: ERROR_DOCS_URL,
+      at: url,
+    };
+  }
   return {
     code: 'X_BUDGET_UNMEASURED',
     cause: built
@@ -109,7 +131,11 @@ function unmeasuredFinding(url: string, declared: string, built: boolean): Findi
  * reporting them under their own codes would tell the author to fix a database the gate never
  * had. The list grows by a decision, per code, here.
  */
-const REPORTED_BY_OWN_CODE: ReadonlySet<string> = new Set(['X_ISLAND_PROPS_INVALID']);
+const REPORTED_BY_OWN_CODE: ReadonlySet<string> = new Set([
+  'X_ISLAND_PROPS_INVALID',
+  // A dynamic route that lists no `prerender()` path: the edit is in the route, not the build.
+  'X_BUDGET_PARAMS_UNDECLARED',
+]);
 
 /**
  * The build's own finding for a route it could not weigh, when that failure is an instruction.
@@ -144,8 +170,14 @@ export function checkBudgets(
   unmeasured: readonly UnmeasuredRoute[] = [],
 ): readonly Finding[] {
   const byPath = new Map((stats?.routes ?? []).map((route) => [route.path, route]));
+  // Routes no build can weigh by construction (`UnmeasuredRoute.weighable`): printed by the step,
+  // never a finding — an instruction with no edit behind it is noise.
+  const unweighable = new Set(
+    unmeasured.filter((one) => one.weighable === false).map((one) => one.path),
+  );
   const findings: Finding[] = [];
   for (const route of manifest.routes) {
+    if (unweighable.has(route.url)) continue;
     const measured = byPath.get(route.url);
     const js = jsBudgetOf(route);
     const lcp = route.budget?.lcp;
@@ -153,7 +185,12 @@ export function checkBudgets(
       if (js !== null || lcp !== undefined) {
         findings.push(
           ownCodeFinding(route.url, unmeasured) ??
-            unmeasuredFinding(route.url, declaredBudgets(js, lcp), stats !== undefined),
+            unmeasuredFinding(
+              route.url,
+              declaredBudgets(js, lcp),
+              stats !== undefined,
+              stats?.stale === true,
+            ),
         );
       }
       continue;
@@ -183,7 +220,9 @@ export function checkBudgets(
 export async function readBuildStats(root: string): Promise<BuildStats | undefined> {
   const path = join(root, BUILD_STATS_FILE);
   if (!existsSync(path)) return undefined;
-  return (await Bun.file(path).json()) as BuildStats;
+  const read = (await Bun.file(path).json()) as BuildStats;
+  // A file the current rules did not write carries no numbers this gate may read.
+  return read.measuredBy === BUILD_STATS_RULES ? read : { routes: [], stale: true };
 }
 
 const SCRIPT_TAG = /<script(?<attrs>[^>]*)>(?<body>[\s\S]*?)<\/script>/g;
@@ -242,14 +281,17 @@ export interface MeasuredJs {
  * and the next build measured the one before it and recorded 250. Same commit, green then red,
  * decided by whether anything had cleaned the output directory.
  *
- * ENUMERATED, and it is one entry: `serviceWorkerHead` is the only `<script src>` the framework
- * puts in a prerendered document — measured on a fresh scaffold plus `x g island` and
- * `x g route`, where `<script src="/x-sw-register.js" defer>` is the only script tag across every
- * emitted page. Two framework scripts are deliberately NOT here. `render/src/hydrate.ts`'s inline
- * module runtime is charged, because it exists only when the page ships an island — it is the
- * cost of the app's own interactivity, and a page with a `0kb` budget has none. `island-props.ts`'
- * `<script type="application/json">` is already excluded as data, by `carriesJson`. A third one
- * joins this set by a decision, here, with the same argument.
+ * ENUMERATED, and it is one entry — the service-worker register is the only framework
+ * `<script src>` EXEMPTED, not the only one emitted. Three framework scripts are deliberately
+ * CHARGED. The page boot (plan 101: the page client, the principal fence, the sync target) is
+ * framework-emitted too, and charged by decision (DX ledger #28, 2026-09-22): it ships only on a
+ * page that hydrates something, so it is part of the interactivity the app opted into, and
+ * `examples/dummy`'s route budgets already include it. `render/src/hydrate.ts`'s inline module
+ * runtime is charged for the same reason — it exists only when the page ships an island, and a
+ * page with a `0kb` budget has none. `island-props.ts`' `<script type="application/json">` is
+ * excluded as data, by `carriesJson`, not by this set. A further entry joins this set by a
+ * decision, here, with the register's argument: every document carries it and no author can
+ * remove it.
  */
 export const FRAMEWORK_SCRIPTS: ReadonlySet<string> = new Set([SW_REGISTER_PATH]);
 
@@ -335,6 +377,7 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
  */
 export async function writeBuildStats(root: string, stats: BuildStats): Promise<string> {
   const path = join(root, BUILD_STATS_FILE);
-  await Bun.write(path, `${JSON.stringify(stats, null, 2)}\n`);
+  const stamped: BuildStats = { ...stats, measuredBy: BUILD_STATS_RULES };
+  await Bun.write(path, `${JSON.stringify(stamped, null, 2)}\n`);
   return path;
 }

package/src/build-errors.ts

@@ -0,0 +1,54 @@
+// The CLI's build and bundle refusals: an entry an app does not have, an island that will not
+// compile, a framework browser script that will not bundle. Split from `errors.ts` at its 500-line
+// ceiling; `errors.ts` re-exports every name, so no import site moves.
+
+import { UltimateError } from '@ultimat3/core';
+import { quoteArg } from './shell-quote';
+
+/**
+ * A build target names an entry file the app does not have. `x build` refuses before it spawns the
+ * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
+ * supposed to own, and `docker build`'s says nothing about which target wanted it.
+ */
+export class BuildEntryMissingError extends UltimateError {
+  constructor(input: { target: string; entry: string }) {
+    super({
+      code: 'X_BUILD_ENTRY_MISSING',
+      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
+      fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
+    });
+  }
+}
+
+/**
+ * A client entry would not compile. `X_BUILD_FAILED`, not a code of its own: an island is a bundle
+ * entry point like any other, and the target's own logs are what says which line. The fix builds
+ * exactly that one file, so the next message an author reads is the compiler's and not the CLI's.
+ */
+export class IslandBuildFailedError extends UltimateError {
+  constructor(input: { file: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
+      fix: `bun build --target browser ${input.file}`,
+    });
+  }
+}
+
+/** Which framework script a page ships: the one sync worker, or the one page boot. */
+export type FrameworkScriptKind = 'sync worker' | 'page boot';
+
+/**
+ * One of the page's framework scripts would not bundle. Same code as an island: "a browser entry
+ * the framework builds did not build" is one condition, and the entry here is framework code, not
+ * the app's — the cause names WHICH script, so the reader knows what the page is now missing.
+ */
+export class FrameworkScriptBuildFailedError extends UltimateError {
+  constructor(input: { what: FrameworkScriptKind; entry: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `the ${input.what} (${input.entry}) would not bundle for the browser: ${input.logs}`,
+      fix: `bun build --target browser --format iife ${quoteArg(input.entry)}`,
+    });
+  }
+}

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