@ultimat3/cli 19.4.0 → 20.0.0

package/CLAUDE.md

@@ -259,6 +259,7 @@ change, and CI does not install one.
 |---|---|---|
 | `x shot <route>` | `x dev` on a scratch port, plus the app's own `puppeteer-core` through `@ultimat3/scraping` — launching Chrome here, or **attaching** to one over `--cdp-url` / `SCRAPE_CDP_URL`, which is what every stealth provider sells and what `remoteBrowser()` has called its primary path since it shipped | the static build — `--target static` prerenders `site/` only, so an `app/` route would photograph the landing page |
 | `x shot --island <name>` | the same server and the same browser, plus the app's own `*.island.states.ts` | a second command — photographing a route and photographing a component are one job with two subjects, and `--island` with a route positional is refused by name |
+| `x shot --all-islands` | every `*.island.states.ts` in the app, one boot, one browser per declared VIEWPORT across all of them | a second capture loop — one island and every island are `runIslandSweep` with one argument, because two loops are two answers to what a run produced |
 | `x pr review\|resolve\|reply` | `gh api graphql`, through the injected `Runner` | `gh pr view --comments`, which shows *issue* comments and not the line-anchored threads that carry the findings |
 | `x ci` | `gh run view --log-failed`, one call | a per-job log fetch — the run and all its jobs come back together |
 
@@ -277,10 +278,12 @@ ones a running app will not produce on request. `--island` takes them, one addre
 | `island-harness.ts` | the document that mounts ONE island over `data-x-entry` / `data-x-props` |
 | `island-harness-script.ts` | what runs before the chunk does: the sealed network, the pinned clock, the readiness watch |
 | `island-harness-route.ts` | `GET /_x/island`, mounted by `x dev` |
-| `island-shot.ts` | the capture loop, the assertions before each shutter, the missing-shot gate |
+| `island-shot.ts` | the RUN: which islands, in which order, which artifacts — and the missing-shot gate |
+| `island-capture.ts` | ONE picture: the assertions before the shutter, the crop rectangle, the one session |
+| `island-shot-index.ts` | `index.md` as a PURE function of (manifests, targets, verdicts) — no I/O in the rule |
 | `shot-browser.ts` | which browser a run gets — launch one here, or attach over `--cdp-url` / `SCRAPE_CDP_URL` — as three rules over plain inputs |
 | `island-verdict.ts` | the per-state verdict — a PNG cannot say the component threw or logged |
-| `cmd-shot-island.ts` | the flags, and the one browser per declared viewport |
+| `cmd-shot-island.ts` | the flags, the refusals, and the one browser per declared viewport |
 
 The vocabulary is **`@ultimat3/testing`'s**, not this package's: `defineIslandStates`,
 `islandShotTargets`, `islandAddress` / `parseIslandAddress`, `findIslandStates`,
@@ -312,6 +315,43 @@ mount that never finished, a page that never went quiet, a zero-sized box, a box
 and no text. Then a byte floor as a backstop. Every one of them otherwise comes out as a plausible
 image of the wrong thing.
 
