@ultimat3/cli 20.1.6 → 20.2.1

package/src/mcp-ui-diff.ts

@@ -0,0 +1,141 @@
+// `ui.diff` — the one `ui.*` tool with no browser in it. Two PNGs the others wrote, decoded through
+// `@ultimat3/core`'s raw-pixel seam, compared by `ui-diff.ts`, and written back as a third PNG
+// beside the second. No dependency: the seam already reads and writes 8-bit RGBA, and a capture
+// that arrives in another PNG shape (Chrome writes RGB when a page has no transparency) is
+// normalised through `transformImageBytes`, whose encoder emits the one shape the seam reads.
+//
+// The path gate is what makes `dev:read` defensible for a tool that opens files: `before`, `after`
+// and `out` are relative to the app root and must resolve — lexically AND through any symlink —
+// inside `.x/shot/`, the directory only `x shot` and the `ui.*` tools write. A token that may read
+// the route table may read the pictures of those routes; it may not read `.env` through a tool
+// that says "diff".
+
+// why: Bun has no realpath of its own, and a symlink under .x/shot/ pointing out of it is the
+// one path the lexical check cannot see.
+import { realpath } from 'node:fs/promises';
+// why: Bun exposes no path primitives; the gate is a resolve-then-prefix check on joined paths.
+import { dirname, resolve, sep } from 'node:path';
+import type { Raster } from '@ultimat3/core';
+import {
+  decodeImage,
+  encodeImage,
+  ImageUnsupportedError,
+  transformImageBytes,
+  UltimateError,
+} from '@ultimat3/core';
+import type { UiDiffInput, UiDiffResult } from '@ultimat3/mcp';
+import { SHOT_DIR } from './shot-server';
+import { changedPercent, diffPixels } from './ui-diff';
+
+export interface DiffDeps {
+  readonly root: string;
+}
+
+const SHOT_FIX =
+  'x shot / --json   # then pass the image path it answers, relative to the app root: ui.diff reads .x/shot/ and nothing else';
+
+/** `true` when `path` is `dir` or lies under it — a prefix check on whole segments, never on chars. */
+const under = (path: string, dir: string): boolean => path === dir || path.startsWith(dir + sep);
+
+/**
+ * The lexical half of the gate: `root/<relative>` resolved, then held under `root/.x/shot`. An
+ * absolute `relative` resolves to itself, and `..` segments resolve away, so both leave through
+ * the same refusal.
+ */
+export function shotPath(root: string, relative: string, field: string): string {
+  const shotDir = resolve(root, SHOT_DIR);
+  const path = resolve(root, relative);
+  if (!under(path, shotDir)) {
+    throw new UltimateError({
+      code: 'X_UI_DIFF_PATH_OUTSIDE',
+      cause: `${field} resolves to ${path}, which is not inside ${shotDir}`,
+      fix: SHOT_FIX,
+      meta: { field, path, shotDir },
+    });
+  }
+  return path;
+}
+
+/** The symlink half: the file's real location is held under the shot directory's real location. */
+async function readCapture(root: string, relative: string, field: string): Promise<Uint8Array> {
+  const path = shotPath(root, relative, field);
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    throw new UltimateError({
+      code: 'X_UI_DIFF_FILE_MISSING',
+      cause: `${field} names ${path}, and there is no file there`,
+      fix: 'x shot / --json   # then diff the image path it answers; a capture ui.shot wrote is listed in its own answer',
+      meta: { field, path },
+    });
+  }
+  const real = await realpath(path);
+  const shotDir = await realpath(resolve(root, SHOT_DIR));
+  if (!under(real, shotDir)) {
+    throw new UltimateError({
+      code: 'X_UI_DIFF_PATH_OUTSIDE',
+      cause: `${field} is a link to ${real}, which is not inside ${shotDir}`,
+      fix: SHOT_FIX,
+      meta: { field, path, real, shotDir },
+    });
+  }
+  return file.bytes();
+}
+
+/**
+ * The seam reads 8-bit RGBA and nothing else. A PNG in any other shape — Chrome's RGB when the page
+ * is opaque, a palette from an optimiser — goes once through Bun's codecs, which always write the
+ * shape the seam reads. Only `imageUnsupported` is retried that way: a truncated file is a
+ * truncated file in either decoder.
+ */
+export async function decodeCapture(bytes: Uint8Array): Promise<Raster> {
+  try {
+    return decodeImage(bytes);
+  } catch (error) {
+    if (!(error instanceof ImageUnsupportedError)) throw error;
+    return decodeImage(await transformImageBytes(bytes, { format: 'png' }));
+  }
+}
+
+/** Eight hex digits of the path's 64-bit hash: enough to keep two diffs of one `after` apart. */
+export const hash8 = (text: string): string =>
+  Bun.hash(text).toString(16).padStart(16, '0').slice(0, 8);
+
+export async function diffShots(deps: DiffDeps, input: UiDiffInput): Promise<UiDiffResult> {
+  const { root } = deps;
+  // The output path is gated BEFORE any decoding: a refusal should cost nothing, and `out` is the
+  // one path this tool writes, so it is the one that most needs holding under `.x/shot/`.
+  const afterPath = shotPath(root, input.after, 'after');
+  const diff =
+    input.out === undefined
+      ? resolve(dirname(afterPath), `diff-${hash8(input.before)}.png`)
+      : shotPath(root, input.out, 'out');
+  const [before, after] = await Promise.all([
+    readCapture(root, input.before, 'before').then(decodeCapture),
+    readCapture(root, input.after, 'after').then(decodeCapture),
+  ]);
+  if (before.width !== after.width || before.height !== after.height) {
+    throw new UltimateError({
+      code: 'X_UI_DIFF_SIZE_MISMATCH',
+      cause: `before is ${before.width}x${before.height} and after is ${after.width}x${after.height}; a diff needs one size`,
+      fix: 'x shot / --json   # photograph both captures at one viewport with one fullPage setting, then diff those two',
+      meta: {
+        before: { width: before.width, height: before.height },
+        after: { width: after.width, height: after.height },
+      },
+    });
+  }
+  const { width, height } = after;
+  const result = diffPixels(before.pixels, after.pixels, width, height, input.threshold);
+  await Bun.write(diff, encodeImage({ width, height, pixels: result.diffRgba }));
+  return {
+    ok: true,
+    before: input.before,
+    after: input.after,
+    width,
+    height,
+    changedPixels: result.changedPixels,
+    changedPercent: changedPercent(result.changedPixels, width, height),
+    changedBox: result.changedBox,
+    diff,
+  };
+}

