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

package/src/budgets.ts

@@ -13,6 +13,7 @@ import type { Manifest, RouteFact } from '@ultimat3/manifest';
 import { formatBytes, parseByteBudget } from '@ultimat3/render';
 import type { Finding } from './output';
 import type { UnmeasuredRoute } from './static-report';
+import { SW_REGISTER_PATH } from './sw-artifacts';
 
 export const BUILD_STATS_FILE = join('.x', 'build-stats.json');
 
@@ -24,7 +25,14 @@ export interface RouteStats {
    * prerenders many pages contributes ONE row, holding its heaviest.
    */
   readonly path: string;
+  /** The APP's JavaScript, and only the app's — see `FRAMEWORK_SCRIPTS`. */
   readonly jsBytes: number;
+  /**
+   * The framework's own injected runtime, in bytes: reported, never budgeted. Optional because a
+   * stats file written before 2026-09-11 has no such key, and absent is not zero — a row from an
+   * older build simply did not count it, and `checkBudgets` reads `jsBytes` either way.
+   */
+  readonly frameworkJsBytes?: number;
   /**
    * **Written by nothing, `As of 2026-08`.** `apps/web/prerender.ts` is the only producer of this
    * file and it emits static HTML — there is no browser in the build to observe a paint. So the
@@ -212,11 +220,39 @@ export interface MeasuredEntry {
 }
 
 export interface MeasuredJs {
+  /** The app's own executable bytes — what `budget.js` is a promise about. */
   readonly jsBytes: number;
-  /** Every `src=`/`data-x-entry=` module, so a finding can name the heaviest by file. */
+  /** The framework's injected runtime, counted separately so it is reported and never charged. */
+  readonly frameworkBytes: number;
+  /** Every APP `src=`/`data-x-entry=` module, so a finding can name the heaviest by file. */
   readonly entries: readonly MeasuredEntry[];
 }
 
+/**
+ * Scripts the FRAMEWORK injects into a document, which a route's `budget.js` does not answer for.
+ * `budget.js` is a promise about the APP's JavaScript: an author can delete an import, move one
+ * behind `hydrate: 'interaction'` or drop an island, and can do NOTHING about a file the build
+ * writes into every document it renders. Charging it made `js: '0kb'` — the budget `x new`
+ * scaffolds on `site/` — unreachable for any installable app, and the `fix:` it printed named an
+ * import chain of one entry the author never wrote.
+ *
+ * It was also not a stable number. `/x-sw-register.js` is written AFTER the documents that name
+ * it are weighed (`prerender.ts` emits the worker last, because its precache manifest is built
+ * from their content hashes), so a clean `.x/` measured a file that did not exist and recorded 0,
+ * and the next build measured the one before it and recorded 250. Same commit, green then red,
+ * decided by whether anything had cleaned the output directory.
+ *
+ * ENUMERATED, and it is one entry: `serviceWorkerHead` is the only `<script src>` the framework
+ * puts in a prerendered document — measured on a fresh scaffold plus `x g island` and
+ * `x g route`, where `<script src="/x-sw-register.js" defer>` is the only script tag across every
+ * emitted page. Two framework scripts are deliberately NOT here. `render/src/hydrate.ts`'s inline
+ * module runtime is charged, because it exists only when the page ships an island — it is the
+ * cost of the app's own interactivity, and a page with a `0kb` budget has none. `island-props.ts`'
+ * `<script type="application/json">` is already excluded as data, by `carriesJson`. A third one
+ * joins this set by a decision, here, with the same argument.
+ */
+export const FRAMEWORK_SCRIPTS: ReadonlySet<string> = new Set([SW_REGISTER_PATH]);
+
 /**
  * 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
@@ -226,6 +262,7 @@ export interface MeasuredJs {
  */
 export async function measureDocumentJs(html: string, out: string): Promise<MeasuredJs> {
   let jsBytes = 0;
+  let frameworkBytes = 0;
   const entries: MeasuredEntry[] = [];
   // Deduped ONCE, across both readers below, and the unit is the FETCH: a browser downloads a URL
   // once however many times the document names it, so `budget.js` — a byte budget — counts it
@@ -247,6 +284,14 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     fetched.add(url);
     const file = Bun.file(join(out, url.slice(1)));
     const bytes = (await file.exists()) ? file.size : 0;
+    // Counted and set aside, not skipped: the bytes are real and a reader is owed the number.
+    // Kept out of `entries` as well as out of `jsBytes`, because `entries` is what a finding reads
+    // to name the heaviest import — and on a fresh scaffold every route's `heaviestChain` was
+    // `/x-sw-register.js`, a file the author cannot edit, delete or move.
+    if (FRAMEWORK_SCRIPTS.has(url)) {
+      frameworkBytes += bytes;
+      return;
+    }
     entries.push({ url, bytes });
     jsBytes += bytes;
   };
