@ultimat3/mcp 20.1.6 → 20.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "20.1.6",
+  "version": "20.2.1",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "20.1.6",
-    "@ultimat3/core": "20.1.6",
-    "@ultimat3/entity": "20.1.6",
-    "@ultimat3/http": "20.1.6",
-    "@ultimat3/jobs": "20.1.6",
-    "@ultimat3/policy": "20.1.6",
-    "@ultimat3/query": "20.1.6",
-    "@ultimat3/schema": "20.1.6"
+    "@ultimat3/action": "20.2.1",
+    "@ultimat3/core": "20.2.1",
+    "@ultimat3/entity": "20.2.1",
+    "@ultimat3/http": "20.2.1",
+    "@ultimat3/jobs": "20.2.1",
+    "@ultimat3/policy": "20.2.1",
+    "@ultimat3/query": "20.2.1",
+    "@ultimat3/schema": "20.2.1"
   }
 }

package/src/dev-server.ts

@@ -10,6 +10,19 @@
 // packages of this same tier, and the shell-side capabilities (db, tests, logs) belong to
 // the CLI, so this file defines the interface and the CLI satisfies it.
 
+import type { UiInteractInput, UiInteractResult } from './dev-ui-interact';
+import { uiInteractTools } from './dev-ui-interact';
+import type {
+  UiDiffInput,
+  UiDiffResult,
+  UiInspectInput,
+  UiInspectResult,
+  UiIslandInput,
+  UiIslandResult,
+  UiShotInput,
+  UiShotResult,
+} from './dev-ui-tools';
+import { uiTools } from './dev-ui-tools';
 import type { QueryLimits, QueryRows } from './query-limits';
 import { capQueryRows, DEFAULT_QUERY_ROWS, QUERY_LIMITS, resolveQueryLimits } from './query-limits';
 import type { DatabaseTarget } from './readonly-sql';
@@ -19,6 +32,45 @@ import { jsonResult, textResult } from './registry';
 import type { JsonSchema } from './wire';
 import { NO_ARGS } from './wire';
 