+**`--all-islands` is a spelling, never `--island` with no value.** The parser refuses a bare
+`--island` ("expects a value") and `--island=` is an empty NAME, so "every island" had no form a
+reader could type that could not be read as a mistyped one. A boolean cannot be confused with a
+name. Every contradictory pair is refused BY NAME and before a value is read — beside `--island`,
+beside a route positional, and beside `--state`, which belongs to ONE manifest's vocabulary
+(`empty` in two manifests is two unrelated states). An app declaring no states at all is refused
+too, rather than answered with an empty gallery: "produced nothing and exited 0" is the one outcome
+a reader cannot tell from success. Its `fix:` names `x g island`, and deliberately not a states
+generator — a `fix:` may only cite a command this build ships (`fix-command.ts`), and there is none.
+
+**A sweep never aborts on a failure.** Every state the app CAN photograph is captured, every
+per-island `verdict.json` and the index are written, and only then does the missing-picture gate
+turn the reasons into a non-zero exit. One island that will not mount must not cost a reader the
+other nineteen — which is the same rule the per-state loop already followed, one level up.
+
+**`.x/shot/island/index.md` is the file an agent opens**, and it is written for a SINGLE-island run
+too: the file that says what a picture IS cannot be a property of how many islands were asked for.
+`island-shot-index.ts` is a pure renderer over (manifests, targets, verdicts) — no disk, no browser
+— and the caller does the writing, which is the split every check in this repo uses. It carries the
+counts, the re-run commands, the verdict's own `blind` list (handed in, never reworded: two
+wordings drift), and per state the `id`, the `title`, the `note` — the *"you cannot reach this by
+clicking, because …"* line, which is the whole reason a reviewer knows what they are looking at.
+
+**A console WARNING and an overflowing box are recorded and gate NOTHING.** `stateShotOk` reads
+neither, on purpose: a signal that fails a run is a signal an author switches off. The warnings were
+already in `page.console()` and already in `--json`; what was missing is that nobody counted them.
+The overflow is new and is the readiness probe's own answer — `scrollWidth > clientWidth` on the
+crop target, measured in the same round trip, because a fact measured after the shutter is a fact
+about a different page.
+
+**The clip carries a margin, clamped to the document.** It was the readiness box EXACTLY, and a
+pixel-tight rectangle shaves off everything a component paints outside its border box — a
+`box-shadow`, an outline, a focus ring, a hairline border on a subpixel — so a reviewer reads a
+component with no elevation as flat. `ISLAND_CROP_MARGIN_PX` is the one constant; the clamp reads
+the document's own extent off the probe (`page`), never the viewport, and it may only ever make the
+frame BIGGER than the component's box — a clamp that could shrink it would crop the subject.
+
 **One session per picture, and that is not an optimisation to collapse.** `page.console()` and
 `page.pageErrors()` are bounded rings over the whole SESSION, so a shared one files state A's
 console errors under state B — and per-state attribution is the half of the artifact that gates.
@@ -1487,7 +1527,20 @@ refuses). A guard returning `[1n]` is `X_GUARD_FINDING_INVALID`, per candidate,
 entry costs its own line and not the real findings beside it. The mechanism whose job is producing
 structured failures handing back a stack trace is the one outcome it exists to prevent.
 