package/src/mcp-ui-inspect.ts

@@ -0,0 +1,183 @@
+// `ui.inspect` — the dev MCP server's third eye, and the one that reads instead of looking. A
+// browser is the cost of every `ui.*` call, so this one reads MANY facts per navigation: for each
+// selector the tag, text, box, visibility, attributes, named computed styles and (on request) the
+// browser-computed role and name; for the document its title, `data-theme`, the focused element,
+// the island count and both error streams. It is `runShot` with an `act` hook — the same boot,
+// the same driver, the same verdict, the same PNG under an `inspect/` subdirectory — so `ok` here
+// means exactly what `ui.shot`'s `ok` means, and a page that threw while an agent was reading
+// its styles is a finding beside the styles.
+
+// why: Bun exposes no path-join primitive, and the directory is a path an agent opens.
+import { join } from 'node:path';
+import type { UiInspectInput, UiInspectResult, UiInspectSelector } from '@ultimat3/mcp';
+import { UI_INSPECT_LIMITS } from '@ultimat3/mcp';
+import type { AxNode, ScrapeDriver, ScrapePage } from '@ultimat3/scraping';
+import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
+import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
+import type { ShotServer } from './shot-server';
+import type { ShotVerdict } from './shot-verdict';
+import type { InspectProbe } from './ui-inspect-probe';
+import { inspectExpression, parseInspectProbe } from './ui-inspect-probe';
+
+export interface InspectDeps {
+  readonly root: string;
+  /** The memoised scratch server (or the running `x dev`), as `uiCapabilities` hands it out. */
+  readonly boot: () => Promise<ShotServer>;
+  readonly driver: (viewport: UiInspectInput['viewport']) => Promise<ScrapeDriver>;
+}
+
+/** What the page answered before the parser had a say — `null` selectors when it answered nothing. */
+export interface Seen {
+  probe: InspectProbe | null;
+  /** Per selector, in the input's order: the a11y nodes, or `null` when not asked. */
+  a11y: readonly (readonly AxNode[] | null)[];
+}
+
+/** The four fields the read is built from — `ui.inspect`'s input, or `ui.interact`'s block. */
+export type InspectSpecInput = Pick<
+  UiInspectInput,
+  'selectors' | 'styles' | 'a11y' | 'activeElement'
+>;
+
+/**
+ * The read itself, on a page somebody else navigated: the one probe expression, then (on request)
+ * one accessibility round trip per selector. `.catch(() => null)` for the island probe's reason:
+ * a page that refuses evaluation is a page with no facts, and the verdict — not a throw here — is
+ * what says why. Shared by `ui.inspect` and `ui.interact`, so both read the same facts.
+ */
+export async function readInspect(page: ScrapePage, spec: InspectSpecInput): Promise<Seen> {
+  const expression = inspectExpression({
+    selectors: spec.selectors,
+    styles: spec.styles,
+    activeElement: spec.activeElement,
+  });
+  const probe = await page
+    .evaluate(expression)
+    .then(parseInspectProbe)
+    .catch(() => null);
+  if (!spec.a11y) return { probe, a11y: [] };
+  const nodes: (readonly AxNode[] | null)[] = [];
+  for (const selector of spec.selectors) {
+    nodes.push(await page.accessibility(selector, { max: UI_INSPECT_LIMITS.matches }));
+  }
+  return { probe, a11y: nodes };
+}
+
+/**
+ * The empty answer for a selector the page never described: the probe refused to run, or answered
+ * a shape the parser did not accept. `valid: false` is the honest reading — nothing about this
+ * selector was established — and the verdict beside it says whether the page was broken.
+ */
+const unanswered = (selector: string): UiInspectSelector => ({
+  selector,
+  valid: false,
+  count: 0,
+  truncated: false,
+  matches: [],
+});
+
+export function selectorsOf(input: InspectSpecInput, seen: Seen): readonly UiInspectSelector[] {
+  return input.selectors.map((selector, index): UiInspectSelector => {
+    const found = seen.probe?.selectors[index];
+    if (found === undefined) return unanswered(selector);
+    const nodes = seen.a11y[index] ?? null;
+    return {
+      selector,
+      valid: found.valid,
+      count: found.count,
+      truncated: found.truncated,
+      // Merged BY INDEX: both reads walk `querySelectorAll` in document order over the same DOM,
+      // one navigation apart from nothing. A node the a11y read did not cover keeps no `a11y` key.
+      matches: found.matches.map((match, at) => {
+        const node = nodes?.[at];
+        return node === undefined
+          ? match
+          : { ...match, a11y: { role: node.role, name: node.name } };
+      }),
+    };
+  });
+}
+
+const encoded = (value: unknown): number => new TextEncoder().encode(JSON.stringify(value)).length;
+
+/**
+ * The wire cap. Matches are dropped from the LAST selectors first — an agent lists what it cares
+ * about most first, and a cap that emptied the first selector would take the fact the call was
+ * for. The selector keeps its `count` and gains `truncated: true`, so the drop is visible.
+ */
+export function capInspect(result: UiInspectResult): UiInspectResult {
+  if (encoded(result) <= UI_INSPECT_LIMITS.bytes) return result;
+  const selectors = [...result.selectors];
+  let truncated = result.truncated;
+  for (let index = selectors.length - 1; index >= 0; index -= 1) {
+    const entry = selectors[index];
+    if (entry === undefined || entry.matches.length === 0) continue;
+    selectors[index] = { ...entry, truncated: true, matches: [] };
+    truncated = true;
+    if (encoded({ ...result, selectors, truncated }) <= UI_INSPECT_LIMITS.bytes) break;
+  }
+  return { ...result, selectors, truncated };
+}
+
+const errorsOf = (verdict: ShotVerdict): readonly string[] =>
+  verdict.console.filter((line) => line.level === 'error').map((line) => line.text);
+
+export async function inspectRoute(
+  deps: InspectDeps,
+  input: UiInspectInput,
+): Promise<UiInspectResult> {
+  // A holder rather than a `let`: an assignment inside the `act` closure does not reach the
+  // narrowing below, and a `let` typed `null` after the await is what the compiler would see.
+  const seen: Seen = { probe: null, a11y: [] };
+  const driver = await deps.driver(input.viewport);
+  // Its own subdirectory under the (route, viewport, scheme) one, so an inspect and a shot of the
+  // same route at the same size never overwrite each other's verdict.
+  const outDir = join(
+    deps.root,
+    SHOT_DIR,
+    shotSlug(input.route),
+    `${input.viewport.width}x${input.viewport.height}-${input.colorScheme}`,
+    'inspect',
+  );
+  const artifacts = await runShot({
+    route: input.route,
+    outDir,
+    driver,
+    boot: deps.boot,
+    settleMs: DEFAULT_SETTLE_MS,
+    timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
+    fullPage: true,
+    colorScheme: input.colorScheme,
+    act: async (page) => {
+      const read = await readInspect(page, input);
+      seen.probe = read.probe;
+      seen.a11y = read.a11y;
+    },
+  });
+  const verdict = artifacts.verdict;
+  return capInspect({
+    ok: verdict.ok,
+    route: input.route,
+    finalUrl: verdict.finalUrl,
+    title: seen.probe?.title ?? '',
+    theme: seen.probe?.theme ?? null,
+    activeElement: seen.probe?.activeElement ?? null,
+    islands:
+      verdict.islands === null
+        ? null
+        : {
+            declared: verdict.islands.declared,
+            booted: verdict.islands.booted,
+            mounted: verdict.islands.mounted,
+            failed: verdict.islands.failed,
+          },
+    consoleErrors: errorsOf(verdict),
+    pageErrors: verdict.pageErrors.map((error) => error.message),
+    refused: verdict.refused,
+    selectors: selectorsOf(input, seen),
+    image: artifacts.image,
+    verdictFile: artifacts.verdictFile,
+    truncated: false,
+    droppedStyles: [],
+  });
+}