+export type {
+  UiInspectSpec,
+  UiInteractInput,
+  UiInteractInspect,
+  UiInteractResult,
+  UiInteractStep,
+  UiInteractStepKind,
+  UiInteractStepResult,
+} from './dev-ui-interact';
+export { UI_INTERACT_LIMITS, UI_INTERACT_STEP_SCHEMA, uiInteractTools } from './dev-ui-interact';
+// Re-exported, not re-declared: `index.ts` and the CLI import the `ui.*` vocabulary from here, and
+// the extraction to `dev-ui-tools.ts` was about the ceiling, never about moving the API.
+export type {
+  UiColorScheme,
+  UiDiffInput,
+  UiDiffResult,
+  UiInspectActive,
+  UiInspectBox,
+  UiInspectInput,
+  UiInspectIslands,
+  UiInspectMatch,
+  UiInspectResult,
+  UiInspectSelector,
+  UiIslandInput,
+  UiIslandResult,
+  UiScopes,
+  UiShotInput,
+  UiShotResult,
+  UiViewportName,
+} from './dev-ui-tools';
+export {
+  STYLE_NAME,
+  UI_DIFF_DEFAULT_THRESHOLD,
+  UI_INSPECT_LIMITS,
+  UI_VIEWPORTS,
+  uiTools,
+  viewportOf,
+} from './dev-ui-tools';
+
 /** Scopes the dev server gates on. A token carries a subset; the rest is invisible. */
 export const DEV_SCOPES = {
   read: 'dev:read',
@@ -68,59 +120,6 @@ export interface VerifyResult {
 }
 
 /** Description sources. Satisfied by `frameworkIntrospection` in a real app. */
-/**
- * The viewports `ui.shot` names. Named, not free, so two agents (or one agent twice) photograph
- * the same thing and can compare the pictures; `{ width, height }` stays available for the one
- * case a name does not cover.
- */
-export const UI_VIEWPORTS = {
-  phone: { width: 390, height: 844 },
-  tablet: { width: 820, height: 1180 },
-  desktop: { width: 1440, height: 900 },
-} as const;
-export type UiViewportName = keyof typeof UI_VIEWPORTS;
-export type UiColorScheme = 'light' | 'dark';
-
-export interface UiShotInput {
-  /** The route's path — `/dashboard`, `/links/abc123` — never a full URL. */
-  readonly route: string;
-  readonly viewport: { readonly width: number; readonly height: number };
-  /**
-   * What `prefers-color-scheme` the page sees. Emulated on the page BEFORE navigation, so a
-   * capture never depends on the box that took it; an app whose boot script honours a stored
-   * choice still wins, because the stored choice is what "explicit" means.
-   */
-  readonly colorScheme: UiColorScheme;
-  readonly fullPage: boolean;
-}
-
-/**
- * What a picture is worth: the file, and the verdict beside it. The verdict is the SAME shape
- * `x shot` writes to `verdict.json` — console lines, page errors, network refusals, whether every
- * island mounted — so a picture with a hydration error is a finding, never merely a picture.
- * The PNG is a PATH, never inlined bytes: an agent reads the picture it wants and pays for one.
- */
-export interface UiShotResult {
-  readonly ok: boolean;
-  readonly image: string;
-  readonly verdictFile: string;
-  readonly verdict: unknown;
-}
-
-export interface UiIslandInput {
-  /** The island's name as `x shot --island <name>` takes it. */
-  readonly island: string;
-  /** One declared state, or every state the island declares. */
-  readonly state?: string | undefined;
-}
-
-export interface UiIslandResult {
-  readonly ok: boolean;
-  readonly dir: string;
-  readonly verdictFile: string;
-  readonly verdict: unknown;
-}
-
 export interface DevIntrospection {
   routes(): unknown;
   entities(): unknown;
@@ -156,6 +155,24 @@ export interface DevCapabilities {
   shotRoute(input: UiShotInput): Promise<UiShotResult>;
   /** `x shot --island <name> [--state <id>]` as a tool: every declared state, photographed and judged. */
   shotIsland(input: UiIslandInput): Promise<UiIslandResult>;
+  /**
+   * DOM, computed-style and (optionally) accessibility facts for a set of selectors, read in ONE
+   * navigation of the route — the browser is the cost, so one call reads many. Same route gate
+   * as `shotRoute`; takes the same PNG and verdict, under an `inspect/` subdirectory.
+   */
+  inspectRoute(input: UiInspectInput): Promise<UiInspectResult>;
+  /**
+   * Drive the route through a bounded step list (click, type, press, focus, wait), each step
+   * followed by an island settle, then photograph it and optionally read `inspectRoute`'s facts —
+   * ONE navigation. Same route gate; the PNG lands under `interact-<hash of the steps>/`.
+   */
+  interactRoute(input: UiInteractInput): Promise<UiInteractResult>;
+  /**
+   * Compare two PNGs the `ui.*` tools wrote — both paths relative to the app root and confined to
+   * `.x/shot/`, which is what lets a tool that reads files sit under `dev:read`. No browser: the
+   * pixels are decoded, counted and written back by `@ultimat3/core`'s raw-pixel seam.
+   */
+  diffShots(input: UiDiffInput): Promise<UiDiffResult>;
 }
 
 export type DevHost = DevIntrospection & DevCapabilities;
@@ -166,19 +183,6 @@ const NAME_ARG: JsonSchema = {
   additionalProperties: false,
 };
 
-/**
- * An explicit `width`+`height` wins over the name; one of the pair alone is not a viewport and
- * falls back to the name (default `desktop`) rather than to a half-sized frame.
- */
-export function viewportOf(args: ToolArgs): { readonly width: number; readonly height: number } {
-  const width = args['width'];
-  const height = args['height'];
-  if (typeof width === 'number' && typeof height === 'number') return { width, height };
-  const name = args['viewport'];
-  const named = typeof name === 'string' && Object.hasOwn(UI_VIEWPORTS, name) ? name : 'desktop';
-  return UI_VIEWPORTS[named as UiViewportName];
-}
-
 /** Every dev tool, in one array so `x mcp serve` and the HTTP transport share the catalog. */
 export function devTools(host: DevHost): readonly AnyMcpTool[] {
   return [
@@ -333,67 +337,11 @@ export function devTools(host: DevHost): readonly AnyMcpTool[] {
         return { ...jsonResult(result), ...(result.ok ? {} : { isError: true }) };
       },
     },
-    {
-      name: 'ui.shot',
-      description:
-        'Photograph one route at a named viewport (phone/tablet/desktop) or an explicit size, ' +
-        'in light or dark, against the running dev server. Returns the PNG path and the same ' +
-        'verdict x shot writes: console, page errors, refused requests, whether every island ' +
-        'mounted. Refuses a route with no declared JS budget. Launches a browser.',
-      scope: DEV_SCOPES.test,
-      destructive: true,
-      inputSchema: {
-        type: 'object',
-        properties: {
-          route: { type: 'string', description: 'Route path, e.g. /dashboard.' },
-          viewport: {
-            type: 'string',
-            enum: Object.keys(UI_VIEWPORTS),
-            default: 'desktop',
-            description: 'phone 390×844, tablet 820×1180, desktop 1440×900.',
-          },
-          width: { type: 'integer', minimum: 320, maximum: 3840 },
-          height: { type: 'integer', minimum: 320, maximum: 2160 },
-          theme: { type: 'string', enum: ['light', 'dark'], default: 'dark' },
-          fullPage: { type: 'boolean', default: true },
-        },
-        required: ['route'],
-        additionalProperties: false,
-      },
-      async handle(args: ToolArgs) {
-        const route = typeof args['route'] === 'string' ? args['route'] : '';
-        const result = await host.shotRoute({
-          route,
-          viewport: viewportOf(args),
-          colorScheme: args['theme'] === 'light' ? 'light' : 'dark',
-          fullPage: args['fullPage'] !== false,
-        });
-        return { ...jsonResult(result), ...(result.ok ? {} : { isError: true }) };
-      },
-    },
-    {
-      name: 'ui.island',
-      description:
-        'Photograph an island in every state its *.island.states.ts declares (or one state), ' +
-        'as x shot --island does: PNGs plus a verdict per state. Launches a browser.',
-      scope: DEV_SCOPES.test,
-      destructive: true,
-      inputSchema: {
-        type: 'object',
-        properties: {
-          island: { type: 'string', description: 'Island name, e.g. links-table.' },
-          state: { type: 'string', description: 'One declared state id; omit for all.' },
-        },
-        required: ['island'],
-        additionalProperties: false,
-      },
-      async handle(args: ToolArgs) {
-        const island = typeof args['island'] === 'string' ? args['island'] : '';
-        const state = typeof args['state'] === 'string' ? args['state'] : undefined;
-        const result = await host.shotIsland({ island, ...(state === undefined ? {} : { state }) });
-        return { ...jsonResult(result), ...(result.ok ? {} : { isError: true }) };
-      },
-    },
+    // The five `ui.*` tools live in `dev-ui-tools.ts` and `dev-ui-interact.ts` (ceiling); same
+    // catalog. Four launch a browser under `dev:test`; `ui.diff` reads two files they already
+    // wrote, under `dev:read`.
+    ...uiTools(host, { test: DEV_SCOPES.test, read: DEV_SCOPES.read }),
+    ...uiInteractTools(host, DEV_SCOPES.test),
     {
       name: 'logs.tail',
       description: 'Last N log lines, optionally for one runtime role (web/sync/worker/...).',

package/src/dev-ui-interact.ts

@@ -0,0 +1,226 @@
+// `ui.interact` — the dev server's hand. An agent that needs the ⌘K palette open, a dialog up or a
+// field filled before the picture is worth taking drives the route through a BOUNDED list of
+// steps, and gets the picture, the verdict and (on request) `ui.inspect`'s facts in ONE
+// navigation. Its own file for the reason `dev-ui-tools.ts` has one: that file stands near the
+// 500-line ceiling, and this tool's step schema alone is a screen. `dev-server.ts` spreads both.
+//
+// Every bound lives in the HANDLER's contract, not the schema: `validate-args.ts` enforces no
+// `maxItems`, and a step list the schema cannot bound is one the CLI refuses whole — never trims,
+// because dropping a step changes what the picture is of. The schema's job is the SHAPE of a step
+// (`anyOf` over five one-key objects); the CLI's is the count, the lengths and the policies.
+
+import type {
+  UiColorScheme,
+  UiInspectActive,
+  UiInspectInput,
+  UiInspectSelector,
+} from './dev-ui-tools';
+import { inspectSpecOf, VIEWPORT_ARGS, viewportOf } from './dev-ui-tools';
+import type { AnyMcpTool, ToolArgs } from './registry';
+import { jsonResult } from './registry';
+import type { JsonSchema } from './wire';
+
+/**
+ * Bounds the CLI holds a step list to. `steps` is a scene, not a script: twelve is enough to open
+ * a palette, type a query and pick a row, and a longer list is a test that belongs in `x test`.
+ * `waitMs` is a CSS transition's worth, not a network's — a `wait` on a selector waits within the
+ * shot timeout instead. `textChars` bounds what one `type` step may put into a field.
+ */
+export const UI_INTERACT_LIMITS = { steps: 12, textChars: 500, waitMs: 5000 } as const;
+
+/** One step, as the wire carries it: exactly ONE key, naming the verb. */
+export type UiInteractStep =
+  | { readonly click: string }
+  | { readonly type: { readonly selector: string; readonly text: string } }
+  | { readonly press: string }
+  | { readonly focus: string }
+  | { readonly wait: number | string };
+
+export type UiInteractStepKind = 'click' | 'type' | 'press' | 'focus' | 'wait';
+
+/** The `ui.inspect` block `ui.interact` runs AFTER its steps — the same four fields, same bounds. */
+export type UiInspectSpec = Pick<UiInspectInput, 'selectors' | 'styles' | 'a11y' | 'activeElement'>;
+
+export interface UiInteractInput {
+  readonly route: string;
+  readonly viewport: { readonly width: number; readonly height: number };
+  readonly colorScheme: UiColorScheme;
+  /** Default FALSE, unlike `ui.shot`: a dialog or a palette is judged on the fold it opened in. */
+  readonly fullPage: boolean;
+  /**
+   * What the wire carried, one record per step, already shaped by the schema's `anyOf`. Records
+   * and not `UiInteractStep`: the CLI parses them — count, lengths, the one-key rule — and refuses
+   * the whole list with `X_UI_INTERACT_STEPS_INVALID`, so a host reached without the schema (a
+   * test, a script) is held to the same rule.
+   */
+  readonly steps: readonly Readonly<Record<string, unknown>>[];
+  readonly inspect?: UiInspectSpec | undefined;
+}
+
+export interface UiInteractStepResult {
+  readonly index: number;
+  readonly kind: UiInteractStepKind;
+  /** Wall time the step took, settle included. */
+  readonly ms: number;
+  /** The page's URL changed during this step — a same-origin navigation the step caused. */
+  readonly navigated: boolean;
+  readonly url: string;
+}
+
+/** `ui.inspect`'s document-and-selectors block, read after the last step settled. */
+export interface UiInteractInspect {
+  readonly title: string;
+  readonly theme: string | null;
+  readonly activeElement: UiInspectActive | null;
+  readonly selectors: readonly UiInspectSelector[];
+  readonly truncated: boolean;
+  readonly droppedStyles: readonly string[];
+}
+
+export interface UiInteractResult {
+  /**
+   * The verdict's `ok` — with one reading of its own: a same-origin navigation a STEP caused is
+   * not the redirect `ui.shot` fails a capture for. The verdict still reports `redirected`.
+   */
+  readonly ok: boolean;
+  readonly route: string;
+  readonly finalUrl: string;
+  readonly image: string;
+  readonly verdictFile: string;
+  readonly verdict: unknown;
+  readonly steps: readonly UiInteractStepResult[];
+  readonly inspect?: UiInteractInspect | undefined;
+}
+
+export interface UiInteractHost {
+  interactRoute(input: UiInteractInput): Promise<UiInteractResult>;
+}
+
+const selector = (what: string): JsonSchema => ({
+  type: 'string',
+  minLength: 1,
+  description: what,
+});
+
+const oneKey = (key: string, value: JsonSchema): JsonSchema => ({
+  type: 'object',
+  properties: { [key]: value },
+  required: [key],
+  additionalProperties: false,
+});
+
+/** Five shapes, one key each. A step with two verbs has no order, so it has no shape here. */
+export const UI_INTERACT_STEP_SCHEMA: JsonSchema = {
+  anyOf: [
+    oneKey('click', selector('CSS selector of the element to click (first match).')),
+    oneKey('type', {
+      type: 'object',
+      properties: {
+        selector: selector('CSS selector of the field; a password field is refused.'),
+        text: {
+          type: 'string',
+          minLength: 1,
+          description: `Keystrokes to send, at most ${UI_INTERACT_LIMITS.textChars} characters.`,
+        },
+      },
+      required: ['selector', 'text'],
+      additionalProperties: false,
+    }),
+    oneKey('press', selector("A key chord on whatever holds focus: 'Meta+K', 'Escape', 'Enter'.")),
+    oneKey('focus', selector('CSS selector of the element to move focus to.')),
+    oneKey('wait', {
+      anyOf: [
+        {
+          type: 'integer',
+          minimum: 0,
+          description: `Milliseconds to pause, at most ${UI_INTERACT_LIMITS.waitMs}.`,
+        },
+        selector('CSS selector to wait VISIBLE, within the shot timeout.'),
+      ],
+    }),
+  ],
+};
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Everything array-shaped goes through; the CLI is the parser, and it refuses whole. */
+const stepsOf = (value: unknown): readonly Readonly<Record<string, unknown>>[] =>
+  Array.isArray(value)
+    ? value.map((item): Readonly<Record<string, unknown>> => (isRecord(item) ? item : {}))
+    : [];
+
+/** The one `ui.interact` tool, spread into the dev catalog beside the three `ui.*` eyes. */
+export function uiInteractTools(host: UiInteractHost, scope: string): readonly AnyMcpTool[] {
+  return [
+    {
+      name: 'ui.interact',
+      description:
+        `Drive one route through at most ${UI_INTERACT_LIMITS.steps} steps — click, type, press a ` +
+        'key chord, focus, wait — then photograph it and (optionally) read the same DOM, style and ' +
+        'a11y facts ui.inspect reads, all in ONE navigation. Each step waits for the islands to ' +
+        'settle; per step you get whether it navigated and where. Refuses a step list over the ' +
+        "bounds (never trims), typing into a password field, and any step that leaves the app's " +
+        'origin. Same PNG and verdict as ui.shot, under interact-<hash>/; `ok` is the verdict. ' +
+        'Launches a browser.',
+      scope,
+      destructive: true,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          route: { type: 'string', description: 'Route path, e.g. /dashboard.' },
+          ...VIEWPORT_ARGS,
+          fullPage: { type: 'boolean', default: false },
+          steps: {
+            type: 'array',
+            items: UI_INTERACT_STEP_SCHEMA,
+            description:
+              `In order, at most ${UI_INTERACT_LIMITS.steps}. Each is ONE of {click}, {type: {selector, text}}, ` +
+              '{press}, {focus}, {wait: ms | selector}.',
+          },
+          inspect: {
+            type: 'object',
+            description:
+              'ui.inspect’s block, run after the last step: selectors, styles, a11y, activeElement.',
+            properties: {
+              selectors: { type: 'array', items: { type: 'string', minLength: 1 } },
+              styles: { type: 'array', items: { type: 'string' } },
+              a11y: { type: 'boolean', default: false },
+              activeElement: { type: 'boolean', default: true },
+            },
+            required: ['selectors'],
+            additionalProperties: false,
+          },
+        },
+        required: ['route', 'steps'],
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        const route = typeof args['route'] === 'string' ? args['route'] : '';
+        const asked = isRecord(args['inspect']) ? inspectSpecOf(args['inspect']) : undefined;
+        const result = await host.interactRoute({
+          route,
+          viewport: viewportOf(args),
+          colorScheme: args['theme'] === 'light' ? 'light' : 'dark',
+          fullPage: args['fullPage'] === true,
+          steps: stepsOf(args['steps']),
+          ...(asked === undefined ? {} : { inspect: asked.spec }),
+        });
+        // The same confession `ui.inspect` makes: what the handler trimmed, named in the answer.
+        const inspect =
+          result.inspect === undefined || asked === undefined
+            ? result.inspect
+            : {
+                ...result.inspect,
+                truncated: result.inspect.truncated || asked.trimmed,
+                droppedStyles: asked.droppedStyles,
+              };
+        const answer: UiInteractResult = {
+          ...result,
+          ...(inspect === undefined ? {} : { inspect }),
+        };
+        return { ...jsonResult(answer), ...(answer.ok ? {} : { isError: true }) };
+      },
+    },
+  ];
+}

package/src/dev-ui-tools.ts

@@ -0,0 +1,439 @@
+// The dev server's eyes: `ui.shot` (a route), `ui.island` (a component's states), `ui.inspect`
+// (DOM, computed-style and accessibility facts for a set of selectors, in ONE navigation) and
+// `ui.diff` (two captures the others wrote, compared without a browser). Split
+// out of `dev-server.ts` because that file stood at 439 lines against the 500-line ceiling and a
+// third `ui.*` literal would have crossed it — the catalog is still one array; `devTools` spreads
+// this one in. Every type here is re-exported from `dev-server.ts`, so the CLI and the package
+// index import what they always did.
+//
+// A browser is the expensive half of every call here, which is why `ui.inspect` reads MANY
+// selectors per navigation and bounds each answer in the handler: a model that asks for a
+// thousand selectors gets twenty and a `truncated: true`, never a thousand navigations.
+
+import type { AnyMcpTool, ToolArgs } from './registry';
+import { jsonResult } from './registry';
+
+/**
+ * The viewports `ui.shot` names. Named, not free, so two agents (or one agent twice) photograph
+ * the same thing and can compare the pictures; `{ width, height }` stays available for the one
+ * case a name does not cover.
+ */
+export const UI_VIEWPORTS = {
+  phone: { width: 390, height: 844 },
+  tablet: { width: 820, height: 1180 },
+  desktop: { width: 1440, height: 900 },
+} as const;
+export type UiViewportName = keyof typeof UI_VIEWPORTS;
+export type UiColorScheme = 'light' | 'dark';
+
+export interface UiShotInput {
+  /** The route's path — `/dashboard`, `/links/abc123` — never a full URL. */
+  readonly route: string;
+  readonly viewport: { readonly width: number; readonly height: number };
+  /**
+   * What `prefers-color-scheme` the page sees. Emulated on the page BEFORE navigation, so a
+   * capture never depends on the box that took it; an app whose boot script honours a stored
+   * choice still wins, because the stored choice is what "explicit" means.
+   */
+  readonly colorScheme: UiColorScheme;
+  readonly fullPage: boolean;
+}
+
+/**
+ * What a picture is worth: the file, and the verdict beside it. The verdict is the SAME shape
+ * `x shot` writes to `verdict.json` — console lines, page errors, network refusals, whether every
+ * island mounted — so a picture with a hydration error is a finding, never merely a picture.
+ * The PNG is a PATH, never inlined bytes: an agent reads the picture it wants and pays for one.
+ */
+export interface UiShotResult {
+  readonly ok: boolean;
+  readonly image: string;
+  readonly verdictFile: string;
+  readonly verdict: unknown;
+}
+
+export interface UiIslandInput {
+  /** The island's name as `x shot --island <name>` takes it. */
+  readonly island: string;
+  /** One declared state, or every state the island declares. */
+  readonly state?: string | undefined;
+}
+
+export interface UiIslandResult {
+  readonly ok: boolean;
+  readonly dir: string;
+  readonly verdictFile: string;
+  readonly verdict: unknown;
+}
+
+/**
+ * Every bound `ui.inspect` applies, in one place, so the handler (selectors, styles), the in-page
+ * probe (matches, text, attrs) and the wire cap (bytes) cannot drift apart. Each one exists
+ * because the alternative is unbounded: a `*` selector on a long page is thousands of matches,
+ * and a match's `textContent` on `<body>` is the whole document.
+ */
+export const UI_INSPECT_LIMITS = {
+  selectors: 20,
+  styles: 32,
+  matches: 25,
+  textChars: 200,
+  attrs: 20,
+  bytes: 64 * 1024,
+} as const;
+
+/** A computed-style property name as CSS spells it: `color`, `font-size`, never `fontSize`. */
+export const STYLE_NAME = /^[a-z][a-z0-9-]*$/;
+
+export interface UiInspectInput {
+  readonly route: string;
+  readonly viewport: { readonly width: number; readonly height: number };
+  readonly colorScheme: UiColorScheme;
+  /** At most `UI_INSPECT_LIMITS.selectors`; the handler trims and says so. */
+  readonly selectors: readonly string[];
+  /** Computed property names, already filtered to `STYLE_NAME` and at most `.styles` of them. */
+  readonly styles: readonly string[];
+  /** Read the browser's computed role and name per match. Off by default: one round trip each. */
+  readonly a11y: boolean;
+  readonly activeElement: boolean;
+}
+
+export interface UiInspectBox {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface UiInspectMatch {
+  readonly tag: string;
+  /** Whitespace-collapsed `textContent`, at most `UI_INSPECT_LIMITS.textChars`. */
+  readonly text: string;
+  readonly box: UiInspectBox;
+  readonly visible: boolean;
+  /** At most `UI_INSPECT_LIMITS.attrs` entries, in document order. */
+  readonly attrs: Readonly<Record<string, string>>;
+  readonly styles: Readonly<Record<string, string>>;
+  /** Present only when `a11y: true` was asked and the driver answered for this match. */
+  readonly a11y?: { readonly role: string; readonly name: string } | undefined;
+}
+
+export interface UiInspectSelector {
+  readonly selector: string;
+  /** `false` when `querySelectorAll` threw: a malformed selector is a fact, not a crash. */
+  readonly valid: boolean;
+  readonly count: number;
+  /** More matched than `matches` carries — the in-page cap, or the wire cap dropping them. */
+  readonly truncated: boolean;
+  readonly matches: readonly UiInspectMatch[];
+}
+
+export interface UiInspectActive {
+  readonly tag: string;
+  readonly id: string;
+  readonly role: string;
+  readonly name: string;
+}
+
+export interface UiInspectIslands {
+  readonly declared: number;
+  readonly booted: number;
+  readonly mounted: number;
+  readonly failed: number;
+}
+
+export interface UiInspectResult {
+  /** The verdict's `ok`, by `ui.shot`'s rule: no console error, no throw, no failed mount, no redirect. */
+  readonly ok: boolean;
+  readonly route: string;
+  readonly finalUrl: string;
+  readonly title: string;
+  /** `document.documentElement`'s `data-theme`, or `null` when the app sets none. */
+  readonly theme: string | null;
+  readonly activeElement: UiInspectActive | null;
+  /** The same island count `ui.island` reads; `null` when the page answered no probe. */
+  readonly islands: UiInspectIslands | null;
+  readonly consoleErrors: readonly string[];
+  readonly pageErrors: readonly string[];
+  readonly refused: number;
+  readonly selectors: readonly UiInspectSelector[];
+  readonly image: string;
+  readonly verdictFile: string;
+  /** Selectors were trimmed, or matches were dropped to fit the wire cap. */
+  readonly truncated: boolean;
+  /** Style names that failed `STYLE_NAME` or fell past the cap — named, so a typo is visible. */
+  readonly droppedStyles: readonly string[];
+}
+
+export interface UiDiffInput {
+  /** Both paths relative to the app root, and both under `.x/shot/` — the host refuses the rest. */
+  readonly before: string;
+  readonly after: string;
+  /** Per-channel delta as a fraction of 255 above which a pixel counts as changed. */
+  readonly threshold: number;
+  /** Where to write the diff PNG, relative to the app root; default beside `after`. */
+  readonly out?: string | undefined;
+}
+
+export interface UiDiffResult {
+  readonly ok: true;
+  readonly before: string;
+  readonly after: string;
+  readonly width: number;
+  readonly height: number;
+  readonly changedPixels: number;
+  /** Two decimals. */
+  readonly changedPercent: number;
+  /** The bounding box of every changed pixel, or `null` when the two captures match. */
+  readonly changedBox: UiInspectBox | null;
+  /** The written diff PNG's path. */
+  readonly diff: string;
+}
+
+/** The default `threshold`: a tenth of the channel range, which absorbs a one-level wobble. */
+export const UI_DIFF_DEFAULT_THRESHOLD = 0.1;
+
+/** The capability half these four tools need. `DevCapabilities` satisfies it structurally. */
+export interface UiHost {
+  shotRoute(input: UiShotInput): Promise<UiShotResult>;
+  shotIsland(input: UiIslandInput): Promise<UiIslandResult>;
+  inspectRoute(input: UiInspectInput): Promise<UiInspectResult>;
+  diffShots(input: UiDiffInput): Promise<UiDiffResult>;
+}
+
+/** The scopes the `ui.*` tools split across: the browser-launching three, and the one that reads. */
+export interface UiScopes {
+  readonly test: string;
+  readonly read: string;
+}
+
+/**
+ * An explicit `width`+`height` wins over the name; one of the pair alone is not a viewport and
+ * falls back to the name (default `desktop`) rather than to a half-sized frame.
+ */
+export function viewportOf(args: ToolArgs): { readonly width: number; readonly height: number } {
+  const width = args['width'];
+  const height = args['height'];
+  if (typeof width === 'number' && typeof height === 'number') return { width, height };
+  const name = args['viewport'];
+  const named = typeof name === 'string' && Object.hasOwn(UI_VIEWPORTS, name) ? name : 'desktop';
+  return UI_VIEWPORTS[named as UiViewportName];
+}
+
+const strings = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+
+export interface InspectSpecRead {
+  readonly spec: Pick<UiInspectInput, 'selectors' | 'styles' | 'a11y' | 'activeElement'>;
+  /** Selectors past the cap were dropped — the answer must say `truncated: true`. */
+  readonly trimmed: boolean;
+  readonly droppedStyles: readonly string[];
+}
+
+/**
+ * The four `ui.inspect` fields, bounded HERE and not in the schema: `validate-args.ts` enforces
+ * no `maxItems`, and a bound the catalog cannot state is one the handler must apply and then
+ * confess to. Shared with `ui.interact`, whose `inspect` block is these same four fields.
+ */
+export function inspectSpecOf(args: ToolArgs): InspectSpecRead {
+  const wanted = strings(args['selectors']);
+  const selectors = wanted.slice(0, UI_INSPECT_LIMITS.selectors);
+  const named = strings(args['styles']);
+  const valid = named.filter((name) => STYLE_NAME.test(name));
+  const styles = valid.slice(0, UI_INSPECT_LIMITS.styles);
+  return {
+    spec: {
+      selectors,
+      styles,
+      a11y: args['a11y'] === true,
+      activeElement: args['activeElement'] !== false,
+    },
+    trimmed: wanted.length > selectors.length,
+    droppedStyles: named.filter((name) => !styles.includes(name)),
+  };
+}
+
+export const VIEWPORT_ARGS = {
+  viewport: {
+    type: 'string',
+    enum: Object.keys(UI_VIEWPORTS),
+    default: 'desktop',
+    description: 'phone 390×844, tablet 820×1180, desktop 1440×900.',
+  },
+  width: { type: 'integer', minimum: 320, maximum: 3840 },
+  height: { type: 'integer', minimum: 320, maximum: 2160 },
+  theme: {
+    type: 'string',
+    enum: ['light', 'dark'],
+    default: 'dark',
+    description:
+      'The theme the capture is of: prefers-color-scheme is emulated AND the scheme is stored as ' +
+      "the visitor's choice (localStorage, the boot's key) before navigation, so an app whose " +
+      'theme.defaultMode differs still captures what a visitor who chose this theme sees.',
+  },
+} as const;
+
+/**
+ * The four `ui.*` tools. The scopes are the dev server's `dev:test` and `dev:read`, passed in to
+ * keep this file a leaf; `ui.diff` is the one under `read` — it opens no browser.
+ */
+export function uiTools(host: UiHost, scopes: UiScopes): readonly AnyMcpTool[] {
+  const scope = scopes.test;
+  return [
+    {
+      name: 'ui.shot',
+      description:
+        'Photograph one route at a named viewport (phone/tablet/desktop) or an explicit size, ' +
+        'in light or dark, against the running dev server. Returns the PNG path and the same ' +
+        'verdict x shot writes: console, page errors, refused requests, whether every island ' +
+        'mounted. Refuses a route with no declared JS budget. Launches a browser.',
+      scope,
+      destructive: true,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          route: { type: 'string', description: 'Route path, e.g. /dashboard.' },
+          ...VIEWPORT_ARGS,
+          fullPage: { type: 'boolean', default: true },
+        },
+        required: ['route'],
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        const route = typeof args['route'] === 'string' ? args['route'] : '';
+        const result = await host.shotRoute({
+          route,
+          viewport: viewportOf(args),
+          colorScheme: args['theme'] === 'light' ? 'light' : 'dark',
+          fullPage: args['fullPage'] !== false,
+        });
+        return { ...jsonResult(result), ...(result.ok ? {} : { isError: true }) };
+      },
+    },
+    {
+      name: 'ui.island',
+      description:
+        'Photograph an island in every state its *.island.states.ts declares (or one state), ' +
+        'as x shot --island does: PNGs plus a verdict per state. Launches a browser.',
+      scope,
+      destructive: true,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          island: { type: 'string', description: 'Island name, e.g. links-table.' },
+          state: { type: 'string', description: 'One declared state id; omit for all.' },
+        },
+        required: ['island'],
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        const island = typeof args['island'] === 'string' ? args['island'] : '';
+        const state = typeof args['state'] === 'string' ? args['state'] : undefined;
+        const result = await host.shotIsland({ island, ...(state === undefined ? {} : { state }) });
+        return { ...jsonResult(result), ...(result.ok ? {} : { isError: true }) };
+      },
+    },
+    {
+      name: 'ui.inspect',
+      description:
+        'Read DOM, computed-style and accessibility facts for up to ' +
+        `${UI_INSPECT_LIMITS.selectors} selectors in ONE navigation of a route: per match the tag, ` +
+        'text, bounding box, visibility, attributes, the computed styles you name and (a11y: true) ' +
+        'the browser-computed role and name; plus the document title, data-theme, the focused ' +
+        'element, the island count, console and page errors. Takes the same PNG and verdict ' +
+        'ui.shot does; `ok` is the verdict. Refuses a route with no declared JS budget. Launches ' +
+        'a browser.',
+      scope,
+      destructive: true,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          route: { type: 'string', description: 'Route path, e.g. /dashboard.' },
+          ...VIEWPORT_ARGS,
+          selectors: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 },
+            description: `CSS selectors, at most ${UI_INSPECT_LIMITS.selectors}; extras are dropped and truncated: true says so.`,
+          },
+          styles: {
+            type: 'array',
+            items: { type: 'string' },
+            description: `Computed property names (kebab-case), at most ${UI_INSPECT_LIMITS.styles}; invalid names land in droppedStyles.`,
+          },
+          a11y: {
+            type: 'boolean',
+            default: false,
+            description: 'Read the computed role and name per match (one round trip per selector).',
+          },
+          activeElement: { type: 'boolean', default: true },
+        },
+        required: ['route', 'selectors'],
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        const route = typeof args['route'] === 'string' ? args['route'] : '';
+        const asked = inspectSpecOf(args);
+        const result = await host.inspectRoute({
+          route,
+          viewport: viewportOf(args),
+          colorScheme: args['theme'] === 'light' ? 'light' : 'dark',
+          ...asked.spec,
+        });
+        const answer: UiInspectResult = {
+          ...result,
+          truncated: result.truncated || asked.trimmed,
+          droppedStyles: asked.droppedStyles,
+        };
+        return { ...jsonResult(answer), ...(answer.ok ? {} : { isError: true }) };
+      },
+    },
+    {
+      name: 'ui.diff',
+      description:
+        'Compare two PNGs the other ui.* tools wrote (paths relative to the app root, under ' +
+        '.x/shot/ only — anything else is refused) pixel by pixel: the changed-pixel count and ' +
+        'percentage, the bounding box of the change, and the path of a diff PNG (after faded to ' +
+        'a quarter, changed pixels solid red). A pixel is changed when any channel moved by more ' +
+        'than threshold × 255; no anti-alias detection. Refuses two sizes. Launches no browser.',
+      scope: scopes.read,
+      destructive: false,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          before: {
+            type: 'string',
+            description: 'Path under .x/shot/, e.g. .x/shot/dashboard/1440x900-dark/page.png.',
+          },
+          after: { type: 'string', description: 'Path under .x/shot/ of the later capture.' },
+          threshold: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            default: UI_DIFF_DEFAULT_THRESHOLD,
+            description:
+              'Per-channel delta as a fraction of 255 above which a pixel counts as changed.',
+          },
+          out: {
+            type: 'string',
+            description: 'Where to write the diff PNG (under .x/shot/); default beside `after`.',
+          },
+        },
+        required: ['before', 'after'],
+        additionalProperties: false,
+      },
+      async handle(args: ToolArgs) {
+        const before = typeof args['before'] === 'string' ? args['before'] : '';
+        const after = typeof args['after'] === 'string' ? args['after'] : '';
+        const threshold =
+          typeof args['threshold'] === 'number' ? args['threshold'] : UI_DIFF_DEFAULT_THRESHOLD;
+        const out = typeof args['out'] === 'string' ? args['out'] : undefined;
+        const result = await host.diffShots({
+          before,
+          after,
+          threshold,
+          ...(out === undefined ? {} : { out }),
+        });
+        return jsonResult(result);
+      },
+    },
+  ];
+}

