@ultimat3/cli 20.1.6 → 20.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "20.1.6",
+  "version": "20.2.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "20.1.6",
-    "@ultimat3/admin": "20.1.6",
-    "@ultimat3/ai": "20.1.6",
-    "@ultimat3/auth": "20.1.6",
-    "@ultimat3/cache": "20.1.6",
-    "@ultimat3/core": "20.1.6",
-    "@ultimat3/db": "20.1.6",
-    "@ultimat3/entity": "20.1.6",
-    "@ultimat3/flags": "20.1.6",
-    "@ultimat3/http": "20.1.6",
-    "@ultimat3/i18n": "20.1.6",
-    "@ultimat3/jobs": "20.1.6",
-    "@ultimat3/mail": "20.1.6",
-    "@ultimat3/manifest": "20.1.6",
-    "@ultimat3/mcp": "20.1.6",
-    "@ultimat3/money": "20.1.6",
-    "@ultimat3/notify": "20.1.6",
-    "@ultimat3/policy": "20.1.6",
-    "@ultimat3/pwa": "20.1.6",
-    "@ultimat3/query": "20.1.6",
-    "@ultimat3/realtime": "20.1.6",
-    "@ultimat3/render": "20.1.6",
-    "@ultimat3/schema": "20.1.6",
-    "@ultimat3/scraping": "20.1.6",
-    "@ultimat3/seo": "20.1.6",
-    "@ultimat3/storage": "20.1.6",
-    "@ultimat3/testing": "20.1.6",
-    "@ultimat3/time": "20.1.6",
+    "@ultimat3/action": "20.2.0",
+    "@ultimat3/admin": "20.2.0",
+    "@ultimat3/ai": "20.2.0",
+    "@ultimat3/auth": "20.2.0",
+    "@ultimat3/cache": "20.2.0",
+    "@ultimat3/core": "20.2.0",
+    "@ultimat3/db": "20.2.0",
+    "@ultimat3/entity": "20.2.0",
+    "@ultimat3/flags": "20.2.0",
+    "@ultimat3/http": "20.2.0",
+    "@ultimat3/i18n": "20.2.0",
+    "@ultimat3/jobs": "20.2.0",
+    "@ultimat3/mail": "20.2.0",
+    "@ultimat3/manifest": "20.2.0",
+    "@ultimat3/mcp": "20.2.0",
+    "@ultimat3/money": "20.2.0",
+    "@ultimat3/notify": "20.2.0",
+    "@ultimat3/policy": "20.2.0",
+    "@ultimat3/pwa": "20.2.0",
+    "@ultimat3/query": "20.2.0",
+    "@ultimat3/realtime": "20.2.0",
+    "@ultimat3/render": "20.2.0",
+    "@ultimat3/schema": "20.2.0",
+    "@ultimat3/scraping": "20.2.0",
+    "@ultimat3/seo": "20.2.0",
+    "@ultimat3/storage": "20.2.0",
+    "@ultimat3/testing": "20.2.0",
+    "@ultimat3/time": "20.2.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/budgets.ts

@@ -10,7 +10,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
-import { formatBytes, parseByteBudget } from '@ultimat3/render';
+import { formatBytes, parseByteBudget, themeScriptBody } from '@ultimat3/render';
 import type { Finding } from './output';
 import type { UnmeasuredRoute } from './static-report';
 import { SW_REGISTER_PATH } from './sw-artifacts';