-**`x new` ships four guards, `As of 2026-08-22`.** The scaffolded `AGENTS.md` states nine
+**`x new` ships NINE guards, `As of 2026-09-08`** — the four below plus five interface rules
+(`semantic-interactive`, `focus-visible`, `image-dimensions`, `animated-layout-property`,
+`island-without-states`), each statically decidable and each carrying a legitimate-lookalike test
+that must NOT be reported. **Two of the original four were broken the whole time and nobody could
+see it**, because no guard had ever run against a real app: `raw-colour` reported all 87 uses of
+`rgb(var(--color-…))` — which IS the token form `_colors.scss` emits, so its own cause line ("a
+value no theme can restate") was false of every one — and `untranslated-string`'s JSX mask
+`/\{[^{}]*\}/g` does not nest, so `{t('k', { org: x })}` lost its inner brace group first and the
+remnant read as prose, flagging every `t()` call with an interpolation object or a template-literal
+key. Both are fixed and both now report zero against `examples/dummy`, which is the first tracked
+app to carry a `guards/` directory at all. Read the count, never this sentence:
+`bun -e "import {scaffoldGuardFiles} from './packages/cli/src/templates/scaffold-guards'; console.log(scaffoldGuardFiles().length)"`.
+
+The scaffolded `AGENTS.md` states nine
 non-negotiables, and five of them used to be prose — each proven green on `x verify`: a hardcoded
 JSX string beside a `t()` call, `color: #ff0000` in a stylesheet whose own scaffolded header called
 it "a lint failure", `toLocaleDateString('en-US')` with no `timeZone`, `t.number` money, and a bare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "19.4.0",
+  "version": "20.0.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": "19.4.0",
-    "@ultimat3/admin": "19.4.0",
-    "@ultimat3/ai": "19.4.0",
-    "@ultimat3/auth": "19.4.0",
-    "@ultimat3/cache": "19.4.0",
-    "@ultimat3/core": "19.4.0",
-    "@ultimat3/db": "19.4.0",
-    "@ultimat3/entity": "19.4.0",
-    "@ultimat3/flags": "19.4.0",
-    "@ultimat3/http": "19.4.0",
-    "@ultimat3/i18n": "19.4.0",
-    "@ultimat3/jobs": "19.4.0",
-    "@ultimat3/mail": "19.4.0",
-    "@ultimat3/manifest": "19.4.0",
-    "@ultimat3/mcp": "19.4.0",
-    "@ultimat3/money": "19.4.0",
-    "@ultimat3/notify": "19.4.0",
-    "@ultimat3/policy": "19.4.0",
-    "@ultimat3/pwa": "19.4.0",
-    "@ultimat3/query": "19.4.0",
-    "@ultimat3/realtime": "19.4.0",
-    "@ultimat3/render": "19.4.0",
-    "@ultimat3/schema": "19.4.0",
-    "@ultimat3/scraping": "19.4.0",
-    "@ultimat3/seo": "19.4.0",
-    "@ultimat3/storage": "19.4.0",
-    "@ultimat3/testing": "19.4.0",
-    "@ultimat3/time": "19.4.0",
+    "@ultimat3/action": "20.0.0",
+    "@ultimat3/admin": "20.0.0",
+    "@ultimat3/ai": "20.0.0",
+    "@ultimat3/auth": "20.0.0",
+    "@ultimat3/cache": "20.0.0",
+    "@ultimat3/core": "20.0.0",
+    "@ultimat3/db": "20.0.0",
+    "@ultimat3/entity": "20.0.0",
+    "@ultimat3/flags": "20.0.0",
+    "@ultimat3/http": "20.0.0",
+    "@ultimat3/i18n": "20.0.0",
+    "@ultimat3/jobs": "20.0.0",
+    "@ultimat3/mail": "20.0.0",
+    "@ultimat3/manifest": "20.0.0",
+    "@ultimat3/mcp": "20.0.0",
+    "@ultimat3/money": "20.0.0",
+    "@ultimat3/notify": "20.0.0",
+    "@ultimat3/policy": "20.0.0",
+    "@ultimat3/pwa": "20.0.0",
+    "@ultimat3/query": "20.0.0",
+    "@ultimat3/realtime": "20.0.0",
+    "@ultimat3/render": "20.0.0",
+    "@ultimat3/schema": "20.0.0",
+    "@ultimat3/scraping": "20.0.0",
+    "@ultimat3/seo": "20.0.0",
+    "@ultimat3/storage": "20.0.0",
+    "@ultimat3/testing": "20.0.0",
+    "@ultimat3/time": "20.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-shot-island.ts

@@ -1,7 +1,11 @@
-// `--island`'s half of `x shot`: read the flags, resolve the manifest, refuse the combinations
-// that cannot mean anything, and hand `runIslandShot` values. Split from `cmd-shot.ts` so neither
-// file has to hold both a route capture and a component capture — the two share a boot, a browser
-// and an output tree, and nothing else.
+// `--island` and `--all-islands`: read the flags, resolve the manifests, refuse the combinations
+// that cannot mean anything, and hand the run its values. Split from `cmd-shot.ts` so neither file
+// has to hold both a route capture and a component capture — the two share a boot, a browser and
+// an output tree, and nothing else.
+//
+// One island and every island are one code path with one argument (`runIslandSweep`), never two
+// loops: two would be two answers to what a run produced, and the sweep is the form an agent
+// reaches for first.
 
 // why: no Bun native joins or resolves a path; `--out` is resolved against the app root.
 import { join, resolve } from 'node:path';
@@ -11,10 +15,16 @@ import { findIslandStates } from '@ultimat3/testing';
 import { appBrowser } from './browser-launcher';
 import { BadFlagError } from './errors';
 import type { IslandBrowser } from './island-shot';
-import { ISLAND_SHOT_DIR, runIslandShot } from './island-shot';
+import { ISLAND_SHOT_DIR, runIslandShot, runIslandSweep } from './island-shot';
 import { loadIslandStates } from './island-states-load';
-import type { IslandArtifacts } from './island-verdict';
-import { islandShotLines, islandShotSummary, islandVerdictJson } from './island-verdict';
+import type { IslandArtifacts, IslandSweepArtifacts } from './island-verdict';
+import {
+  islandShotLines,
+  islandShotSummary,
+  islandSweepLines,
+  islandSweepSummary,
+  islandVerdictJson,
+} from './island-verdict';
 import type { CommandResult } from './output';
 import type { ShotServer } from './shot-server';
 import { SHOT_DIR } from './shot-server';
@@ -79,6 +89,62 @@ export function refuseRouteWithIsland(route: string | undefined, island: string)
   });
 }
 