package/src/mcp-ui-interact.ts

@@ -0,0 +1,304 @@
+// `ui.interact` — the dev MCP server's hand. The three `ui.*` eyes photograph a route as it loads;
+// this one drives it first — opens the ⌘K palette, raises a dialog, types into a field — and
+// then takes the same picture, the same verdict and (on request) `ui.inspect`'s facts, in ONE
+// navigation. It is `runShot` with an `act` hook whose body is the step list: after EVERY step the
+// island poll re-runs (a click that mounts something changes the count the verdict reports) and
+// one poll interval passes for the CSS transition the click started.
+//
+// Four refusals, and every one refuses WHOLE rather than trims, skips or follows: a dropped step,
+// a swallowed keystroke or a navigation quietly followed changes what the picture is of, and an
+// agent judging that picture would judge the wrong thing.
+
+// why: Bun exposes no path-join primitive, and the directory is a path an agent opens.
+import { join } from 'node:path';
+import { isUltimateError, toUltimateError, UltimateError } from '@ultimat3/core';
+import type { UiInteractInput, UiInteractResult, UiInteractStepResult } from '@ultimat3/mcp';
+import { UI_INTERACT_LIMITS } from '@ultimat3/mcp';
+import type { ScrapePage } from '@ultimat3/scraping';
+import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
+import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
+import type { InspectDeps, Seen } from './mcp-ui-inspect';
+import { readInspect, selectorsOf } from './mcp-ui-inspect';
+import { SETTLE_POLL_MS } from './shot-settle';
+import type { IslandCount } from './shot-verdict';
+import { verdictJson } from './shot-verdict';
+
+export interface InteractDeps extends InspectDeps {
+  /** Injected by the test, so the per-step transition frame is proved without spending it. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+
+/** A step after parsing: one verb, its argument, and the bounds already held. */
+export type InteractStep =
+  | { readonly kind: 'click'; readonly selector: string }
+  | { readonly kind: 'type'; readonly selector: string; readonly text: string }
+  | { readonly kind: 'press'; readonly chord: string }
+  | { readonly kind: 'focus'; readonly selector: string }
+  | { readonly kind: 'wait'; readonly ms: number }
+  | { readonly kind: 'wait'; readonly selector: string };
+
+/**
+ * The four fix lines, verbatim from `mcp-errors.ts`'s `CLI_FIXES` — an error's fix travels IN the
+ * error, and `errors.explain` answers the same text.
+ */
+const FIX = {
+  invalid:
+    'x help shot --json   # then resend ui.interact with at most 12 one-key steps, type.text under 500 chars and wait under 5000 ms',
+  secret:
+    'x shot --all-islands --json   # or --island <name>: a declared state renders the filled form without the secret ever being typed',
+  left: 'x routes --json   # then resend ui.interact with steps that stay on one of its paths',
+  failed:
+    'x routes --json   # then run ui.inspect on the route first and copy a selector it reports with count >= 1',
+} as const;
+
+const invalid = (cause: string): UltimateError =>
+  new UltimateError({ code: 'X_UI_INTERACT_STEPS_INVALID', cause, fix: FIX.invalid });
+
+const nonEmpty = (value: unknown, at: string): string => {
+  if (typeof value !== 'string' || value === '') throw invalid(`${at} must be a non-empty string`);
+  return value;
+};
+
+function parseStep(raw: Readonly<Record<string, unknown>>, index: number): InteractStep {
+  const keys = Object.keys(raw);
+  const key = keys[0];
+  if (keys.length !== 1 || key === undefined) {
+    throw invalid(
+      `step ${index} names ${keys.length} verbs (${keys.join(', ')}); a step is ONE of click, type, press, focus, wait`,
+    );
+  }
+  const at = `step ${index} (${key})`;
+  // `Object.hasOwn` narrowed the key set above; the read below is on a literal the parser owns.
+  const value: unknown = Object.hasOwn(raw, key) ? raw[key] : undefined;
+  switch (key) {
+    case 'click':
+      return { kind: 'click', selector: nonEmpty(value, at) };
+    case 'focus':
+      return { kind: 'focus', selector: nonEmpty(value, at) };
+    case 'press':
+      return { kind: 'press', chord: nonEmpty(value, at) };
+    case 'type': {
+      if (typeof value !== 'object' || value === null)
+        throw invalid(`${at} needs { selector, text }`);
+      const field = value as { readonly selector?: unknown; readonly text?: unknown };
+      const text = nonEmpty(field.text, `${at}.text`);
+      if (text.length > UI_INTERACT_LIMITS.textChars) {
+        throw invalid(
+          `${at}.text is ${text.length} chars; the cap is ${UI_INTERACT_LIMITS.textChars}`,
+        );
+      }
+      return { kind: 'type', selector: nonEmpty(field.selector, `${at}.selector`), text };
+    }
+    case 'wait': {
+      if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value < 0 || value > UI_INTERACT_LIMITS.waitMs) {
+          throw invalid(`${at} is ${value} ms; the cap is ${UI_INTERACT_LIMITS.waitMs}`);
+        }
+        return { kind: 'wait', ms: value };
+      }
+      return { kind: 'wait', selector: nonEmpty(value, at) };
+    }
+    default:
+      throw invalid(`${at} is not a verb; a step is ONE of click, type, press, focus, wait`);
+  }
+}
+
+/** The whole list or nothing: a trimmed list photographs a different scene than the one asked for. */
+export function parseSteps(raw: UiInteractInput['steps']): readonly InteractStep[] {
+  if (raw.length > UI_INTERACT_LIMITS.steps) {
+    throw invalid(`${raw.length} steps; the cap is ${UI_INTERACT_LIMITS.steps}`);
+  }
+  return raw.map(parseStep);
+}
+
+/** Eight hex chars of `Bun.hash` over the raw list — deterministic per step list, never per run. */
+export const stepsHash = (raw: UiInteractInput['steps']): string =>
+  Bun.hash(JSON.stringify(raw)).toString(16).padStart(16, '0').slice(0, 8);
+
+const describe = (step: InteractStep): string => {
+  switch (step.kind) {
+    case 'click':
+    case 'focus':
+      return `${step.kind} ${JSON.stringify(step.selector)}`;
+    case 'press':
+      return `press ${JSON.stringify(step.chord)}`;
+    case 'type':
+      return `type into ${JSON.stringify(step.selector)}`;
+    case 'wait':
+      return 'ms' in step ? `wait ${step.ms}ms` : `wait for ${JSON.stringify(step.selector)}`;
+  }
+};
+
+async function perform(
+  page: ScrapePage,
+  step: InteractStep,
+  sleep: (ms: number) => Promise<void>,
+): Promise<void> {
+  switch (step.kind) {
+    case 'click':
+      return page.click(step.selector);
+    case 'focus':
+      return page.focus(step.selector);
+    case 'press':
+      return page.press(step.chord);
+    case 'type':
+      return page.type(step.selector, step.text);
+    case 'wait':
+      if ('ms' in step) return sleep(step.ms);
+      await page.waitFor(step.selector, { state: 'visible', timeout: DEFAULT_PAGE_TIMEOUT_MS });
+  }
+}
+
+/**
+ * Before any keystroke: a password field's value would land in the PNG, the verdict's console and
+ * an agent's transcript. The read is the driver's own `query`, so the fake answers it offline.
+ */
+async function refuseSecretField(
+  page: ScrapePage,
+  step: InteractStep,
+  index: number,
+): Promise<void> {
+  if (step.kind !== 'type') return;
+  const [first] = await page.query(step.selector);
+  if (first?.attrs['type'] !== 'password') return;
+  throw new UltimateError({
+    code: 'X_UI_INTERACT_SECRET_FIELD',
+    cause: `step ${index} would type into ${JSON.stringify(step.selector)}, an <input type="password">`,
+    fix: FIX.secret,
+    meta: { step: index, selector: step.selector },
+  });
+}
+
+export interface StepsRun {
+  readonly steps: readonly UiInteractStepResult[];
+  /** Some step changed the page's URL — the navigation `ok` must not read as a redirect. */
+  readonly navigated: boolean;
+}
+
+/**
+ * The steps in order, each followed by a settle and one poll interval, each checked against the
+ * origin. A scraping error is wrapped, never passed through: the agent needs to know WHICH step,
+ * and the fix is a selector `ui.inspect` reports rather than whatever the driver's fix names.
+ */
+export async function runSteps(
+  page: ScrapePage,
+  steps: readonly InteractStep[],
+  settle: () => Promise<IslandCount | null>,
+  origin: string,
+  sleep: (ms: number) => Promise<void>,
+): Promise<StepsRun> {
+  const results: UiInteractStepResult[] = [];
+  let navigated = false;
+  for (const [index, step] of steps.entries()) {
+    const before = page.url();
+    const started = performance.now();
+    await refuseSecretField(page, step, index);
+    try {
+      await perform(page, step, sleep);
+    } catch (error) {
+      const inner = isUltimateError(error) ? error : toUltimateError(error);
+      throw new UltimateError({
+        code: 'X_UI_INTERACT_STEP_FAILED',
+        cause: `step ${index} (${describe(step)}): ${inner.code} — ${inner.cause}`,
+        fix: FIX.failed,
+        meta: { step: index, code: inner.code },
+        sourceError: error,
+      });
+    }
+    const url = page.url();
+    if (new URL(url).origin !== origin) {
+      throw new UltimateError({
+        code: 'X_UI_INTERACT_LEFT_APP',
+        cause: `step ${index} (${describe(step)}) navigated to ${url}, off ${origin}`,
+        fix: FIX.left,
+        meta: { step: index, url },
+      });
+    }
+    await settle();
+    await sleep(SETTLE_POLL_MS);
+    const moved = url !== before;
+    navigated = navigated || moved;
+    results.push({
+      index,
+      kind: step.kind,
+      ms: Math.round(performance.now() - started),
+      navigated: moved,
+      url,
+    });
+  }
+  return { steps: results, navigated };
+}
+
+export async function interactRoute(
+  deps: InteractDeps,
+  input: UiInteractInput,
+): Promise<UiInteractResult> {
+  // Parsed BEFORE a browser exists: a refused list costs no navigation.
+  const steps = parseSteps(input.steps);
+  const sleep = deps.sleep ?? ((ms: number): Promise<void> => Bun.sleep(ms));
+  const server = await deps.boot();
+  const origin = new URL(server.url).origin;
+  const requestedUrl = new URL(input.route, server.url).toString();
+  const driver = await deps.driver(input.viewport);
+  const outDir = join(
+    deps.root,
+    SHOT_DIR,
+    shotSlug(input.route),
+    `${input.viewport.width}x${input.viewport.height}-${input.colorScheme}`,
+    `interact-${stepsHash(input.steps)}`,
+  );
+  // Holders rather than `let`s, for `ui.inspect`'s reason: an assignment inside `act` does not
+  // reach the narrowing below.
+  const ran: { run: StepsRun | null; seen: Seen | null; landedOn: string } = {
+    run: null,
+    seen: null,
+    landedOn: '',
+  };
+  const artifacts = await runShot({
+    route: input.route,
+    outDir,
+    driver,
+    boot: deps.boot,
+    settleMs: DEFAULT_SETTLE_MS,
+    timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
+    fullPage: input.fullPage,
+    colorScheme: input.colorScheme,
+    act: async (page, settle) => {
+      ran.landedOn = page.url();
+      ran.run = await runSteps(page, steps, settle, origin, sleep);
+      if (input.inspect !== undefined) ran.seen = await readInspect(page, input.inspect);
+    },
+  });
+  const verdict = artifacts.verdict;
+  const run = ran.run ?? { steps: [], navigated: false };
+  // The verdict fails a capture whose final URL is not the one requested — the sign-in redirect
+  // rule. A step that navigated is the agent's doing, not the server's, so it is excused ONLY
+  // when the page landed where it was asked and the verdict's other three rules hold.
+  const excused =
+    run.navigated &&
+    ran.landedOn === requestedUrl &&
+    verdict.errors === 0 &&
+    verdict.pageErrors.length === 0 &&
+    (verdict.islands?.failed ?? 0) === 0;
+  const inspect =
+    input.inspect === undefined || ran.seen === null
+      ? undefined
+      : {
+          title: ran.seen.probe?.title ?? '',
+          theme: ran.seen.probe?.theme ?? null,
+          activeElement: ran.seen.probe?.activeElement ?? null,
+          selectors: selectorsOf(input.inspect, ran.seen),
+          truncated: false,
+          droppedStyles: [],
+        };
+  return {
+    ok: verdict.ok || excused,
+    route: input.route,
+    finalUrl: verdict.finalUrl,
+    image: artifacts.image,
+    verdictFile: artifacts.verdictFile,
+    verdict: verdictJson(verdict),
+    steps: run.steps,
+    ...(inspect === undefined ? {} : { inspect }),
+  };
+}