@ultimat3/cli 20.1.5 → 20.2.0

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

package/src/mcp-ui.ts

@@ -1,6 +1,9 @@
-// The dev MCP server's two eyes: `ui.shot` (a route) and `ui.island` (a component's states), as
-// the `DevCapabilities` half `packages/mcp` declares and cannot satisfy — a browser is the CLI's
-// to launch. Both are `x shot` under another name: the same server lookup (a running `x dev` is
+// The dev MCP server's eyes and hand: `ui.shot` (a route), `ui.island` (a component's states),
+// `ui.inspect` (DOM facts for a set of selectors, in `mcp-ui-inspect.ts`), `ui.interact` (steps
+// first, then the picture, in `mcp-ui-interact.ts`) and `ui.diff` (two captures compared, in
+// `mcp-ui-diff.ts`), as the `DevCapabilities` half `packages/mcp` declares and cannot satisfy — a
+// browser is the CLI's to launch, and the files are the CLI's to read. The four that look
+// are `x shot` under another name: the same server lookup (a running `x dev` is
 // reused through its lock, otherwise a scratch one boots), the same driver, the same verdict.
 // Nothing here is a new capability; it is the existing one made reachable from inside the loop
 // an agent already works in, so "does it look right" stops needing a hand-written script.
@@ -8,7 +11,18 @@
 // why: Bun exposes no path-join primitive, and the picture's directory is a path an agent opens.
 import { join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
-import type { UiIslandInput, UiIslandResult, UiShotInput, UiShotResult } from '@ultimat3/mcp';
+import type {
+  UiDiffInput,
+  UiDiffResult,
+  UiInspectInput,
+  UiInspectResult,
+  UiInteractInput,
+  UiInteractResult,
+  UiIslandInput,
+  UiIslandResult,
+  UiShotInput,
+  UiShotResult,
+} from '@ultimat3/mcp';
 import { describeRoutes } from '@ultimat3/render';
 import type { ScrapeDriver } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
@@ -17,6 +31,9 @@ import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import { islandShot } from './cmd-shot-island';
 import type { Env } from './dev-services';
 import { islandVerdictJson } from './island-verdict';
+import { diffShots } from './mcp-ui-diff';
+import { inspectRoute } from './mcp-ui-inspect';
+import { interactRoute } from './mcp-ui-interact';
 import { retryMemo } from './retry-memo';
 import { shotBrowserChoice } from './shot-browser';
 import { devServerFor, type ShotServer } from './shot-server';
@@ -44,7 +61,7 @@ export function assertBudgetedRoute(route: string, declared: readonly DeclaredRo
     throw new UltimateError({
       code: 'X_UI_SHOT_ROUTE_UNKNOWN',
       cause: `no route in this app answers ${route}`,
-      fix: 'x routes --json   # then ui.shot with one of its `path` values',
+      fix: 'x routes --json   # then call the ui.* tool with one of its `path` values',
     });
   }
   if (hit.budgetJs === null) {
@@ -78,6 +95,10 @@ export interface UiHostInput {
 export interface UiCapabilities {
   shotRoute(shot: UiShotInput): Promise<UiShotResult>;
   shotIsland(island: UiIslandInput): Promise<UiIslandResult>;
+  inspectRoute(inspect: UiInspectInput): Promise<UiInspectResult>;
+  interactRoute(interact: UiInteractInput): Promise<UiInteractResult>;
+  /** Two captures under `.x/shot/` compared without a browser; never boots the scratch server. */
+  diffShots(diff: UiDiffInput): Promise<UiDiffResult>;
   /** Stops the scratch server, if one was booted. Never boots one in order to stop it. */
   close(): Promise<void>;
 }
@@ -100,6 +121,17 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
   // provider's CDP URL, or the launcher's own discovery.
   const browser = () => shotBrowserChoice({ cdpFlag: undefined, browserFlag: undefined, env });
   const routes = input.routes ?? describeRoutes;
+  // One browser per call, sized to the call: the injected driver in a test, `appBrowser` otherwise.
+  const driverFor = async (viewport: UiShotInput['viewport']): Promise<ScrapeDriver> => {
+    if (input.driver !== undefined) return input.driver(viewport);
+    const { cdpUrl, executablePath } = browser();
+    return appBrowser({
+      root,
+      viewport,
+      ...(executablePath === undefined ? {} : { executablePath }),
+      ...(cdpUrl === undefined ? {} : { cdpUrl }),
+    });
+  };
   let closed = false;
 
   return {
@@ -113,16 +145,7 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
 
     async shotRoute(shot) {
       assertBudgetedRoute(shot.route, routes());
-      const { cdpUrl, executablePath } = browser();
-      const driver =
-        input.driver === undefined
-          ? await appBrowser({
-              root,
-              viewport: shot.viewport,
-              ...(executablePath === undefined ? {} : { executablePath }),
-              ...(cdpUrl === undefined ? {} : { cdpUrl }),
-            })
-          : await input.driver(shot.viewport);
+      const driver = await driverFor(shot.viewport);
       // One directory per (route, viewport, scheme), so two pictures of one route at two widths
       // never overwrite each other and an agent can hold both.
       const outDir = join(
@@ -149,6 +172,21 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
       };
     },
 
+    async inspectRoute(inspect) {
+      // The same gate as `ui.shot`, for the same reason: facts about a draft are facts about the
+      // wrong thing.
+      assertBudgetedRoute(inspect.route, routes());
+      return inspectRoute({ root, boot, driver: driverFor }, inspect);
+    },
+
+    async interactRoute(interact) {
+      assertBudgetedRoute(interact.route, routes());
+      return interactRoute({ root, boot, driver: driverFor }, interact);
+    },
+    // No route gate and no boot: the captures were gated when they were taken, and a diff of two
+    // files needs neither a server nor a browser.
+    diffShots: (diff) => diffShots({ root }, diff),
+
     async shotIsland(island) {
       const { cdpUrl, executablePath } = browser();
       const artifacts = await islandShot({

package/src/output.ts

@@ -64,7 +64,7 @@ export interface CommandResult {
    * Which fd this result is written to. `stdout` for every command, absent included — and
    * `stderr` for the one case where fd 1 is not the command's to write on: `x mcp serve
    * --transport stdio`, whose stdout carries JSON-RPC frames, and where the `✓ mcp stdio serving
-   * 15 tools` line printed after the loop exits is a malformed frame to whatever is reading.
+   * 18 tools` line printed after the loop exits is a malformed frame to whatever is reading.
    *
    * Behaviour, not a fact, exactly like `hold` above — so NEITHER renderer carries it. It says
    * where a rendered line goes, and a payload that also claimed it would be a second answer to a

package/src/prerender.ts

@@ -30,6 +30,7 @@ import {
   serviceWorkerHead,
   serviceWorkerRegistration,
 } from './sw-artifacts';
+import { loadThemeMode, themeBoot } from './theme-boot';
 
 // Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
 // carries it, and this file already imports that module.
@@ -186,6 +187,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // wiring exists to close. `undefined` when the app is not installable, and then no document
   // names it either.
   const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
   // The registration TAG now, the worker itself after the render loop — the two halves are wanted
   // at different moments and used to be taken at the same one. Every document below has to name
   // `/x-sw-register.js`, and the worker's precache manifest is built from the content hash of
@@ -238,6 +240,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     runWithContext(as, () =>
       routeDocument(entry, data, {
         resolveIsland: (file: string) => islands.resolverFor(file),
+        themeHead: theme.head,
         ...(pwa === undefined ? {} : { pwaHead: pwa.head + (swHead ?? '') }),
       }),
     );

package/src/scaffold-typecheck.ts

@@ -146,6 +146,11 @@ const overlay = (root: string, app: string): string =>
       compilerOptions: {
         noEmit: true,
         paths: {
+          // The two subpath exports a generated app reaches for, spelled the way the packages'
+          // own `exports` maps spell them — the wildcard below would read `ui/icons/zap` as a
+          // package name. Longest prefix wins, so these are consulted first.
+          '@ultimat3/ui/icons/*': [`${root}/packages/ui/src/icons/glyphs/*`],
+          '@ultimat3/render/server': [`${root}/packages/render/src/server`],
           '@ultimat3/*': [`${root}/packages/*/src`],
           [`@${app}/web/*`]: ['./apps/web/*'],
           [`@${app}/admin/*`]: ['./apps/admin/*'],

package/src/script-csp.ts

@@ -11,7 +11,10 @@ import { HYDRATE_RUNTIME_BODIES } from '@ultimat3/render';
  * Hashes, never a nonce: a `render: 'static'` page is a file on disk, so no per-response value can
  * reach it. Read from `@ultimat3/render`'s own enumeration rather than restated here — the body
  * the document carries and the body the policy hashes have to be one string.
+ *
+ * `extra` is for sources the caller already hashed from a body it emits — the theme boot's,
+ * which `theme-boot.ts` derives from the same string it inlines.
  */
-export function inlineScriptSources(): readonly string[] {
-  return [...new Set(HYDRATE_RUNTIME_BODIES.map(cspHashSource))].sort();
+export function inlineScriptSources(extra: readonly string[] = []): readonly string[] {
+  return [...new Set([...HYDRATE_RUNTIME_BODIES.map(cspHashSource), ...extra])].sort();
 }