@ultimat3/cli 11.1.0 → 11.3.0

package/CLAUDE.md

@@ -166,7 +166,8 @@ 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 <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 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,66 @@ 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 |
+| `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 |
+
+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.3.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.3.0",
+    "@ultimat3/admin": "11.3.0",
+    "@ultimat3/ai": "11.3.0",
+    "@ultimat3/auth": "11.3.0",
+    "@ultimat3/cache": "11.3.0",
+    "@ultimat3/core": "11.3.0",
+    "@ultimat3/db": "11.3.0",
+    "@ultimat3/entity": "11.3.0",
+    "@ultimat3/flags": "11.3.0",
+    "@ultimat3/http": "11.3.0",
+    "@ultimat3/i18n": "11.3.0",
+    "@ultimat3/jobs": "11.3.0",
+    "@ultimat3/mail": "11.3.0",
+    "@ultimat3/manifest": "11.3.0",
+    "@ultimat3/mcp": "11.3.0",
+    "@ultimat3/money": "11.3.0",
+    "@ultimat3/policy": "11.3.0",
+    "@ultimat3/pwa": "11.3.0",
+    "@ultimat3/query": "11.3.0",
+    "@ultimat3/realtime": "11.3.0",
+    "@ultimat3/render": "11.3.0",
+    "@ultimat3/schema": "11.3.0",
+    "@ultimat3/scraping": "11.3.0",
+    "@ultimat3/seo": "11.3.0",
+    "@ultimat3/storage": "11.3.0",
+    "@ultimat3/testing": "11.3.0",
+    "@ultimat3/time": "11.3.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

@@ -2,11 +2,17 @@
 // of this package. `@ultimat3/scraping` declares the launcher's shape structurally (`cdp-port.ts`)
 // precisely so the framework can drive a browser without shipping one, and `x shot` is a CLI
 // command holding to the same bargain: the app installs `puppeteer-core`, the CLI asks for it.
+//
+// Two ways to get a browser, and the second is the one production uses. `localBrowser()` starts
+// Chrome in this container; `remoteBrowser({ cdpUrl })` ATTACHES to one somebody else is running,
+// which is what every stealth provider sells — a session created over their API answers with a
+// `wss://` CDP endpoint and a real, unfingerprintable Chromium behind it. `driver-cdp.ts` has
+// called attach its primary path since it shipped, and until now no CLI command could reach it.
 
 import { existsSync } from 'node:fs';
 import { UltimateError } from '@ultimat3/core';
 import type { CdpLauncherLike, ScrapeDriver } from '@ultimat3/scraping';
-import { localBrowser } from '@ultimat3/scraping';
+import { localBrowser, remoteBrowser } from '@ultimat3/scraping';
 
 /**
  * The one library this works against. Playwright is not an alternative and is not a flag:
@@ -18,6 +24,17 @@ export const BROWSER_PACKAGE = 'puppeteer-core';
 /** Where a browser binary is named when the flag does not name one. Read in this order. */
 export const BROWSER_PATH_VARS = ['PUPPETEER_EXECUTABLE_PATH', 'CHROME_PATH'] as const;
 
+/**
+ * Where a CDP endpoint is named when `--cdp-url` does not name one. `SCRAPE_CDP_URL` and not a
+ * name of this command's own: `@ultimat3/scraping`'s `remoteRequired` refusal already tells its
+ * reader `remoteBrowser({ cdpUrl: env.SCRAPE_CDP_URL })`, and a second spelling would make the
+ * package's own instruction wrong for the CLI that follows it.
+ */
+export const BROWSER_CDP_URL_VAR = 'SCRAPE_CDP_URL';
+
+/** The schemes a CDP endpoint can arrive as: a provider's `wss://`, a sidecar's `http://`. */
+const CDP_SCHEMES = ['ws:', 'wss:', 'http:', 'https:'] as const;
+
 /**
  * A missing browser is an instruction, not a crash (axiom 4). The cause distinguishes the two
  * shapes — nothing resolved, or something resolved that is not a launcher — while the fix is the
@@ -27,6 +44,8 @@ export class ShotBrowserMissingError extends UltimateError {
   constructor(input: { root: string; detail: string }) {
     super({
       code: 'X_SHOT_BROWSER_MISSING',
+      // The same install either way: attaching over CDP needs no Chrome on this box, but it still
+      // needs a client that speaks the protocol, and `puppeteer-core` is that client.
       cause: `x shot drives a real browser and ${BROWSER_PACKAGE} ${input.detail} from ${input.root}`,
       // One literal, not `bun add -d ${BROWSER_PACKAGE}`: `fix-scan.ts` can only read a fix that IS
       // one literal, and a fix line the gate cannot read is a fix line nothing holds to the
@@ -40,23 +59,41 @@ export class ShotBrowserMissingError extends UltimateError {
 /**
  * Structural, because this is somebody else's module: a namespace object, a CJS `default`, or a
  * transpiled interop wrapper are all shapes `import()` legitimately hands back, and only one
- * question decides — is there a `launch` to call?
+ * question decides — is the method this run needs there to call?
+ *
+ * WHICH method is the run's, not this function's. `cdp-port.ts` declares `launch` and `connect`
+ * both optional precisely so an attach-only provider SDK satisfies the port, and asking for
+ * `launch` when the run is going to `connect` would refuse exactly the library that works.
  */