+/**
+ * An app with no `*.island.states.ts` anywhere. Refused by NAME rather than answered with an empty
+ * gallery: a run that produces no picture and exits 0 is the one outcome a reader cannot tell from
+ * success, and it is what this whole command exists to make impossible.
+ *
+ * The `fix:` is the generator that exists. It deliberately does not name a states generator: a
+ * `fix:` may only cite a command this build ships (`fix-command.ts`), and there is none.
+ */
+export function refuseNoIslandStates(flag: 'island' | 'all-islands'): never {
+  throw new BadFlagError({
+    flag,
+    command: 'shot',
+    reason: 'this app declares no island states at all, so there is nothing to photograph',
+    fix: "x g island settings --at apps/web/app/settings   # then declare its states beside it with defineIslandStates({ island: '…', states: [...] })",
+  });
+}
+
+/**
+ * `--all-islands` is the WHOLE app and `--island <name>` is one component, so naming both is two
+ * subjects and one command. Refused by name for `refuseRouteWithIsland`'s reason: a reader who
+ * typed both has a belief about which one runs, and half of them would be wrong.
+ */
+export function refuseSweepWithIsland(island: string): never {
+  throw new BadFlagError({
+    flag: 'all-islands',
+    command: 'shot',
+    reason: `--all-islands photographs every island and --island ${island} photographs one; x shot takes one subject`,
+    fix: 'x shot --all-islands --json',
+  });
+}
+
+/** A route and every island are two subjects too, and the same rule decides it. */
+export function refuseSweepWithRoute(route: string): never {
+  throw new BadFlagError({
+    flag: 'all-islands',
+    command: 'shot',
+    reason: `--all-islands photographs every island and "${route}" is a route; x shot takes one subject`,
+    fix: 'x shot --all-islands --json',
+  });
+}
+
+/**
+ * A state id belongs to ONE island's vocabulary — `empty` in two manifests is two unrelated
+ * states — so a filter across every island either means nothing or silently means whichever
+ * islands happen to share the word. The fix names the one-island form, which is where a state id
+ * can be resolved at all.
+ */
+export function refuseSweepWithState(state: string): never {
+  throw new BadFlagError({
+    flag: 'state',
+    command: 'shot',
+    reason: `--state ${state} names one island's declared state, and --all-islands spans every island`,
+    fix: 'x shot --island <name> --state <id> --json',
+  });
+}
+
 export interface IslandShotInput {
   readonly root: string;
   readonly island: string;
@@ -96,6 +162,9 @@ export interface IslandShotInput {
   readonly minBytes?: number | undefined;
 }
 
+/** Every field the one-island form takes, minus the two that name one island and one state. */
+export type IslandSweepInput = Omit<IslandShotInput, 'island' | 'state'>;
+
 /**
  * The states are loaded, expanded and the name resolved BEFORE a browser or a dev server exists —
  * a typo must not cost an embedded Postgres to report, and the expected picture list has to be
@@ -103,14 +172,7 @@ export interface IslandShotInput {
  */
 export async function islandShot(input: IslandShotInput): Promise<IslandArtifacts> {
   const all = await loadIslandStates(input.root);
-  if (all.length === 0) {
-    throw new BadFlagError({
-      flag: 'island',
-      command: 'shot',
-      reason: 'this app declares no island states at all, so there is nothing to photograph',
-      fix: "x g island settings --at apps/web/app/settings   # then declare its states beside it with defineIslandStates({ island: '…', states: [...] })",
-    });
-  }
+  if (all.length === 0) refuseNoIslandStates('island');
   // `findIslandStates` is loose on the way in — `Settings`, `settings`, `settings.island.tsx` and
   // the full path are one name — and refuses an unresolved one by listing every valid name, which
   // is what tells a typo apart from an island whose states were never declared.
@@ -138,6 +200,48 @@ export async function islandShot(input: IslandShotInput): Promise<IslandArtifact
   });
 }
 