@@ -266,7 +311,7 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     if (url === undefined) continue;
     await weigh(url);
   }
-  return { jsBytes, entries };
+  return { jsBytes, frameworkBytes, entries };
 }
 
 /**

package/src/cmd-doctor.ts

@@ -3,14 +3,20 @@
 // work back to the reader.
 
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import {
   ENV_EXAMPLE_PATH,
   ERROR_DOCS_URL,
   tryResolveEnvironment,
   usesDevCursorSecret,
 } from '@ultimat3/core';
-import { checkDb, createPostgresClient } from '@ultimat3/db';
+import {
+  checkDb,
+  createPostgresClient,
+  PGLITE_FIX,
+  PGLITE_MISSING,
+  PGLITE_PACKAGE,
+} from '@ultimat3/db';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -61,6 +67,16 @@ export interface DoctorProbe {
    * correctly answered `X_DB_UNAVAILABLE` (#F5).
    */
   database(): Promise<Finding | null>;
+  /**
+   * Is the EMBEDDED database usable, and is it the one this environment would open? A FACT and not
+   * a finding, the split `offlineFallback` makes below: reaching a module resolver is IO, and what
+   * an unresolvable optional peer MEANS is a pure rule with a pure test.
+   *
+   * `database()` answers `null` the moment `DATABASE_URL` is unset — which is exactly a bare VM,
+   * the configuration `x dev` invents a database FOR — so until this existed `x doctor` was silent
+   * about the only database a fresh box has. `bin/setup` found out instead, at `x db migrate`.
+   */
+  embeddedDatabase(): Promise<EmbeddedDatabase>;
   drift(): Promise<readonly Finding[]>;
   /**
    * The other half of the migrations directory: a newest migration with no `.snapshot.json`, which
@@ -76,11 +92,40 @@ export interface DoctorProbe {
   offlineFallback(): Promise<OfflineFallbackFact>;
 }
 
+/** What `x doctor` reads about the embedded database, without opening it. */
+export interface EmbeddedDatabase {
+  /**
+   * True while `DATABASE_URL` is unset or blank — the condition that makes PGlite the app's
+   * database (`resolveServices`), and the same reading `probeDatabase` returns `null` on.
+   */
+  readonly selected: boolean;
+  /** Does `@electric-sql/pglite` resolve from the app root? */
+  readonly resolved: boolean;
+}
+
 const finding = (code: string, cause: string, fix: string, at?: string): Finding =>
   at === undefined
     ? { code, cause, fix, docs: ERROR_DOCS_URL }
     : { code, cause, fix, docs: ERROR_DOCS_URL, at };
 
+/**
+ * The rule, pure. Red only where the embedded database is the one that would be opened: an app
+ * pointed at a real Postgres never loads PGlite, and a finding about an absent optional peer there
+ * is noise the reader learns to skim.
+ *
+ * `@ultimat3/db`'s own refusal, not a CLI twin of it — same `X_DB_UNAVAILABLE`, same sentence,
+ * same runnable fix. The package already says this the moment a query arrives; `x doctor` is what
+ * says it before `bin/setup` gets that far.
+ */
+export const embeddedDatabaseFinding = (fact: EmbeddedDatabase): Finding | undefined =>
+  fact.selected && !fact.resolved
+    ? finding(
+        'X_DB_UNAVAILABLE',
+        `${PGLITE_MISSING} — and DATABASE_URL is unset or blank, so the embedded one is the database this app would open`,
+        PGLITE_FIX,
+      )
+    : undefined;
+
 /** The file `x doctor` reports missing, and the one the reader creates. */
 export const ENV_DEVELOPMENT = '.env.development';
 
@@ -229,6 +274,10 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   if (offline !== undefined) findings.push(offline);
   const database = await probe.database();
   if (database !== null) findings.push(database);