package/src/index.ts

@@ -26,15 +26,42 @@ export type {
   QueueDepth,
   TestRun,
   UiColorScheme,
+  UiDiffInput,
+  UiDiffResult,
+  UiInspectActive,
+  UiInspectBox,
+  UiInspectInput,
+  UiInspectIslands,
+  UiInspectMatch,
+  UiInspectResult,
+  UiInspectSelector,
+  UiInspectSpec,
+  UiInteractInput,
+  UiInteractInspect,
+  UiInteractResult,
+  UiInteractStep,
+  UiInteractStepKind,
+  UiInteractStepResult,
   UiIslandInput,
   UiIslandResult,
+  UiScopes,
   UiShotInput,
   UiShotResult,
   UiViewportName,
   VerifyResult,
   VerifyStep,
 } from './dev-server';
-export { DEV_SCOPES, devTools, UI_VIEWPORTS, viewportOf } from './dev-server';
+export {
+  DEV_SCOPES,
+  devTools,
+  STYLE_NAME,
+  UI_DIFF_DEFAULT_THRESHOLD,
+  UI_INSPECT_LIMITS,
+  UI_INTERACT_LIMITS,
+  UI_INTERACT_STEP_SCHEMA,
+  UI_VIEWPORTS,
+  viewportOf,
+} from './dev-server';
 export type { McpErrorCode } from './errors';
 export {
   MCP_ERROR_CODES,