@ultimat3/cli 11.1.0 → 11.2.0

package/CLAUDE.md

@@ -167,6 +167,7 @@ change, and CI does not install one.
 | | Reaches for | Never |
 |---|---|---|
 | `x shot <route>` | `x dev` on a scratch port, plus the app's own `puppeteer-core` through `@ultimat3/scraping` | 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 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 |
 
@@ -174,6 +175,65 @@ change, and CI does not install one.
 not observe alongside what it did. A capture tool that silently omits what it cannot see is worse
 than one that says so, because the omission reads as a clean result.
 
+### `--island` photographs ONE component in a state nobody can click to
+
+A failed read, an empty list, over-quota, read-only: the states a reviewer most needs to see are the
+ones a running app will not produce on request. `--island` takes them, one address at a time.
+
+| File | Job |
+|---|---|
+| `island-states-load.ts` | discover `*.island.states.ts`, prove each pure, import it, check the set |
+| `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-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 |
+
+The vocabulary is **`@ultimat3/testing`'s**, not this package's: `defineIslandStates`,
+`islandShotTargets`, `islandAddress` / `parseIslandAddress`, `findIslandStates`,
+`assertIslandStatesPure`. `cli → testing` is a declared sideways edge and `cli → scraping` is
+another, which is what makes `@ultimat3/cli` the only package that can hold both the mount half and
+the screenshot half.
+
+**The expected picture list exists before a browser does.** `loadIslandStates` → `findIslandStates`
+→ `islandShotTargets` is a pure expansion off files on disk, and the run ends by diffing it against
+what actually landed (`missingShots`, `X_SHOT_ISLAND_MISSING`). That diff is the point of the whole
+design: a loop that swallowed every failure would otherwise report a clean run with no pictures in
+it, and "produced nothing and exited 0" is the one outcome a reader cannot tell from success.
+
+**An unstubbed request FAILS the run.** The page's own seal replaces `fetch`, `WebSocket`,
+`EventSource` and `XMLHttpRequest` before the island's chunk is imported, answers the state's
+`routes` and publishes everything else on `window.__xShot.unstubbed`; the capture refuses on a
+non-empty list with `X_SHOT_ISLAND_UNSTUBBED_REQUEST`, naming each method and path. A component
+whose fetch quietly hangs paints its own loading branch, and the picture then shows a fixture gap
+dressed up as a real component state. `@ultimat3/testing`'s `sealNetwork()` is not reusable here:
+it patches THIS process's `globalThis.fetch` and the component runs in the page's realm.
+
+**Readiness is quiet, not idle.** Fonts ready, then N consecutive animation frames with an unchanged
+network-ACTIVITY counter — never "nothing in flight", which never comes for a state whose fixture is
+deliberately `pending`, and never a fixed sleep, which photographs whatever a slow machine painted.
+
+**Eight assertions before a shutter opens** (`photographFault`), each naming a fact the picture would
+have hidden rather than shown: no probe, not the harness, no host element, a mount that REJECTED, a
+mount that never finished, a page that never went quiet, a zero-sized box, a box with no children
+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.
+
+**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.
+
+**The picture is the VIEWPORT, not a crop.** `@ultimat3/scraping`'s `CaptureRequest` is `fullPage`
+alone, so there is no clip rectangle to ask for; the framing knob is the state's own `viewport`,
+passed to `launch()` as `defaultViewport` through `LocalBrowserOptions.options`. That is why there
+is one browser per declared viewport, memoised. The verdict names it as a blind spot rather than
+implying a crop it did not perform.
+
+**`loadApp` does not import a states file**, for the reason it does not import an island: it
+registers no primitive, and importing it would put `@ultimat3/testing` in the server module graph of
+every `x dev`, every `x build` and every gate step that loads the app (axiom 6).
+
 **`x shot` reuses a running `x dev` rather than booting a second one.** Embedded Postgres is
 single-writer, so a second boot is `X_DEV_ALREADY_RUNNING` and no picture is ever taken. A reused
 server's `stop()` deliberately does not clear the other process's lock.

package/package.json

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

package/src/app-load.ts

@@ -46,6 +46,15 @@ const ENTRY_POINT = /^apps\/[^/]+\/(?:server|prerender)\.tsx?$/;
  */
 const CLIENT_ENTRY_POINT = /\.island\.tsx$/;
 
+/**
+ * A `*.island.states.ts` is read by a TOOL, not by the server: `x shot --island` loads it, the
+ * harness route loads it, and a guard test loads it. It registers no primitive and it imports
+ * `@ultimat3/testing`, so importing it here would put the test-support package in the module graph
+ * of every `x dev`, every `x build` and every gate step that loads the app — the same rule the
+ * client entry point above follows, for the same reason (axiom 6).
+ */
+const STATES_FILE = /\.island\.states\.ts$/;
+
 export interface LoadedApp {
   readonly root: string;
   /** App-root-relative POSIX paths of every module that imported, sorted. */
@@ -88,7 +97,9 @@ export async function loadApp(root: string): Promise<LoadedApp> {
     for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
       if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
       const file = relative(root, absolute).split(sep).join('/');
-      if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file)) continue;
+      if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
+        continue;
+      }
       let module: Record<string, unknown>;
       try {
         module = (await import(absolute)) as Record<string, unknown>;

package/src/browser-launcher.ts

@@ -57,6 +57,13 @@ export interface AppBrowserOptions {
   readonly root: string;
   /** `--browser`, then `PUPPETEER_EXECUTABLE_PATH`, then `CHROME_PATH`. */
   readonly executablePath?: string | undefined;
+  /**
+   * The page size this browser lays out at. A LAUNCH option and not a per-capture one, because
+   * that is the only place the shipped port has for it: `CaptureRequest` is `fullPage` alone
+   * (`packages/scraping/src/page.ts`), so the viewport IS the frame of every picture taken with
+   * this driver — which is why `x shot --island` builds one browser per declared viewport.
+   */
+  readonly viewport?: { readonly width: number; readonly height: number } | undefined;
   /** Test seam: the resolver and the loader, so a test proves the refusal without an install. */
   readonly resolve?: (specifier: string, from: string) => string;
   readonly load?: (path: string) => Promise<unknown>;
@@ -103,5 +110,10 @@ export async function appBrowser(options: AppBrowserOptions): Promise<ScrapeDriv
     launcher,
     headless: true,
     ...(options.executablePath === undefined ? {} : { executablePath: options.executablePath }),
+    // `LocalBrowserOptions.options` is passed through to `launch()` untouched, which is the seam
+    // that lets the CLI size a browser without `@ultimat3/scraping` naming a puppeteer type.
+    ...(options.viewport === undefined
+      ? {}
+      : { options: { defaultViewport: { ...options.viewport } } }),
   });
 }

package/src/cmd-dev.ts

@@ -38,7 +38,9 @@ import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands } from './island-bundle';
+import { islandHarnessRoutes } from './island-harness-route';
 import { islandRoutes } from './island-routes';
+import { loadIslandStates } from './island-states-load';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
@@ -181,6 +183,15 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // The chunks the documents below name. Mounted before the app's routes for the reason
     // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
     ...islandRoutes(() => state.islands),
+    // `x shot --island`'s harness, in the `/_x` dev namespace so no app route can shadow it. It
+    // lives here rather than in a second server because everything it needs is in THIS process:
+    // the built chunks, the app's stylesheet registry, and the one embedded Postgres a checkout
+    // may have. The states are read per REQUEST — an author editing a state and re-running the
+    // command must not need a restart to see it.
+    ...islandHarnessRoutes({
+      islands: () => state.islands,
+      states: () => loadIslandStates(options.root),
+    }),
     ...appRoutes({ buildId, resolveIsland: (file) => state.islands.resolverFor(file) }),
   ];
 

package/src/cmd-shot-island.ts

@@ -0,0 +1,146 @@
+// `--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.
+
+// why: no Bun native joins or resolves a path; `--out` is resolved against the app root.
+import { join, resolve } from 'node:path';
+import type { ScrapeDriver } from '@ultimat3/scraping';
+import type { IslandStatesManifest, IslandViewport } from '@ultimat3/testing';
+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 { loadIslandStates } from './island-states-load';
+import type { IslandArtifacts } from './island-verdict';
+import { islandShotLines, islandShotSummary, islandVerdictJson } from './island-verdict';
+import type { CommandResult } from './output';
+import type { ShotServer } from './shot-server';
+import { SHOT_DIR } from './shot-server';
+
+/**
+ * One browser per declared viewport, memoised. A state declares its own size and the viewport is a
+ * LAUNCH option, so two states at two sizes are two browsers — but two states at one size must not
+ * be, or a manifest of eight states pays eight launches for nothing.
+ */
+export function islandBrowser(input: {
+  readonly root: string;
+  readonly executablePath?: string | undefined;
+}): IslandBrowser {
+  const byViewport = new Map<string, Promise<ScrapeDriver>>();
+  return (viewport: IslandViewport): Promise<ScrapeDriver> => {
+    const key = `${viewport.width}x${viewport.height}`;
+    const held = byViewport.get(key);
+    if (held !== undefined) return held;
+    const started = appBrowser({
+      root: input.root,
+      ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
+      viewport: { width: viewport.width, height: viewport.height },
+    });
+    byViewport.set(key, started);
+    return started;
+  };
+}
+
+/**
+ * `--state <id>` against what the manifest really declares. Refused here rather than by an empty
+ * expansion downstream: a filter that matches nothing produces no picture, and a run that produces
+ * no picture and exits 0 is the outcome this whole command exists to make impossible.
+ */
+export function readStateFlag(
+  manifest: IslandStatesManifest,
+  wanted: string | undefined,
+): string | undefined {
+  if (wanted === undefined || wanted === '') return undefined;
+  if (manifest.states.some((one) => one.id === wanted)) return wanted;
+  const known = manifest.states.map((one) => one.id);
+  throw new BadFlagError({
+    flag: 'state',
+    command: 'shot',
+    reason: `${manifest.island} declares no state "${wanted}" — it declares ${known.join(', ')}`,
+    fix: `x shot --island ${manifest.name} --state ${known[0] ?? '<id>'} --json`,
+  });
+}
+
+/**
+ * `--island` and a route positional are two different subjects and one command, so naming both is
+ * refused by name. Never silently preferring one: a reader who typed both has a belief about which
+ * one runs, and half of them would be wrong.
+ */
+export function refuseRouteWithIsland(route: string | undefined, island: string): never {
+  throw new BadFlagError({
+    flag: 'island',
+    command: 'shot',
+    reason: `--island ${island} photographs a component and "${route ?? ''}" is a route; x shot takes one subject`,
+    fix: `x shot --island ${island} --json`,
+  });
+}
+
+export interface IslandShotInput {
+  readonly root: string;
+  readonly island: string;
+  readonly state?: string | undefined;
+  readonly out?: string | undefined;
+  readonly settleMs: number;
+  readonly timeoutMs: number;
+  readonly extraHosts?: string | undefined;
+  readonly executablePath?: string | undefined;
+  readonly boot: () => Promise<ShotServer>;
+  /** Injected by a test, so the whole path is proved on a machine with no Chrome. */
+  readonly driver?: IslandBrowser | undefined;
+  readonly minBytes?: number | undefined;
+}
+
+/**
+ * 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
+ * knowable without either.
+ */
+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: [...] })",
+    });
+  }
+  // `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.
+  const manifest = findIslandStates(all, input.island);
+  const only = readStateFlag(manifest, input.state);
+  return runIslandShot({
+    manifest,
+    ...(only === undefined ? {} : { state: only }),
+    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 }),
+      }),
+    boot: input.boot,
+    settleMs: input.settleMs,
+    timeoutMs: input.timeoutMs,
+    ...(input.extraHosts === undefined ? {} : { extraHosts: input.extraHosts }),
+    ...(input.minBytes === undefined ? {} : { minBytes: input.minBytes }),
+  });
+}
+
+export const islandShotResult = (artifacts: IslandArtifacts): CommandResult => ({
+  ok: artifacts.verdict.ok,
+  command: 'shot',
+  summary: islandShotSummary(artifacts.verdict),
+  lines: islandShotLines(artifacts),
+  data: {
+    dir: artifacts.dir,
+    verdictFile: artifacts.verdictFile,
+    verdict: islandVerdictJson(artifacts.verdict),
+  },
+});

