@ultimat3/cli 5.0.1 → 7.0.0

package/src/shot-verdict.ts

@@ -0,0 +1,337 @@
+// What a shot CLAIMS, and what it refuses to claim: the verdict `x shot` writes beside the
+// picture, built from plain values so every rule here is testable with no browser, no dev server
+// and no `ParsedArgs` — the `cmd-jobs.ts` / `jobs-report.ts` split, repeated.
+
+import { probeImage } from '@ultimat3/core';
+import { ISLAND_FAILED_ATTRIBUTE, ISLAND_MOUNTED_ATTRIBUTE } from '@ultimat3/render';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { t, validate } from '@ultimat3/schema';
+import type { ConsoleLine, NetworkEntry, PageError } from '@ultimat3/scraping';
+import { msg } from './messages';
+import type { JsonValue } from './output';
+
+/**
+ * The one expression that counts islands, and it counts TWO different facts because they are two
+ * different facts. `data-x-island` is emitted by `emitIslandAttributes` for every island on the
+ * page including `hydrate: 'never'`, so its presence means "the server rendered an island here"
+ * and nothing about the client. `el.__x` is the boot promise `hydrateRuntime`'s prelude assigns
+ * (`el.__x=import(e).then(…)`), so it means "the runtime asked for this island's chunk" — still
+ * not "mount() resolved", which nothing in the DOM records today.
+ *
+ * An expression, never a closure: `CdpPageLike.evaluate` takes the string form only.
+ */
+/** Every key this command renders. `msg()` answers `⟦key⟧` for a miss, which no build can see. */
+export const SHOT_MESSAGE_KEYS = [
+  'cli.shot.ok',
+  'cli.shot.errors',
+  'cli.shot.redirected',
+  'cli.shot.picture',
+  'cli.shot.verdict',
+  'cli.shot.server.booted',
+  'cli.shot.server.reused',
+  'cli.shot.canvas',
+  'cli.shot.canvasUnreadable',
+  'cli.shot.islands',
+  'cli.shot.islandsUnknown',
+  'cli.shot.network',
+  'cli.shot.console',
+  'cli.shot.threw',
+  'cli.shot.pageError',
+  'cli.shot.blind.status',
+] as const;
+
+/**
+ * Four facts, not one, because they are genuinely different and conflating them is what makes a
+ * screenshot tool lie. `declared` is server-rendered and says nothing about the client.
+ * `booted` means the runtime CALLED `import()` — set before `mount()` settles, and legitimately
+ * absent for a `visible` or `interaction` island nothing has scrolled to or clicked. `mounted` and
+ * `failed` are the outcome, marked by the prelude itself when the mount promise settles.
+ *
+ * The attribute names are INTERPOLATED from `@ultimat3/render`'s own exports rather than typed
+ * here: this probe and the runtime that writes the markers have to agree, and a second spelling of
+ * `data-x-mounted` would read as "no island mounted" — a clean-looking answer that is wrong.
+ */
+export const ISLAND_PROBE =
+  '(function(){var els=document.querySelectorAll("[data-x-island]");var by={};var booted=0;' +
+  'var mounted=0;var failed=0;var failures=[];' +
+  'for(var i=0;i<els.length;i+=1){var el=els[i];' +
+  'var s=el.getAttribute("data-x-hydrate")||"unknown";by[s]=(by[s]||0)+1;' +
+  'if(el.__x!==undefined)booted+=1;' +
+  `if(el.hasAttribute("${ISLAND_MOUNTED_ATTRIBUTE}"))mounted+=1;` +
+  `if(el.hasAttribute("${ISLAND_FAILED_ATTRIBUTE}")){failed+=1;failures.push({` +
+  'island:el.getAttribute("data-x-island")||"",' +
+  `message:el.getAttribute("${ISLAND_FAILED_ATTRIBUTE}")||''});}}` +
+  'return{declared:els.length,booted:booted,mounted:mounted,failed:failed,' +
+  'byStrategy:by,failures:failures};})()';
+
+export interface IslandCount {
+  /** `[data-x-island]` in the served DOM — server-rendered, whatever the client then did. */
+  readonly declared: number;
+  /** Islands whose chunk the hydration runtime asked for. See `ISLAND_PROBE` for the distance. */
+  readonly booted: number;
+  /** Islands whose `mount()` RESOLVED. This is the one that answers "does the page work". */
+  readonly mounted: number;
+  /** Islands whose `mount()` REJECTED — the case a picture can never show. */
+  readonly failed: number;
+  /** `data-x-hydrate` value → count, so a `never` island is never read as a failure to boot. */
+  readonly byStrategy: Readonly<Record<string, number>>;
+  /** Which island threw, and what it said. Empty when `failed` is 0. */
+  readonly failures: readonly IslandFailure[];
+}
+
+export interface IslandFailure {
+  readonly island: string;
+  readonly message: string;
+}
+
+const islandProbeSchema: StandardSchemaV1<unknown, IslandCount> = t.object({
+  declared: t.number,
+  booted: t.number,
+  mounted: t.number,
+  failed: t.number,
+  byStrategy: t.record(t.number),
+  failures: t.array(t.object({ island: t.string, message: t.string })),
+}) as unknown as StandardSchemaV1<unknown, IslandCount>;
+
+/**
+ * `evaluate()` answers `unknown` on every driver — a page can return anything at all — so the
+ * probe's result is PARSED and never cast. `null` for anything that does not fit, because a
+ * malformed probe must not be able to take a capture down after the picture was already taken.
+ */
+export function parseIslandProbe(value: unknown): IslandCount | null {
+  const result = validate(islandProbeSchema, value);
+  return result.issues === undefined ? result.value : null;
+}
+
+export interface ShotCanvas {
+  readonly width: number;
+  readonly height: number;
+  readonly format: string;
+}
+
+/**
+ * The picture's own pixel size, read from the header bytes by `@ultimat3/core`'s one image probe —
+ * never a viewport number the tool asked for and cannot prove it got. `null` when the bytes are
+ * not a decodable image, which is a fact worth reporting rather than an exception worth throwing:
+ * the offline drivers answer a PNG signature with no IHDR behind it.
+ */
+export function canvasOf(bytes: Uint8Array): ShotCanvas | null {
+  try {
+    const info = probeImage(bytes);
+    return { width: info.width, height: info.height, format: info.format };
+  } catch {
+    return null;
+  }
+}
+
+export interface ShotInput {
+  readonly route: string;
+  readonly requestedUrl: string;
+  readonly finalUrl: string;
+  readonly server: 'booted' | 'reused';
+  readonly capturedAt: string;
+  /** The picture's filename, beside the verdict — a sibling, so the pair moves as one directory. */
+  readonly screenshot: string;
+  readonly bytes: Uint8Array;
+  readonly console: readonly ConsoleLine[];
+  /**
+   * Uncaught exceptions, which are NOT console lines: a throw calls no console method, so a page
+   * whose island exploded can have `console: []`. This is the field the whole command was for —
+   * "a picture cannot tell you the island threw".
+   */
+  readonly pageErrors: readonly PageError[];
+  /** Page errors the ring evicted, so `pageErrors.length` reads as a floor and not a total. */
+  readonly pageErrorsDropped: number;
+  readonly network: readonly NetworkEntry[];
+  readonly networkDropped: number;
+  /** `null` when the probe could not run or did not parse. Never a zero standing in for unknown. */
+  readonly islands: IslandCount | null;
+}
+
+export interface ShotVerdict extends ShotInput {
+  readonly ok: boolean;
+  /** The route asked for is not the document photographed. An `auth: 'required'` route's default. */
+  readonly redirected: boolean;
+  readonly errors: number;
+  readonly warnings: number;
+  readonly canvas: ShotCanvas | null;
+  readonly refused: number;
+  /** What this verdict cannot see, stated every time — a `0` whose blind spots are named. */
+  readonly blind: readonly string[];
+}
+
+/**
+ * What a shot is blind to, each naming the mechanism rather than apologising. Constant because
+ * these are properties of the browser port, not of a run — and in the artifact because `errors: 0`
+ * read without them is a claim the tool cannot support.
+ *
+ * It was three. `pageErrors` and `hydration` both left on 2026-08-21, when `@ultimat3/scraping`
+ * learned to capture `pageerror` and the hydration prelude learned to mark a mount's outcome. A
+ * blind spot is worth stating while it is true and worth DELETING the moment it is not: a stale
+ * one teaches an agent to distrust an answer the tool can now give.
+ */
+export const BLIND_SPOTS = ['cli.shot.blind.status'] as const;
+
+const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']): number =>
+  lines.filter((line) => line.level === level).length;
+
+/**
+ * `ok` is three conditions, and every one is something a picture cannot show: nothing on the page
+ * logged an error, nothing THREW, and the document photographed is the route that was asked for.
+ *
+ * The throw is its own clause rather than folded into `errors` because an uncaught exception calls
+ * no console method — a page whose island died can log nothing at all, and `errors === 0` would
+ * then pass it. A redirect is a failure of the CAPTURE rather than of the app: an agent that
+ * photographs the sign-in page and files "the island did not mount" is the outcome this prevents.
+ */
+export function buildVerdict(input: ShotInput): ShotVerdict {
+  const errors = levelCount(input.console, 'error');
+  return {
+    ...input,
+    ok: errors === 0 && input.pageErrors.length === 0 && input.requestedUrl === input.finalUrl,
+    redirected: input.requestedUrl !== input.finalUrl,
+    errors,
+    warnings: levelCount(input.console, 'warn'),
+    canvas: canvasOf(input.bytes),
+    refused: input.network.filter((entry) => entry.refused !== undefined).length,
+    blind: BLIND_SPOTS.map((key) => msg(key)),
+  };
+}
+
+const consoleJson = (lines: readonly ConsoleLine[]): JsonValue =>
+  lines.map((line) => ({ level: line.level, text: line.text, at: line.at }));
+
+const islandJson = (islands: IslandCount | null): JsonValue =>
+  islands === null
+    ? null
+    : {
+        declared: islands.declared,
+        booted: islands.booted,
+        mounted: islands.mounted,
+        failed: islands.failed,
+        byStrategy: islands.byStrategy,
+        failures: islands.failures.map((failure) => ({
+          island: failure.island,
+          message: failure.message,
+        })),
+      };
+
+/** The artifact, and the same object `--json` carries under `data.verdict`. One shape, two files. */
+export function verdictJson(verdict: ShotVerdict): JsonValue {
+  return {
+    ok: verdict.ok,
+    route: verdict.route,
+    requestedUrl: verdict.requestedUrl,
+    finalUrl: verdict.finalUrl,
+    redirected: verdict.redirected,
+    server: verdict.server,
+    capturedAt: verdict.capturedAt,
+    screenshot: verdict.screenshot,
+    bytes: verdict.bytes.byteLength,
+    canvas:
+      verdict.canvas === null
+        ? null
+        : {
+            width: verdict.canvas.width,
+            height: verdict.canvas.height,
+            format: verdict.canvas.format,
+          },
+    console: {
+      total: verdict.console.length,
+      errors: verdict.errors,
+      warnings: verdict.warnings,
+      lines: consoleJson(verdict.console),
+    },
+    // Its own object, never merged into `console`: an uncaught exception calls no console method,
+    // and a reader who finds throws under `console` will look for them in the wrong stream.
+    pageErrors: {
+      total: verdict.pageErrors.length,
+      dropped: verdict.pageErrorsDropped,
+      thrown: verdict.pageErrors.map((error) => ({
+        message: error.message,
+        stack: error.stack ?? null,
+        at: error.at,
+      })),
+    },
+    islands: islandJson(verdict.islands),
+    network: {
+      requests: verdict.network.length,
+      refused: verdict.refused,
+      dropped: verdict.networkDropped,
+    },
+    blind: [...verdict.blind],
+  };
+}
+
+export interface ShotArtifacts {
+  readonly verdict: ShotVerdict;
+  /** Absolute path of the picture. */
+  readonly image: string;
+  /** Absolute path of this verdict on disk. */
+  readonly verdictFile: string;
+}
+
+const consoleLines = (verdict: ShotVerdict): readonly string[] =>
+  verdict.console
+    .filter((line) => line.level === 'error' || line.level === 'warn')
+    .map((line) => msg('cli.shot.console', { level: line.level, text: line.text.slice(0, 200) }));
+
+/** Human lines. Every fact here is a fact `--json` carries under `data.verdict`. */
+export function shotLines(artifacts: ShotArtifacts): readonly string[] {
+  const verdict = artifacts.verdict;
+  const islands = verdict.islands;
+  const canvas = verdict.canvas;
+  return [
+    msg(`cli.shot.server.${verdict.server}`, { url: verdict.finalUrl }),
+    canvas === null
+      ? msg('cli.shot.canvasUnreadable', { bytes: verdict.bytes.byteLength })
+      : msg('cli.shot.canvas', { width: canvas.width, height: canvas.height }),
+    islands === null
+      ? msg('cli.shot.islandsUnknown')
+      : msg('cli.shot.islands', {
+          booted: islands.mounted,
+          declared: islands.declared,
+          strategies: Object.entries(islands.byStrategy)
+            .map(([name, count]) => `${name}=${count}`)
+            .join(' '),
+        }),
+    msg('cli.shot.network', {
+      requests: verdict.network.length,
+      refused: verdict.refused,
+      dropped: verdict.networkDropped,
+    }),
+    ...verdict.pageErrors.map((error) =>
+      msg('cli.shot.pageError', {
+        message: error.message,
+        // The frame that names the island module and line. `message` alone says what went wrong
+        // and never where, which is the difference between a report and a lead.
+        at: error.stack?.split('\n')[1]?.trim() ?? '',
+      }),
+    ),
+    ...consoleLines(verdict),
+    msg('cli.shot.picture', { path: artifacts.image }),
+    msg('cli.shot.verdict', { path: artifacts.verdictFile }),
+  ];
+}
+
+/** The one line a reader sees first, and it names the gating fact rather than the file count. */
+export const shotSummary = (verdict: ShotVerdict): string => {
+  if (verdict.redirected) {
+    return msg('cli.shot.redirected', { route: verdict.route, url: verdict.finalUrl });
+  }
+  // Ahead of the console count, because a throw is the more severe fact AND the quieter one: an
+  // island that died can log nothing at all, so `errors` would report a clean page.
+  if (verdict.pageErrors.length > 0) {
+    return msg('cli.shot.threw', {
+      route: verdict.route,
+      thrown: verdict.pageErrors.length,
+      first: verdict.pageErrors[0]?.message ?? '',
+    });
+  }
+  if (verdict.errors > 0) {
+    return msg('cli.shot.errors', { route: verdict.route, errors: verdict.errors });
+  }
+  // `mounted`, not `booted`: "the runtime asked for the chunk" is not the claim worth making when
+  // the DOM can now say the mount RESOLVED.
+  return msg('cli.shot.ok', { route: verdict.route, islands: verdict.islands?.mounted ?? 0 });
+};