+/**
+ * Every island in the app, one boot, one browser per declared viewport across ALL of them — the
+ * memo lives in the `islandBrowser` closure built here, so a sweep of forty states at one size is
+ * still one launch. The manifests are loaded before a browser or a dev server exists, for
+ * `islandShot`'s reason: the complete expected picture list has to be knowable without either.
+ */
+export async function islandSweep(input: IslandSweepInput): Promise<IslandSweepArtifacts> {
+  const all = await loadIslandStates(input.root);
+  if (all.length === 0) refuseNoIslandStates('all-islands');
+  return runIslandSweep({
+    manifests: all,
+    outDir:
+      input.out === undefined
+        ? join(input.root, SHOT_DIR, ISLAND_SHOT_DIR)
+        : resolve(input.root, input.out),
+    driver:
+      input.driver ??
+      islandBrowser({
+        root: input.root,
+        ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
+        ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
+      }),
+    boot: input.boot,
+    settleMs: input.settleMs,
+    timeoutMs: input.timeoutMs,
+    ...(input.extraHosts === undefined ? {} : { extraHosts: input.extraHosts }),
+    ...(input.minBytes === undefined ? {} : { minBytes: input.minBytes }),
+  });
+}
+
+export const islandSweepResult = (artifacts: IslandSweepArtifacts): CommandResult => ({
+  ok: artifacts.ok,
+  command: 'shot',
+  summary: islandSweepSummary(artifacts),
+  lines: islandSweepLines(artifacts),
+  data: {
+    dir: artifacts.dir,
+    indexFile: artifacts.indexFile,
+    islands: artifacts.verdicts.map(islandVerdictJson),
+  },
+});
+
 export const islandShotResult = (artifacts: IslandArtifacts): CommandResult => ({
   ok: artifacts.verdict.ok,
   command: 'shot',
@@ -146,6 +250,7 @@ export const islandShotResult = (artifacts: IslandArtifacts): CommandResult => (
   data: {
     dir: artifacts.dir,
     verdictFile: artifacts.verdictFile,
+    indexFile: artifacts.indexFile,
     verdict: islandVerdictJson(artifacts.verdict),
   },
 });

package/src/cmd-shot.ts

@@ -12,7 +12,16 @@ import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
-import { islandShot, islandShotResult, refuseRouteWithIsland } from './cmd-shot-island';
+import {
+  islandShot,
+  islandShotResult,
+  islandSweep,
+  islandSweepResult,
+  refuseRouteWithIsland,
+  refuseSweepWithIsland,
+  refuseSweepWithRoute,
+  refuseSweepWithState,
+} from './cmd-shot-island';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, MissingPositionalError } from './errors';
 import { intFlagOr, PORT_RANGE } from './flag-number';