@@ -253,6 +253,18 @@ export interface MeasuredJs {
  */
 export const FRAMEWORK_SCRIPTS: ReadonlySet<string> = new Set([SW_REGISTER_PATH]);
 
+/**
+ * The inline bodies the boot puts in EVERY document, keyed by the same argument as
+ * `FRAMEWORK_SCRIPTS`: the author cannot edit, delete or move them, so charging one against a
+ * `0kb` budget is a finding nobody can act on. Today that is the no-flash theme script, in each
+ * of its three fallbacks (`theme-boot.ts` uses `themeScript`'s defaults for everything else, so
+ * these are the exact strings a document carries). The hydration runtime is NOT here — it exists
+ * only when the page ships an island, and is the cost of the app's own interactivity.
+ */
+export const FRAMEWORK_INLINE_SCRIPTS: ReadonlySet<string> = new Set(
+  (['light', 'dark', 'system'] as const).map((fallback) => themeScriptBody({ fallback })),
+);
+
 /**
  * What a rendered document actually makes the browser execute: the bytes of every inline script
  * the parser will run, the size of every file a `src` points at, and the size of every island
@@ -301,7 +313,10 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     if (carriesJson(attrs)) continue;
     const src = SRC_ATTR.exec(attrs)?.groups?.['src'];
     if (src === undefined) {
-      jsBytes += Buffer.byteLength(match.groups?.['body'] ?? '', 'utf8');
+      const body = match.groups?.['body'] ?? '';
+      const bytes = Buffer.byteLength(body, 'utf8');
+      if (FRAMEWORK_INLINE_SCRIPTS.has(body)) frameworkBytes += bytes;
+      else jsBytes += bytes;
       continue;
     }
     await weigh(src);

package/src/cmd-dev.ts

@@ -40,6 +40,7 @@ import { describeServices, reportedUrls, resolveServices } from './dev-services'
 import { storageRoutes } from './dev-storage';
 import { createTraceRecorder } from './dev-traces';
 import { watchTree } from './dev-watch-tree';
+import { errorPageStyleSources } from './error-page-csp';
 import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { IslandBundle } from './island-bundle';
@@ -59,6 +60,7 @@ import { styleBundle } from './style-bundle';
 import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
+import { loadThemeMode, themeBoot } from './theme-boot';
 
 const DEFAULT_PORT = 3000;
 
@@ -187,6 +189,8 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // name it. `undefined` for an app that is not installable, and then nothing is mounted and no
   // document changes — the 0kb baseline is not spent on a `<link>` to a file that does not exist.
   const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
+  const errorStyles = await errorPageStyleSources(options.root);
   // Built once at boot, from this process's own route table and island bundle. `x dev` rebuilds
   // islands on the watcher tick and the worker is NOT rebuilt with them, deliberately: a service
   // worker that changes under a page it already controls is the update path, and re-emitting one
@@ -241,6 +245,7 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     ...appRoutes({
       buildId,
       resolveIsland: (file) => state.islands.resolverFor(file),
+      themeHead: theme.head,
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
     }),
   ];
@@ -264,23 +269,17 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     runtime,
     routes,
     env: options.env,
-    // Read from `app.config.ts` rather than threaded through `DevOptions`: it is the app's own
-    // declaration, and `x dev` and `serve.ts` must not be able to disagree about where the app's
-    // sign-in page is.
+    // Read from `app.config.ts` rather than threaded through `DevOptions`: `x dev` and `serve.ts`
+    // must not be able to disagree about where the app's sign-in page is.
     signInPath: await loadSignInPath(options.root),
-    // The same seam `serve.ts` passes: the app's own error page is a FILE, so the root is what
-    // `startWeb` needs to find one.
+    // The same seam `serve.ts` passes: the app's own error page is a FILE under this root.
     root: options.root,
-    // The documents this process serves that the app did not write — the `/_x` shell and the
-    // screenshot harness's frame. The app's OWN surfaces need no entry any more: their CSS is a
-    // content-hashed file `'self'` already admits (`style-bundle.ts`). `x dev` sends the policy
-    // report-only, so an uncovered `<style>` here is a console report rather than a blank page —
-    // which is how this reached production.
-    inlineStyles: [await devShellStyle(), FRAME_STYLE],
-    // The fourth surface, and the only one an author sees without leaving the page they broke:
-    // the overlay renders this request's own loops under the error it is already showing.
-    // `serve.ts` boots through the same `startRoles` and passes nothing, so production has no
-    // diagnostic to call.
+    // The `/_x` shell, the harness's frame, and the app's own error pages — the inline bodies this
+    // process serves; the app's surfaces are content-hashed files `'self'` admits.
+    inlineStyles: [await devShellStyle(), FRAME_STYLE, ...errorStyles],
+    inlineScripts: [theme.cspSource],
+    // The overlay renders this request's own loops under the error it is already showing.
+    // `serve.ts` boots through the same `startRoles` and passes nothing (axiom 6).
     devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
       statements.repeatsFor(asCtx(ctx)).map(loopFacts).map(loopNotice),
     // The read-replica scope, opened per request. Absent for every app that names no

package/src/cmd-mcp.ts

@@ -1,4 +1,4 @@
-// `x mcp serve` — the framework's dev MCP server over stdio or HTTP. The 15 tools, the JSON-RPC
+// `x mcp serve` — the framework's dev MCP server over stdio or HTTP. The 18 tools, the JSON-RPC
 // dispatch, both transports and the structural SQL refusals all come from `@ultimat3/mcp`; the CLI
 // supplies only the app, the caller and the socket. A tool answered here would be a second answer
 // to a question the framework already answers.
@@ -117,7 +117,7 @@ export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
  * What the session reports when it is over — on STDERR, which is the half this file's header
  * claimed and did not have. `dispatch` renders a `CommandResult` only after `run` resolves, and
  * this resolves when the peer closes stdin, so nothing lands mid-session; but fd 1 under this
- * transport carries JSON-RPC frames, and `✓ mcp stdio serving 15 tools` arriving on it after the
+ * transport carries JSON-RPC frames, and `✓ mcp stdio serving 18 tools` arriving on it after the
  * loop is a malformed frame to a peer still draining, and a second document under `--json`.
  *
  * Its own function so the addressing is testable without a live peer: `serveStdio` resolves only

package/src/cmd-shot.ts

@@ -8,7 +8,7 @@
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
-import type { ColorScheme, ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
+import type { ColorScheme, ScrapeDriver, ScrapePage, ScrapeSession } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
@@ -197,6 +197,15 @@ export interface ShotRun {
    */
   readonly colorScheme?: ColorScheme | undefined;
   readonly now?: (() => Date) | undefined;
+  /**
+   * Something to do with the page AFTER the islands settled and BEFORE the picture — `ui.inspect`
+   * reads the DOM here, on the one navigation the picture already paid for. `settle` re-runs the
+   * island poll (an action that mounts something changes the count the verdict reports); the
+   * caller who never calls it gets the count from the first settle.
+   */
+  readonly act?:
+    | ((page: ScrapePage, settle: () => Promise<IslandCount | null>) => Promise<void>)
+    | undefined;
 }
 
 /** Nothing here may replace the failure that caused it, so a teardown throw is swallowed. */