+  // The other half of the same question, and the half a bare VM lands on: `database()` is silent
+  // where there is no `DATABASE_URL`, and that silence IS the bare-VM configuration.
+  const embedded = embeddedDatabaseFinding(await probe.embeddedDatabase());
+  if (embedded !== undefined) findings.push(embedded);
   findings.push(...(await probe.drift()));
   // Last, and it is why `X_CLI_UNEXPECTED`'s `fix: x doctor --json` is not a dead end on the path an
   // author reaches it from: `x db gen` throwing `X_MIGRATION_SNAPSHOT_MISSING` used to be a
@@ -249,6 +298,45 @@ export const doctorPort = (args: ParsedArgs): number =>
     DEFAULT_DOCTOR_PORT,
   );
 
+/**
+ * `DATABASE_URL` as BOTH halves of the database question read it: unset and blank are one case.
+ * One seam, because the two halves are complementary — a second reading of the same variable is
+ * how a configuration ends up reported by neither probe, or by both.
+ */
+const externalUrl = (raw: string | undefined): string | undefined =>
+  raw === undefined || raw.trim() === '' ? undefined : raw;
+
+/**
+ * Is the optional peer INSTALLED for this app — a `node_modules` walk up from the app root.
+ *
+ * Never an IMPORT: loading PGlite boots 26 MB of WASM and takes the single-writer lock the next
+ * command needs, and a diagnostic must not be the reason `x dev` cannot open the database it just
+ * reported on.
+ *
+ * Never `Bun.resolveSync` either, which was this check's first draft. It falls back to Bun's
+ * machine-global install cache: measured 2026-09-11 against a freshly scaffolded app with no
+ * `node_modules` anywhere above it, `Bun.resolveSync('@electric-sql/pglite', <app>)` answered
+ * `~/.bun/install/cache/@electric-sql/pglite@0.5.8@@@1/dist/index.js` — a version the app does not
+ * depend on, in a directory `bun install` never wrote for it. A box that had downloaded the package
+ * ONCE, for anything, would have read as ready on every app after it, which is the exact opposite
+ * of the question. The walk asks what `bun add` answers, and nothing else.
+ *
+ * Up from the root and not at it, because an app checked out inside a larger workspace is installed
+ * by the hoisting one: `examples/dummy` in this repository has no `node_modules` of its own.
+ */
+const installedAbove = (dir: string, specifier: string): boolean => {
+  let current = resolve(dir);
+  // Bounded by the path itself — one segment per step — rather than by `for (;;)` and the promise
+  // that `dirname('/')` is `/`. The loop still stops on that, one step earlier.
+  for (let remaining = current.split(sep).length; remaining > 0; remaining -= 1) {
+    if (existsSync(join(current, 'node_modules', specifier, 'package.json'))) return true;
+    const parent = dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+  return false;
+};
+
 /**
  * A real `select 1` through the app's own driver, not a TCP connect: a running Postgres with the
  * wrong credentials or a database that does not exist accepts the socket and refuses the session,
@@ -258,7 +346,7 @@ export const doctorPort = (args: ParsedArgs): number =>
  * next `x db migrate` cannot have.
  */
 async function probeDatabase(url: string | undefined): Promise<Finding | null> {
-  if (url === undefined || url.trim() === '') return null;
+  if (externalUrl(url) === undefined) return null;
   const client = createPostgresClient({ url, applicationName: 'x-doctor' });
   try {
     const report = await checkDb(client);
@@ -296,6 +384,12 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
     portFree,
     database: () => probeDatabase(process.env['DATABASE_URL']),
+    // `root ?? cwd` because the walk needs a directory that exists; outside an app `runDoctor`
+    // returns on `X_NOT_IN_APP` before this is ever asked, so the value only has to be honest.
+    embeddedDatabase: async () => ({
+      selected: externalUrl(process.env['DATABASE_URL']) === undefined,
+      resolved: installedAbove(root ?? cwd, PGLITE_PACKAGE),
+    }),
     drift: async () => (root === undefined ? [] : checkMigrationDrift(root)),
     snapshots: async () => (root === undefined ? [] : checkMigrationSnapshots(root)),
     // `routes: undefined` outside an app is "not judged", which is what the caller already is:

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