@@ -275,9 +284,9 @@ export const shotResult = (artifacts: ShotArtifacts): CommandResult => ({
 export const shotCommand: CliCommand = {
   spec: {
     name: 'shot',
-    summary: 'photograph one route, or one island in a state it declares, from a real browser',
+    summary: 'photograph one route, one island in a state it declares, or every island in the app',
     usage:
-      'x shot <route> | --island <name> [--state <id>] [--port 0] [--out <dir>] [--settle 2000] [--json]',
+      'x shot <route> | --island <name> [--state <id>] | --all-islands [--port 0] [--out <dir>] [--settle 2000] [--json]',
     requiresApp: true,
     flags: [
       { name: 'port', type: 'string', summary: 'dev port (0 lets the kernel pick a free one)' },
@@ -305,6 +314,15 @@ export const shotCommand: CliCommand = {
         type: 'string',
         summary: 'one declared state of that island, not all of them',
       },
+      // Its own SPELLING and never `--island` with no value: the parser refuses a bare `--island`
+      // ("expects a value") and `--island=` is an empty name, so "every island" had no form a
+      // reader could type that could not be read as a mistyped one. A boolean cannot be confused
+      // with a name, and `x shot --all-islands` says what it does beside `x shot --island <name>`.
+      {
+        name: 'all-islands',
+        type: 'boolean',
+        summary: 'every island in the app, in every state it declares, plus an index.md',
+      },
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -312,11 +330,20 @@ export const shotCommand: CliCommand = {
     // Every value read before anything boots: a typo must not cost a browser and a dev server to
     // report, which is the rule `x routes` and `x mcp` already follow.
     const island = flagString(ctx.args, 'island');
+    const state = flagString(ctx.args, 'state');
     const positional = ctx.args.positionals[0];
+    const sweep = flagBool(ctx.args, 'all-islands');
+    // Every ambiguous pair refused BY NAME, before a value is read: a reader who typed two
+    // subjects has a belief about which one runs, and half of them would be wrong.
+    if (sweep && island !== undefined && island !== '') refuseSweepWithIsland(island);
+    if (sweep && positional !== undefined) refuseSweepWithRoute(positional);
+    // A state id is one manifest's vocabulary, so it cannot mean anything across every island.
+    if (sweep && state !== undefined && state !== '') refuseSweepWithState(state);
     if (island !== undefined && island !== '' && positional !== undefined) {
       refuseRouteWithIsland(positional, island);
     }
-    const route = island === undefined || island === '' ? readRoute(positional) : '';
+    const component = sweep || (island !== undefined && island !== '');
+    const route = component ? '' : readRoute(positional);
     const port = intFlag(ctx.args, 'port', PORT_RANGE.min, DEFAULT_PORT, PORT_RANGE.max);
     const settleMs = intFlag(ctx.args, 'settle', 0, DEFAULT_SETTLE_MS);
     const timeoutMs = intFlag(ctx.args, 'timeout', 1, DEFAULT_PAGE_TIMEOUT_MS);
@@ -332,24 +359,22 @@ export const shotCommand: CliCommand = {
     });
     const out = flagString(ctx.args, 'out');
     const boot = (): Promise<ShotServer> => devServerFor(root, ctx.env, port);
+    const shared = {
+      root,
+      ...(out === undefined ? {} : { out }),
+      settleMs,
+      timeoutMs,
+      ...(executablePath === undefined ? {} : { executablePath }),
+      ...(cdpUrl === undefined ? {} : { cdpUrl }),
+      ...(flagString(ctx.args, 'allow-hosts') === undefined
+        ? {}
+        : { extraHosts: flagString(ctx.args, 'allow-hosts') }),
+      boot,
+    };
+    if (sweep) return islandSweepResult(await islandSweep(shared));
     if (island !== undefined && island !== '') {
       return islandShotResult(
-        await islandShot({
-          root,
-          island,
-          ...(flagString(ctx.args, 'state') === undefined
-            ? {}
-            : { state: flagString(ctx.args, 'state') }),
-          ...(out === undefined ? {} : { out }),
-          settleMs,
-          timeoutMs,
-          ...(executablePath === undefined ? {} : { executablePath }),
-          ...(cdpUrl === undefined ? {} : { cdpUrl }),
-          ...(flagString(ctx.args, 'allow-hosts') === undefined
-            ? {}
-            : { extraHosts: flagString(ctx.args, 'allow-hosts') }),
-          boot,
-        }),
+        await islandShot({ ...shared, island, ...(state === undefined ? {} : { state }) }),
       );
     }
     // Resolved before the boot for the same reason: an app with no browser installed must not pay