package/src/solid-loader.ts

@@ -0,0 +1,127 @@
+// The JSX transform every island chunk is built with: `.tsx` → Solid's COMPILED DOM output, run by
+// `babel-preset-solid` inside the island `Bun.build`'s own plugin. Solid's reactivity is a
+// COMPILE-time contract, which is why no runtime factory can stand in for the compiler here.
+
+/// <reference path="../types/babel-modules.d.ts" />
+// The reference is load-bearing, not decorative: @ultimat3/cli ships SOURCE, so an APP's
+// `tsc` compiles this file inside ITS program, where a `.d.ts` sitting in this directory is
+// not included and its `declare module` never applies. `tsc -b` proves it in this repo.
+import { transformAsync } from '@babel/core';
+import { contentHash } from '@ultimat3/render';
+import solidPreset from 'babel-preset-solid';
+import type { BunPlugin } from 'bun';
+import { IslandBuildFailedError } from './errors';
+
+/**
+ * `generate: 'dom'` because an island runs in a browser and nowhere else; `hydratable: false`
+ * because an island MOUNTS over server markup through its own `mount(el, props)` rather than
+ * resuming a Solid hydration tree — there is no `renderToString` pass on the other side of it, so
+ * hydration markers would be per-node bytes with no reader.
+ */
+const PRESET_OPTIONS = { generate: 'dom', hydratable: false } as const;
+
+/**
+ * The parser plugins, given DIRECTLY rather than through `@babel/plugin-syntax-typescript`. That
+ * plugin does nothing but push this same array, and Babel 8 deleted its `isTSX` option — so the
+ * documented spelling silently stops parsing JSX and every `<` becomes a type parameter. Given
+ * here the option surface is Babel's parser, which has never moved.
+ *
+ * Order is inert here and is NOT inert via `plugins:` — as plugin entries, the JSX one must precede
+ * the TypeScript one or `<button` parses as a type-parameter list. One more reason to say it once,
+ * here.
+ */
+const PARSER_PLUGINS = ['typescript', 'jsx'] as const;
+
+interface CacheEntry {
+  /** `contentHash` of the source the code was compiled from. */
+  readonly hash: string;
+  readonly code: string;
+}
+
+/**
+ * Keyed by PATH, not by content hash: `x dev` re-runs `buildIslands` on every change, and a map
+ * keyed by content would grow one entry per keystroke for the life of the process. One entry per
+ * island file is bounded by the island count, which is the only quantity that should bound it.
+ *
+ * It never hits inside a single `x build` — `discoverIslands` yields unique paths and `buildOne`
+ * runs once each. The dev loop is the whole reason it exists: Babel is ~8.7ms a file against
+ * `Bun.Transpiler`'s 0.07ms, so an app with twenty islands re-compiles nineteen unchanged files on
+ * every rebuild without this.
+ */
+const cache = new Map<string, CacheEntry>();
+
+/** Test seam: the cache is process-global because the dev server it serves is too. */
+export function clearIslandTransformCache(): void {
+  cache.clear();
+}
+
+/**
+ * `.tsx` source → Solid's compiled DOM expressions. Exported so the transform is testable as a
+ * function of its two inputs: the plugin below is the four lines of glue that hand it a file.
+ *
+ * The output is still TypeScript — Babel PARSES the annotations here and does not strip them,
+ * which is why the plugin declares `loader: 'ts'` and lets Bun remove them.
+ */
+export async function transformIslandTsx(source: string, path: string): Promise<string> {
+  const hash = contentHash(source);
+  const hit = cache.get(path);
+  if (hit !== undefined && hit.hash === hash) return hit.code;
+
+  // Babel installs its own `prepareStackTrace` on the first TRANSFORM — not on import, which is
+  // where this guard was first put — and leaving it installed makes `Error.captureStackTrace`
+  // strict for every unrelated module loaded later in the same process.
+  const saved = Error.prepareStackTrace;
+  let code: string | null | undefined;
+  try {
+    // `transformAsync` and never `transformFileAsync`: the latter is gated behind `@babel/core`'s
+    // `browser` export condition and throws "Transforming files is not supported in browsers"
+    // under `bun --conditions=browser`, which is the condition Solid work runs in.
+    const result = await transformAsync(source, {
+      filename: path,
+      // The app's own Babel config is not this transform's business, and an app that happens to
+      // have one must not change what its islands compile to.
+      babelrc: false,
+      configFile: false,
+      parserOpts: { plugins: [...PARSER_PLUGINS] },
+      presets: [[solidPreset, PRESET_OPTIONS]],
+    });
+    code = result?.code;
+  } finally {
+    Error.prepareStackTrace = saved;
+  }
+  // A parse error is NOT caught here: Babel's own message already names the file, the line and the
+  // column ("a.island.tsx: Unexpected token (2:23)"), and `buildOne` wraps whatever escapes in
+  // `X_BUILD_FAILED` naming the island. Re-wrapping it here would only bury that.
+  if (code == null) {
+    throw new IslandBuildFailedError({
+      file: path,
+      logs: 'the Solid JSX transform emitted no code',
+    });
+  }
+  cache.set(path, { hash, code });
+  return code;
+}
+
+/**
+ * The plugin `island-bundle.ts` hands `Bun.build`. It carries no state of its own, so one frozen
+ * descriptor serves every concurrent island build — `Bun.build` calls `setup` once per build with
+ * that build's own builder.
+ *
+ * `.tsx`, NOT `.island.tsx`. The narrow filter looks like axiom 6 and is the opposite of it: an
+ * island that imports a plain `.tsx` component — the most ordinary thing an author does, and what
+ * `x g resource` generates — would have that component compiled by nobody, and the app's
+ * `jsx: "preserve"` tsconfig turns it straight back into `React.createElement("span", …)` and
+ * `React is not defined`. Axiom 6 is already satisfied by GRAPH SEPARATION: this plugin runs
+ * inside the island build, whose graph only ever holds islands and what they import, and a page
+ * names its island by SPECIFIER and never imports one. So `.tsx` here already means exactly the
+ * set that ships to a browser — the filter never had to do that work.
+ */
+export const solidJsxPlugin: BunPlugin = {
+  name: 'ultimate-island-solid',
+  setup(build): void {
+    build.onLoad({ filter: /\.tsx$/ }, async ({ path }) => ({
+      contents: await transformIslandTsx(await Bun.file(path).text(), path),
+      loader: 'ts',
+    }));
+  },
+};