package/src/cmd-shot.ts

@@ -12,16 +12,15 @@ import type { ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
 import { appBrowser, browserBinaryExists, executablePathFrom } from './browser-launcher';
-import { startDev } from './cmd-dev';
+import { islandShot, islandShotResult, refuseRouteWithIsland } from './cmd-shot-island';
 import type { CliCommand, CommandContext } from './command';
-import { clearLock, isProcessAlive, lockPath, parseLock, preflight, writeLock } from './dev-lock';
-import { DEV_BINDING } from './dev-roles';
-import { resolveServices } from './dev-services';
 import { BadFlagError, MissingPositionalError } from './errors';
 import { intFlagOr, PORT_RANGE } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
+import type { BootDevServer, ShotServer } from './shot-server';
+import { allowHostsFrom, devServerFor, SHOT_DIR } from './shot-server';
 import { SETTLE_POLL_MS, settleIslands } from './shot-settle';
 import type { IslandCount, ShotArtifacts } from './shot-verdict';
 import {
@@ -45,7 +44,11 @@ const DEFAULT_PORT = 0;
  */
 export const DEFAULT_SETTLE_MS = IDLE_HYDRATE_TIMEOUT_MS;
 
-export const SHOT_DIR = join('.x', 'shot');
+// Re-exported, not re-declared: `cmd-shot.test.ts` and the island path both name them, and a
+// second declaration of a path or an allow-list rule is a second answer.
+export type { BootDevServer, ShotServer };
+export { allowHostsFrom, devServerFor, SHOT_DIR };
+
 export const SHOT_IMAGE = 'shot.png';
 export const SHOT_VERDICT = 'verdict.json';
 
@@ -164,24 +167,6 @@ const intFlag = (
     fallback,
   );
 
-/**
- * How `devServerFor` starts a scratch server. A parameter with a default rather than a direct
- * call, for the reason every `Runner` in this package is one: the failure path below — a boot that
- * throws, and the lock it has to hand back — is otherwise only reachable by breaking a real app.
- */
-export type BootDevServer = (input: {
-  readonly root: string;
-  readonly port: number;
-  readonly env: Readonly<Record<string, string | undefined>>;
-}) => Promise<{ readonly url: string; stop(): Promise<void> }>;
-
-export interface ShotServer {
-  readonly url: string;
-  /** Which server the picture is of. Reported, because the two have different failure modes. */
-  readonly origin: 'booted' | 'reused';
-  stop(): Promise<void>;
-}
-
 export interface ShotRun {
   readonly route: string;
   readonly outDir: string;
@@ -274,65 +259,6 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
   }
 }
 
-/**
- * One rule, two branches: photograph the `x dev` this checkout already has, or boot a scratch one.
- * Reusing is not a convenience — embedded Postgres is a single-writer directory, so a second boot
- * on one checkout is `X_DEV_ALREADY_RUNNING` and the picture would never be taken at all.
- */
-export async function devServerFor(
-  root: string,
-  env: Readonly<Record<string, string | undefined>>,
-  port: number,
-  boot: BootDevServer = (input) => startDev(input),
-): Promise<ShotServer> {
-  const services = resolveServices(root, env);
-  const file = Bun.file(lockPath(services.stateDir));
-  if (await file.exists()) {
-    const lock = parseLock(await file.text());
-    if (lock !== null && isProcessAlive(lock.pid)) {
-      return { url: lock.url, origin: 'reused', stop: () => Promise.resolve() };
-    }
-  }
-  const { release } = await preflight({
-    stateDir: services.stateDir,
-    port,
-    hostname: DEV_BINDING.hostname,
-    embeddedDb: services.db.mode === 'embedded',
-  });
-  // The directory is CLAIMED from here down — `preflight` returns holding it, never having merely
-  // looked — so a boot that throws has to give it back. `cmd-dev.ts` states the same rule at the
-  // same seam. Without it one failed `x shot` refused every later `x dev` and `x shot` on this
-  // checkout, naming a pid that had already exited. The original error is re-thrown untouched: a
-  // teardown must never replace the failure it is cleaning up after.
-  const dev = await boot({ root, port, env }).catch((error: unknown) => {
-    release();
-    throw error;
-  });
-  await writeLock(services.stateDir, {
-    pid: process.pid,
-    port,
-    url: dev.url,
-    startedAt: new Date().toISOString(),
-  });
-  return {
-    url: dev.url,
-    origin: 'booted',
-    async stop() {
-      clearLock(services.stateDir);
-      await dev.stop();
-    },
-  };
-}
-
-/** `--allow-hosts a.com,b.com` on top of the app's own host. Empty means the app's host alone. */
-export const allowHostsFrom = (url: string, extra: string | undefined): readonly string[] => {
-  const named = (extra ?? '')
-    .split(',')
-    .map((host) => host.trim())
-    .filter((host) => host.length > 0);
-  return [new URL(url).hostname, ...named];
-};
-
 export const shotResult = (artifacts: ShotArtifacts): CommandResult => ({
   ok: artifacts.verdict.ok,
   command: 'shot',
@@ -348,8 +274,9 @@ export const shotResult = (artifacts: ShotArtifacts): CommandResult => ({
 export const shotCommand: CliCommand = {
   spec: {
     name: 'shot',
-    summary: 'photograph one route from a real browser, with a verdict a picture cannot carry',
-    usage: 'x shot <route> [--port 0] [--out <dir>] [--no-full] [--settle 2000] [--json]',
+    summary: 'photograph one route, or one island in a state it declares, from a real browser',
+    usage:
+      'x shot <route> | --island <name> [--state <id>] [--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)' },
@@ -359,13 +286,31 @@ export const shotCommand: CliCommand = {
       { name: 'timeout', type: 'string', summary: 'ms one navigation may take' },
       { name: 'browser', type: 'string', summary: 'browser executable puppeteer-core launches' },
       { name: 'allow-hosts', type: 'string', summary: 'extra hosts the page may request' },
+      // A FLAG on `x shot` and never a second command: photographing a route and photographing a
+      // component are one job with two subjects, and a parallel command would be the second path
+      // axiom 1 refuses.
+      {
+        name: 'island',
+        type: 'string',
+        summary: 'photograph one island in every state it declares',
+      },
+      {
+        name: 'state',
+        type: 'string',
+        summary: 'one declared state of that island, not all of them',
+      },
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('shot', ctx.cwd).dir;
     // 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 route = readRoute(ctx.args.positionals[0]);
+    const island = flagString(ctx.args, 'island');
+    const positional = ctx.args.positionals[0];
+    if (island !== undefined && island !== '' && positional !== undefined) {
+      refuseRouteWithIsland(positional, island);
+    }
+    const route = island === undefined || island === '' ? 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);
@@ -375,11 +320,30 @@ export const shotCommand: CliCommand = {
         flag: 'browser',
         command: 'shot',
         reason: `no executable at "${executablePath}"`,
-        fix: `x shot ${route} --browser /usr/bin/chromium`,
+        fix: 'x shot / --browser /usr/bin/chromium',
       });
     }
     const out = flagString(ctx.args, 'out');
     const boot = (): Promise<ShotServer> => devServerFor(root, ctx.env, port);
+    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 }),
+          ...(flagString(ctx.args, 'allow-hosts') === undefined
+            ? {}
+            : { extraHosts: flagString(ctx.args, 'allow-hosts') }),
+          boot,
+        }),
+      );
+    }
     // Resolved before the boot for the same reason: an app with no browser installed must not pay
     // an embedded Postgres to be told to run `bun add -d puppeteer-core`.
     const driver = await appBrowser({

package/src/error-codes.ts

@@ -114,6 +114,13 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_SECRETS_EDIT_FAILED',
   'X_WORKSPACE_DEP_UNDECLARED',
   'X_SHOT_BROWSER_MISSING',
+  // `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.
+  'X_SHOT_ISLAND_STATES_EMPTY',
+  'X_SHOT_ISLAND_UNPHOTOGRAPHABLE',
+  'X_SHOT_ISLAND_UNSTUBBED_REQUEST',
+  'X_SHOT_ISLAND_MISSING',
   'X_GH_UNAVAILABLE',
   'X_GH_NOT_AUTHENTICATED',
   'X_GH_COMMAND_FAILED',
@@ -218,6 +225,10 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
   X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
   X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
+  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',
+  X_SHOT_ISLAND_MISSING: 'a declared island picture is not on disk',
   X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
   X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
   X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',