@@ -239,10 +248,15 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
     // The same budget again, and deliberately no new flag: `settleMs` is the deadline at which the
     // runtime CALLS `import()`, so a mount gets exactly as long to settle as the runtime got to
     // start it — and `--settle 0`, which asks for no wait, still gets none.
-    const islands = await settleIslands(probe, {
-      windowMs: options.settleMs,
-      pollMs: SETTLE_POLL_MS,
-    });
+    const settle = (): Promise<IslandCount | null> =>
+      settleIslands(probe, { windowMs: options.settleMs, pollMs: SETTLE_POLL_MS });
+    let islands = await settle();
+    if (options.act !== undefined) {
+      await options.act(page, async () => {
+        islands = await settle();
+        return islands;
+      });
+    }
     const bytes = await page.screenshot({ fullPage: options.fullPage });
     // Read AFTER the capture, so an error logged while the page settled is in the verdict that
     // ships with the picture it explains.

package/src/dev-render.ts

@@ -65,6 +65,12 @@ export interface DocumentOptions {
    * boot knows it, the renderer cannot ask.
    */
   readonly pwaHead?: string;
+  /**
+   * The no-flash theme `<script>` from `theme-boot.ts`, or absent for a caller that renders no
+   * documents a browser paints. Document-level for `pwaHead`'s reason — the same tag on every page,
+   * decided by `app.config.ts`, which the boot read and the renderer cannot.
+   */
+  readonly themeHead?: string;
 }
 
 export interface DevRenderOptions extends DocumentOptions {
@@ -99,7 +105,9 @@ const headFor = async (
       await entry.config.meta(metaContextFor(ctx, data)),
       seoRenderers({ path: new URL(ctx.url).pathname }),
     ),
-  ) + (options.pwaHead ?? '');
+  ) +
+  (options.themeHead ?? '') +
+  (options.pwaHead ?? '');
 
 /**
  * `<link rel="stylesheet">` for the surface's own stylesheets, or nothing at all when the surface

package/src/dev-roles.ts

@@ -100,6 +100,8 @@ export interface StartRolesOptions {
    * serves: that policy is what rendered every deployed app completely unstyled.
    */
   readonly inlineStyles?: readonly string[];