package/src/static-report.ts

@@ -0,0 +1,219 @@
+// The inventory of one `x build --target static`: which declared route reached the artifact, which
+// did not, and WHY for each. Written by the prerenderer, read back by `x build`, so both renderers
+// state the same thing. A skipped route with no reason is what turned "the island did not mount"
+// into a bug report about a page that had never been in `.x/static/` at all (#242).
+
+// `node:` twice, and only where Bun answers nothing: Bun ships no path API, and `rm(…, { force })`
+// deletes a report that may not be there without a branch. `existsSync` was a third and is gone —
+// `Bun.file(path).json()` already rejects on a missing file, into the catch that answers `undefined`.
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { RenderMode } from '@ultimat3/core';
+import { RENDER_MODES } from '@ultimat3/core';
+import type { Surface } from '@ultimat3/render';
+import { SURFACE_SPECS, SURFACES, surfaceAllows } from '@ultimat3/render';
+import type { JsonValue } from './output';
+
+/** Beside `.x/build-stats.json`, and written by the same call — see `readStaticReport` below. */
+export const STATIC_REPORT_FILE = join('.x', 'static-report.json');
+
+export const SKIP_REASONS = [
+  'surface-forbids-static',
+  'mode-revalidates',
+  'mode-per-request',
+  'no-prerender-paths',
+] as const;
+
+export type SkipReason = (typeof SKIP_REASONS)[number];
+
+/**
+ * Type ALIASES, never interfaces — every shape below is JSON on both sides of a file, and only an
+ * alias carries the implicit index signature that makes it assignable to `JsonValue`. As
+ * interfaces, `data: { emitted, skipped }` in `cmd-build.ts` was TS2322 (`not assignable to type
+ * 'JsonValue'`) with nothing wrong in either file, and the obvious fixes — a cast, a widened
+ * annotation — are the two this repo refuses. Same rule `RouteContext` in `@ultimat3/render` is an
+ * alias for.
+ */
+
+/** The two declarations a skip decision reads. Narrower than `RouteEntry` so a test can state one. */
+export type RouteFacts = {
+  readonly surface: Surface;
+  readonly render: RenderMode;
+};
+
+export type SkippedRoute = RouteFacts & {
+  /** The DECLARED path, `/blog/:slug` — never a filled one, so the author can grep for it. */
+  readonly route: string;
+  readonly reason: SkipReason;
+  readonly why: string;
+};
+
+/** One HTML file in the artifact, and the declared route that produced it. */
+export type EmittedPage = {
+  readonly route: string;
+  readonly path: string;
+  /** Relative to the build output root, POSIX — the file a screenshot tool actually opens. */
+  readonly file: string;
+};
+
+export type StaticReport = {
+  readonly target: 'static';
+  readonly out: string;
+  readonly buildId: string;
+  readonly emitted: readonly EmittedPage[];
+  readonly skipped: readonly SkippedRoute[];
+};
+
+/**
+ * The ONE decision about what lands on a CDN — `isPrerenderable` is derived from it, so the answer
+ * and the reason can never disagree.
+ *
+ * Surface is asked FIRST, and that ordering is the whole finding. `app/` allows `stream | ssr` and
+ * nothing else, so no `render:` edit can put an app/ route into the artifact: the surface is the
+ * cause, and naming the mode would send an author to change the one thing that cannot help. On a
+ * surface that DOES allow `static`, the mode is the cause and the edit is real — which is why the
+ * two produce different sentences below rather than one flat "not prerendered".
+ */
+export function skipReasonFor(route: RouteFacts): SkipReason | null {
+  if (!surfaceAllows(route.surface, 'static')) return 'surface-forbids-static';
+  if (route.render === 'static') return null;
+  return route.render === 'isr' ? 'mode-revalidates' : 'mode-per-request';
+}
+
+/**
+ * `Object.freeze<Record<…>>`, never `const X: Readonly<Record<…>> = Object.freeze({…})`: the second
+ * form infers from the literal and accepts an EXTRA key in silence (`bun run frozen-records`).
+ *
+ * English rather than `t()`, for the reason every `cause:`/`fix:` in this repo is English: this is
+ * a diagnostic an agent pastes into a report, and `wiki/Error-Codes.md` is the same surface.
+ */
+const WHY = Object.freeze<Record<SkipReason, (route: RouteFacts) => string>>({
+  'surface-forbids-static': (route) =>
+    `${route.surface}/ surface — server-rendered, not prerendered; ` +
+    `${route.surface}/ allows ${SURFACE_SPECS[route.surface].allowedModes.join(' | ') || 'no render mode'}, ` +
+    'so no route on it can ever reach the artifact',
+  'mode-revalidates': (route) =>
+    `render: '${route.render}' regenerates on a tag or ttl and a published file cannot, ` +
+    "so it is served by the app — change it to render: 'static' to emit it",
+  'mode-per-request': (route) =>
+    `render: '${route.render}' is rendered per request, so it is served by the app — ` +
+    "change it to render: 'static' to emit it",
+  'no-prerender-paths': (route) =>
+    `render: '${route.render}' with dynamic params and no prerender() paths, so the build ` +
+    'enumerated nothing to write — add prerender() to the route',
+});
+
+/** The reason as a row: the code a machine keys off, and the sentence a human reads. */
+export function skippedRoute(
+  input: RouteFacts & { readonly route: string },
+  reason: SkipReason,
+): SkippedRoute {
+  return {
+    route: input.route,
+    surface: input.surface,
+    render: input.render,
+    reason,
+    why: WHY[reason](input),
+  };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * A closed vocabulary, checked against the vocabulary itself. `typeof value === 'string'` is what
+ * `surface` and `render` were held to, and a string is not a `Surface`: the parse then handed back
+ * a `SkippedRoute` whose declared type says `'site' | 'app' | 'api' | 'shared'` while it holds
+ * whatever the file said, so `SURFACE_SPECS[route.surface]` on the read side is `undefined` at the
+ * first reader that indexes it. `SKIP_REASONS` was already checked this way; these two are the same
+ * kind of field and get the same rule.
+ */
+const inDomain = (domain: readonly string[], value: unknown): boolean =>
+  typeof value === 'string' && domain.includes(value);
+
+const isSkipped = (value: unknown): value is SkippedRoute =>
+  isRecord(value) &&
+  typeof value['route'] === 'string' &&
+  inDomain(SURFACES, value['surface']) &&
+  inDomain(RENDER_MODES, value['render']) &&
+  typeof value['why'] === 'string' &&
+  inDomain(SKIP_REASONS, value['reason']);
+
+const isEmitted = (value: unknown): value is EmittedPage =>
+  isRecord(value) &&
+  typeof value['route'] === 'string' &&
+  typeof value['path'] === 'string' &&
+  typeof value['file'] === 'string';
+
+/**
+ * Parsed, never cast. The file is this build's own output, but `x build` reads it back off disk
+ * after a subprocess — a truncated write or a hand-edit must read as "no report", which the caller
+ * already handles, rather than as a report with a `skipped` nobody can render.
+ */
+export function parseStaticReport(value: unknown): StaticReport | undefined {
+  if (!isRecord(value)) return undefined;
+  const { target, out, buildId, emitted, skipped } = value;
+  if (target !== 'static' || typeof out !== 'string' || typeof buildId !== 'string') {
+    return undefined;
+  }
+  if (!Array.isArray(emitted) || !emitted.every(isEmitted)) return undefined;
+  if (!Array.isArray(skipped) || !skipped.every(isSkipped)) return undefined;
+  return { target, out, buildId, emitted, skipped };
+}
+
+export async function writeStaticReport(root: string, report: StaticReport): Promise<string> {
+  const path = join(root, STATIC_REPORT_FILE);
+  await Bun.write(path, `${JSON.stringify(report, null, 2)}\n`);
+  return path;
+}
+
+/**
+ * `undefined` means no report — an app whose `apps/web/prerender.ts` does not call `prerenderSite`.
+ * That app also writes no `.x/build-stats.json` (one call writes both), so `x verify`'s `budgets`
+ * step already reds it with `X_BUDGET_UNMEASURED`; this side stays quiet rather than adding a
+ * second code for one cause.
+ */
+export async function readStaticReport(root: string): Promise<StaticReport | undefined> {
+  try {
+    return parseStaticReport(await Bun.file(join(root, STATIC_REPORT_FILE)).json());
+  } catch {
+    return undefined;
+  }
+}
+
+/** Deleted before the builder is spawned, so a failed build can never report the last one's list. */
+export async function removeStaticReport(root: string): Promise<void> {
+  await rm(join(root, STATIC_REPORT_FILE), { force: true });
+}
+
+/**
+ * The `--json` half, beside `renderStaticReport`'s human one — and a `Record<string, JsonValue>`
+ * rather than a `JsonValue`, because `x build` SPREADS it into `data` beside `target` and
+ * `artifact`: a bare `JsonValue` admits a string, so the spread is TS2698 (`spread types may only
+ * be created from object types`) and no annotation at the call site can rescue it.
+ *
+ * A field the compiler cannot prove is JSON reds HERE, at the projection, rather than at whichever
+ * caller happens to hand the report to a renderer.
+ */
+export function staticReportData(report: StaticReport | undefined): Record<string, JsonValue> {
+  // Never `{ ...report }`: `out` is an absolute build path and `buildId` is this run's, neither of
+  // which the inventory is about — `data` already carries `artifact` and the build's own id.
+  return report === undefined ? {} : { emitted: report.emitted, skipped: report.skipped };
+}
+
+/**
+ * The human half. Fixed-width columns headed by the JSON's own field names, exactly as
+ * `renderRouteTable` is — the renderer invents no prose, so `--json` and the terminal cannot drift.
+ */
+export function renderStaticReport(report: StaticReport): readonly string[] {
+  const rows: readonly (readonly string[])[] = [
+    ...report.emitted.map((page) => ['emitted', page.route, page.file]),
+    ...report.skipped.map((route) => ['skipped', route.route, route.why]),
+  ];
+  const widths = [0, 1].map((index) =>
+    Math.max(...rows.map((row) => (row[index] ?? '').length), 0),
+  );
+  return rows.map((row) =>
+    `  ${row.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join('  ')}`.trimEnd(),
+  );
+}