-const launcherIn = (module: unknown): CdpLauncherLike | undefined => {
+const launcherIn = (module: unknown, method: 'launch' | 'connect'): CdpLauncherLike | undefined => {
   if (typeof module !== 'object' || module === null) return undefined;
-  const candidate = module as { launch?: unknown; default?: unknown };
-  if (typeof candidate.launch === 'function') return candidate as CdpLauncherLike;
+  const candidate = module as Record<string, unknown>;
+  if (typeof candidate[method] === 'function') return candidate as CdpLauncherLike;
   // `module.exports.default = module.exports` is a real CJS interop shape, so the self-reference is
   // refused rather than followed: one unbounded recursion here is a stack overflow instead of the
   // instruction this whole function exists to produce.
-  if (candidate.default === undefined || candidate.default === candidate) return undefined;
-  return launcherIn(candidate.default);
+  const inner = candidate['default'];
+  if (inner === undefined || inner === candidate) return undefined;
+  return launcherIn(inner, method);
 };
 
 export interface AppBrowserOptions {
   readonly root: string;
   /** `--browser`, then `PUPPETEER_EXECUTABLE_PATH`, then `CHROME_PATH`. */
   readonly executablePath?: string | undefined;
+  /**
+   * A CDP endpoint to ATTACH to. When it is set nothing is launched here and `executablePath` is
+   * not read: the browser is somebody else's, and closing it ends their session too — which
+   * `remoteBrowser()` does deliberately, so a provider stops billing for a run that ended.
+   */
+  readonly cdpUrl?: 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>;
@@ -78,6 +115,33 @@ export const executablePathFrom = (
 /** True when a named executable is really there — a bad `--browser` is refused before a boot. */
 export const browserBinaryExists = (path: string): boolean => existsSync(path);
 
+/** The endpoint a run will attach to, or `undefined` for "launch one here". */
+export const cdpUrlFrom = (
+  flag: string | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+): string | undefined => {
+  if (flag !== undefined && flag.length > 0) return flag;
+  const value = env[BROWSER_CDP_URL_VAR];
+  return value !== undefined && value.length > 0 ? value : undefined;
+};
+
+/**
+ * The scheme, checked here rather than at `connect()`. A `--cdp-url` naming an https page or a
+ * bare host is a typo, and a typo must not cost an embedded Postgres and a provider session to
+ * report — the same rule `--browser` follows against the filesystem one line above.
+ */
+export const cdpUrlProblem = (url: string): string | undefined => {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return 'is not a URL';
+  }
+  return CDP_SCHEMES.includes(parsed.protocol as (typeof CDP_SCHEMES)[number])
+    ? undefined
+    : `has scheme "${parsed.protocol}", and a CDP endpoint is ${CDP_SCHEMES.join(', ')}`;
+};
+
 /**
  * The app's `puppeteer-core`, as a `ScrapeDriver`. Resolved FROM THE APP ROOT rather than from
  * this module: `import('puppeteer-core')` here would find the CLI's own tree, which by design has
@@ -86,22 +150,40 @@ export const browserBinaryExists = (path: string): boolean => existsSync(path);
 export async function appBrowser(options: AppBrowserOptions): Promise<ScrapeDriver> {
   const resolve = options.resolve ?? ((specifier, from) => Bun.resolveSync(specifier, from));
   const load = options.load ?? ((path: string) => import(path) as Promise<unknown>);
+  const method = options.cdpUrl === undefined ? 'launch' : 'connect';
   let entry: string;
   try {
     entry = resolve(BROWSER_PACKAGE, options.root);
   } catch {
     throw new ShotBrowserMissingError({ root: options.root, detail: 'does not resolve' });
   }
-  const launcher = launcherIn(await load(entry));
+  const launcher = launcherIn(await load(entry), method);
   if (launcher === undefined) {
     throw new ShotBrowserMissingError({
       root: options.root,
-      detail: `resolved to ${entry}, which exports no launch()`,
+      detail: `resolved to ${entry}, which exports no ${method}()`,
+    });
+  }
+  if (options.cdpUrl !== undefined) {
+    return remoteBrowser({
+      launcher,
+      cdpUrl: options.cdpUrl,
+      // The viewport reaches `connect()` the same way it reaches `launch()` — through the
+      // pass-through slot — so `x shot --island`'s one-browser-per-viewport loop is unchanged by
+      // which half of the port a run took.
+      ...(options.viewport === undefined
+        ? {}
+        : { options: { defaultViewport: { ...options.viewport } } }),
     });
   }
   return localBrowser({
     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,151 @@
+// `--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;
+  readonly cdpUrl?: 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 }),
+      ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
+      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;
+  /** A provider's session, or a sidecar. One attach per viewport, memoised like a launch. */
+  readonly cdpUrl?: 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 }),
+        ...(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 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),
+  },
+});