+  /** `script-src` sources beyond the hydration runtime's — the theme boot's hash. */
+  readonly inlineScripts?: readonly string[];
   /**
    * Non-fatal findings the browser overlay shows next to an error, for the request being answered.
    * Only `x dev` supplies one — `serve.ts` boots through this same function and omits it, so a
@@ -321,16 +323,14 @@ function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): S
         rateLimit: { scope: store?.scope ?? 'process' },
         // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
         // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
-        // function of that body. Read after `loadApp` — importing the app IS what registered them.
-        // BOTH directives, and the script half is the one that was missing: the hydration runtime
-        // is emitted inline in every document that carries an island, so `script-src 'self'` meant
-        // no island booted anywhere the policy is enforced — which is every container, and never
-        // `x dev`, where it is report-only.
+        // function of that body. BOTH directives: the hydration runtime is emitted inline in every
+        // document that carries an island, so `script-src 'self'` meant no island booted anywhere
+        // the policy is enforced — every container, and never `x dev`, where it is report-only.
         security: {
           csp: {
             extend: {
               'style-src': inlineStyleSources(options.inlineStyles ?? []),
-              'script-src': inlineScriptSources(),
+              'script-src': inlineScriptSources(options.inlineScripts ?? []),
             },
           },
         },

package/src/error-codes.ts

@@ -157,6 +157,17 @@ export const CLI_OWNED_ERROR_CODES = [
   // `ui.shot` (the dev MCP server): a route it will not photograph, and why.
   'X_UI_SHOT_ROUTE_UNKNOWN',
   'X_UI_SHOT_ROUTE_UNBUDGETED',
+  // `ui.interact`: the four ways a step list is refused. All four REFUSE rather than trim or skip
+  // — a step dropped, a keystroke swallowed or a navigation followed changes what the picture is of.
+  'X_UI_INTERACT_STEPS_INVALID',
+  'X_UI_INTERACT_SECRET_FIELD',
+  'X_UI_INTERACT_LEFT_APP',
+  'X_UI_INTERACT_STEP_FAILED',
+  // `ui.diff`: the three ways two captures fail to become a comparison. The path gate is what
+  // lets a file-reading tool sit under `dev:read` — it reads `.x/shot/` and nothing else.
+  'X_UI_DIFF_PATH_OUTSIDE',
+  'X_UI_DIFF_FILE_MISSING',
+  'X_UI_DIFF_SIZE_MISMATCH',
   // `x shot --island` — one code per way a component's named state fails to become a picture.
   // The last of the four is the one that gates: it is checked against the expansion computed
   // before a browser existed, so a capture loop that swallowed a failure cannot exit 0.
@@ -300,8 +311,15 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
   X_PACKAGE_DUPLICATED: 'two copies of one registry-holding framework package are installed',
   X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
-  X_UI_SHOT_ROUTE_UNKNOWN: 'ui.shot was asked for a path no route answers',
-  X_UI_SHOT_ROUTE_UNBUDGETED: 'ui.shot refused a route that declares no budget.js',
+  X_UI_SHOT_ROUTE_UNKNOWN: 'a ui.* tool was asked for a path no route answers',
+  X_UI_SHOT_ROUTE_UNBUDGETED: 'a ui.* tool refused a route that declares no budget.js',
+  X_UI_INTERACT_STEPS_INVALID: 'a ui.interact step list is over its bounds or malformed',
+  X_UI_INTERACT_SECRET_FIELD: 'ui.interact refused to type into a password field',
+  X_UI_INTERACT_LEFT_APP: 'a ui.interact step navigated off the dev server origin',
+  X_UI_INTERACT_STEP_FAILED: 'a ui.interact step raised a scraping error',
+  X_UI_DIFF_PATH_OUTSIDE: 'ui.diff was handed a path that does not resolve inside .x/shot/',
+  X_UI_DIFF_FILE_MISSING: 'ui.diff was handed a capture that is not on disk',
+  X_UI_DIFF_SIZE_MISMATCH: 'ui.diff was handed two captures of different sizes',
   X_SHOT_ISLAND_STATES_EMPTY: 'an island states file declares no manifest',
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
   X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',

package/src/error-page-csp.ts

@@ -0,0 +1,50 @@
+// The `style-src` sources that admit an app's own error pages. `error-pages.ts` serves
+// `apps/web/site/errors/<status>.html` verbatim, and such a page is a self-contained document —
+// it carries its own `<style>`, because the app's stylesheet bundle is not linked from it. Under
+// the enforced policy a container sends, `style-src 'self' <overlay hash>` blocked that block and
+// the page rendered unstyled; `x dev` sends the policy report-only, so the same page looked fine
+// on every author's machine. Hashed at boot, like the hydration runtime: a hash is a function of
+// the body, and these files do not change while a container runs.
+
+// why: Bun exposes no path-join primitive, and the directory is app-root-relative — the same
+// necessity `error-pages.ts` records.
+import { join } from 'node:path';
+import { cspHashSource } from '@ultimat3/http';
+import { ERROR_PAGE_DIR } from './error-pages';
+
+/**
+ * `<style>` bodies, in document order, exactly as the browser will hash them: the text between
+ * the tags, untrimmed. A trimmed body hashes to a different value and admits nothing.
+ */
+export function inlineStyleBodies(html: string): readonly string[] {
+  const bodies: string[] = [];
+  const pattern = /<style(?:\s[^>]*)?>([\s\S]*?)<\/style>/gi;
+  for (let match = pattern.exec(html); match !== null; match = pattern.exec(html)) {
+    bodies.push(match[1] ?? '');
+  }
+  return bodies;
+}
+
+/**
+ * One hash per distinct `<style>` body across every error page the app ships. Read once at boot:
+ * a page an author drops in while `x dev` runs is served (the reader is per request) but not yet
+ * admitted, which the report-only policy there turns into a console report, not a blank page.
+ */
+export async function errorPageStyleSources(root: string): Promise<readonly string[]> {
+  const dir = join(root, ERROR_PAGE_DIR);
+  const sources = new Set<string>();
+  for (const name of await htmlFilesIn(dir)) {
+    const html = await Bun.file(join(dir, name)).text();
+    for (const body of inlineStyleBodies(html)) sources.add(cspHashSource(body));
+  }
+  return [...sources].sort();
+}
+
+/** `Bun.Glob.scan` throws `ENOENT` on a missing directory, and no error pages is the common case. */
+async function htmlFilesIn(dir: string): Promise<readonly string[]> {
+  try {
+    return (await Array.fromAsync(new Bun.Glob('*.html').scan({ cwd: dir }))).sort();
+  } catch {
+    return [];
+  }
+}

package/src/mcp-errors.ts

@@ -55,9 +55,28 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_PACKAGE_DUPLICATED:
     'x i18n check --json   # the finding names both copies and the package.json to pin',
   X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
-  X_UI_SHOT_ROUTE_UNKNOWN: 'x routes --json   # then ui.shot with one of its path values',
+  X_UI_SHOT_ROUTE_UNKNOWN:
+    'x routes --json   # then call the ui.* tool with one of its path values',
   X_UI_SHOT_ROUTE_UNBUDGETED:
     "x build --target static --json && x verify --only budgets --json   # after declaring budget: { js: '<n>kb' } in the route file",
+  // The four `ui.interact` refusals. None can be repaired by a command — each is a change to the
+  // step list the agent sends — so each names the command that SHOWS what a valid resend needs.
+  X_UI_INTERACT_STEPS_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',
+  X_UI_INTERACT_SECRET_FIELD:
+    'x shot --all-islands --json   # or --island <name>: a declared state renders the filled form without the secret ever being typed',
+  X_UI_INTERACT_LEFT_APP:
+    'x routes --json   # then resend ui.interact with steps that stay on one of its paths',
+  X_UI_INTERACT_STEP_FAILED:
+    'x routes --json   # then run ui.inspect on the route first and copy a selector it reports with count >= 1',
+  // The three `ui.diff` codes. Every capture it can compare was written by `x shot` or a `ui.*`
+  // tool under `.x/shot/`, so the runnable half is the command that writes one there.
+  X_UI_DIFF_PATH_OUTSIDE:
+    'x shot / --json   # then pass the image path it answers, relative to the app root: ui.diff reads .x/shot/ and nothing else',
+  X_UI_DIFF_FILE_MISSING:
+    'x shot / --json   # then diff the image path it answers; a capture ui.shot wrote is listed in its own answer',
+  X_UI_DIFF_SIZE_MISMATCH:
+    'x shot / --json   # photograph both captures at one viewport with one fullPage setting, then diff those two',
   // The four island-capture codes. Each one's real repair is an edit to the app's own states file
   // or component, which no command can perform — so each names the command that REPRODUCES it with
   // the file and the reason attached, which is the runnable half.

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