@ultimat3/cli 11.1.0 → 11.3.0

package/src/cmd-shot.ts

@@ -11,17 +11,17 @@ import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
 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 { appBrowser } from './browser-launcher';
+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 { shotBrowserChoice } from './shot-browser';
+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 +45,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 +168,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 +260,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 +275,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)' },
@@ -358,33 +286,76 @@ export const shotCommand: CliCommand = {
       { name: 'settle', type: 'string', summary: 'ms to wait after load before capturing' },
       { name: 'timeout', type: 'string', summary: 'ms one navigation may take' },
       { name: 'browser', type: 'string', summary: 'browser executable puppeteer-core launches' },
+      {
+        name: 'cdp-url',
+        type: 'string',
+        summary: 'attach to a browser somebody else is running (a provider session, a sidecar)',
+      },
       { 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);
-    const executablePath = executablePathFrom(flagString(ctx.args, 'browser'), ctx.env);
-    if (executablePath !== undefined && !browserBinaryExists(executablePath)) {
-      throw new BadFlagError({
-        flag: 'browser',
-        command: 'shot',
-        reason: `no executable at "${executablePath}"`,
-        fix: `x shot ${route} --browser /usr/bin/chromium`,
-      });
-    }
+    // Which browser this run gets — start one here, or attach to one somebody else is running.
+    // Decided by `shot-browser.ts` over plain inputs, and decided HERE, before a dev server or a
+    // provider session exists to pay for a typo.
+    const { cdpUrl, executablePath } = shotBrowserChoice({
+      cdpFlag: flagString(ctx.args, 'cdp-url'),
+      browserFlag: flagString(ctx.args, 'browser'),
+      env: ctx.env,
+    });
     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 }),
+          ...(cdpUrl === undefined ? {} : { cdpUrl }),
+          ...(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({
       root,
       ...(executablePath === undefined ? {} : { executablePath }),
+      ...(cdpUrl === undefined ? {} : { cdpUrl }),
     });
     return shotResult(
       await runShot({

package/src/compile-externals.ts

@@ -8,10 +8,13 @@
  * `package.json` inside a `catch` — and both sit in `loadCtsDefault`, which only runs while Babel
  * loads a `.cts` CONFIG FILE. `solid-loader.ts` passes `babelrc: false, configFile: false`, so no
  * config file is ever loaded and neither line is reachable at run time. The bundler walks them
- * anyway, and that is the whole failure: Bun 1.3 (what CI pins and what `docker/Dockerfile` builds
- * on) refuses the build with `Could not resolve: "@babel/preset-typescript/package.json"`, while
- * Bun 1.4 bundles the unresolvable `require` as a runtime throw — so one tree compiled on a laptop
- * and did not in CI.
+ * anyway, and that is the whole failure: Bun 1.3 refuses the build with
+ * `Could not resolve: "@babel/preset-typescript/package.json"`, while Bun 1.4 bundles the
+ * unresolvable `require` as a runtime throw — so one tree compiled on a laptop and did not in CI.
+ * That skew is closed `As of 2026-08-20`: CI pins `1.4.x` (`.github/actions/setup/action.yml`),
+ * `docker/Dockerfile` builds on `oven/bun:1.4-slim` and `scripts/setup.ts` holds contributors to
+ * 1.4.0, so every builder now takes the second branch. The external stays regardless — it is the
+ * `--compile` graph that must not reach an unresolvable `require`, on either Bun.
  *
  * Marking the dead specifier external rather than the two live ones: `serve.ts` calls
  * `buildIslands` on every boot, unconditionally, so a binary with `@babel/core` external is a

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',

package/src/island-bundle.ts

@@ -10,7 +10,6 @@ import { renderThrowable } from '@ultimat3/core';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
-import { solidProductionPlugin } from './island-solid-production';
 import { islandStylesPlugin } from './island-styles';
 import { solidJsxPlugin } from './solid-loader';
 
@@ -84,12 +83,24 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       // classic `React.createElement` — emitted into a browser chunk that imports no React, with
       // `success: true` and no log. Every island shipped that way through five majors.
       //
-      // The other two close the same shape of failure — a wrong answer `Bun.build` reports as
-      // `success: true`: without the second, `target: 'browser'` resolves the `development`
-      // export condition and the chunk carries Solid's dev build; without the third, Bun's file
-      // loader resolves a `.module.scss` to its asset PATH, so `styles['x']` is `undefined` and
-      // every element renders unclassed.
-      plugins: [solidJsxPlugin, solidProductionPlugin, islandStylesPlugin],
+      // The second closes the same shape of failure — a wrong answer `Bun.build` reports as
+      // `success: true`: without it, Bun's file loader resolves a `.module.scss` to its asset
+      // PATH, so `styles['x']` is `undefined` and every element renders unclassed.
+      plugins: [solidJsxPlugin, islandStylesPlugin],
+      // The third one, and it is a `define` rather than the plugin this used to be: Bun selects
+      // the `development`/`production` export condition from the BUILD PROCESS's own `NODE_ENV`,
+      // and a defined `process.env.NODE_ENV` overrides it. Measured on 1.4.0, `solid-js` plus
+      // `solid-js/web` plus `solid-js/store`: unset → dev build, `test` → dev build, `production`
+      // → production build, this line → production build in all three, byte for byte.
+      //
+      // So without it a chunk built anywhere a container did not run — `x dev`, `x build` on a
+      // laptop, `bun test` — ships Solid's development build, and the island's own
+      // `process.env.NODE_ENV` reads `"development"` in the file a browser downloads.
+      //
+      // Pinned rather than inherited, because an island chunk is only ever built to be shipped:
+      // `x dev` serves the same chunk the container does, and bytes that depend on the ambient
+      // NODE_ENV are a content hash and a byte budget measured on a build nobody ships.
+      define: { 'process.env.NODE_ENV': '"production"' },
     });
   } catch (error) {
     throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });

package/src/island-harness-route.ts

@@ -0,0 +1,91 @@
+// Serving the harness. It is a `x dev` route and not a second server, for the reason `x shot`
+// reuses a running dev server at all: the chunks, the app's stylesheet registry and the island
+// bundle all live in the process that built them, and embedded Postgres is single-writer so there
+// can only be one of those per checkout.
+
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { html, json } from '@ultimat3/http';
+import type { IslandStatesManifest } from '@ultimat3/testing';
+import {
+  islandShotFile,
+  islandShotTargets,
+  islandStatesMatching,
+  islandStatesNames,
+  parseIslandAddress,
+} from '@ultimat3/testing';
+import { harnessPage, ISLAND_HARNESS_PATH } from './island-harness';
+import type { IslandSource } from './island-routes';
+
+/**
+ * A getter, never the manifests: `x dev` rebuilds on the watcher tick, and a set captured when the
+ * route was mounted would serve a state the author has since edited for the rest of the session.
+ * It is async because reading a states file is an `import()`, and one that throws is answered as a
+ * refusal rather than taking the dev server down.
+ */
+export type IslandStatesSource = () => Promise<readonly IslandStatesManifest[]>;
+
+const refused = (cause: string, fix: string): Response =>
+  json(
+    { ok: false, error: { code: 'X_SHOT_ISLAND_UNPHOTOGRAPHABLE', cause, fix } },
+    { status: 404 },
+  );
+
+export interface HarnessRouteInput {
+  readonly islands: IslandSource;
+  readonly states: IslandStatesSource;
+}
+
+/**
+ * `GET /_x/island?island=…&state=…&theme=…`. The address is parsed by the vocabulary's own
+ * `parseIslandAddress`, which is `islandAddress`'s inverse and is TOTAL — a mistyped theme falls
+ * back rather than throwing, because a page that renders an error over a typo turns a typo into a
+ * screenshot of the framework.
+ *
+ * An island or a state this process does not know is the one case that IS refused, and it can only
+ * mean the two processes disagree: `x shot` computed its picture list from the states files on disk
+ * and this server was booted against an older set.
+ */
+export function islandHarnessRoutes(input: HarnessRouteInput): readonly Route[] {
+  return [
+    {
+      method: 'GET',
+      path: ISLAND_HARNESS_PATH,
+      meta: { name: 'dev._x.island', auth: 'public', tags: ['dev'] },
+      handler: async (request: UltimateRequest): Promise<Response> => {
+        const address = parseIslandAddress(request.url.search);
+        const all = await input.states();
+        const manifest = islandStatesMatching(all, address.island)[0];
+        if (manifest === undefined) {
+          return refused(
+            `this dev server declares no island states for ${address.island === '' ? '(no island named)' : address.island} — it knows ${islandStatesNames(all).join(', ') || 'none'}`,
+            'restart x dev, then: x shot --island <name> --json',
+          );
+        }
+        // `wanted`, never a local called `state`: `bun run secret-compare` reads the NAME of a
+        // comparison's operands and `state` is on its list — an OAuth handshake state is compared
+        // under exactly that name, and this one is a screenshot filename stem.
+        const wanted = address.state;
+        const declared = manifest.states.find((one) => one.id === wanted);
+        const file = islandShotFile(manifest.name, wanted, address.theme);
+        const target = islandShotTargets(manifest).find((one) => one.file === file);
+        if (declared === undefined || target === undefined) {
+          return refused(
+            `${manifest.island} declares no state ${wanted === '' ? '(none named)' : wanted} in theme ${address.theme}`,
+            `x shot --island ${manifest.name} --state ${manifest.states[0]?.id ?? '<id>'} --json`,
+          );
+        }
+        // The chunk is looked up rather than built here: `x dev` already built every island at
+        // boot and rebuilds on the watcher tick, so a second build would be a second answer to
+        // "what code does this island run".
+        const chunk = input.islands().chunks.find((one) => one.file === manifest.island);
+        if (chunk === undefined) {
+          return refused(
+            `${manifest.island} is declared as an island's states file but this build has no chunk for it`,
+            `x g island ${manifest.name} --at ${manifest.island.split('/').slice(0, -1).join('/')}`,
+          );
+        }
+        return html(harnessPage({ target, state: declared, entry: chunk.url }));
+      },
+    },
+  ];
+}

package/src/island-harness-script.ts

@@ -0,0 +1,147 @@
+// The inline script the harness page runs BEFORE the island's chunk: the sealed network, the
+// pinned clock and the readiness signal. A classic `<script>` in `<head>` evaluates before any
+// module script, which is the only ordering in which a component's first `fetch` can be caught.
+//
+// A string and not a module, deliberately: this runs in the browser and the CLI has no bundler in
+// the path that serves a page. `@ultimat3/testing`'s `sealNetwork()` patches THIS process's
+// `globalThis.fetch` and cannot reach the page's realm.
+
+import type { IslandRouteStub } from '@ultimat3/testing';
+
+/**
+ * Consecutive animation frames with an unchanged activity counter before a page is called ready.
+ * QUIET, never zero in flight: a state whose fixture is deliberately `pending` has a request that
+ * never settles, so waiting for zero hangs forever — and a fixed sleep photographs whatever a slow
+ * machine had painted by then.
+ */
+export const QUIET_FRAMES = 3;
+
+/** The one global the CLI reads back. Namespaced so an app's own page state can never collide. */
+export const HARNESS_GLOBAL = '__xShot';
+
+/**
+ * Embedded as a JS string literal, so `<` is escaped: a `</script` anywhere inside a stub body
+ * would otherwise end the tag and the rest of the page would be parsed as markup. Escaping the
+ * character rather than the sequence is the total form — there is no second spelling of it.
+ */
+const embed = (value: unknown): string => JSON.stringify(value ?? null).replaceAll('<', '\\u003c');
+
+export interface HarnessScriptOptions {
+  readonly stubs: readonly IslandRouteStub[];
+  /** The frozen instant, with an explicit offset — the manifest's `now`. */
+  readonly now: string;
+  /** The IANA zone every unzoned `Intl.DateTimeFormat` in the page is given. */
+  readonly timeZone: string;
+}
+
+/**
+ * The seal. Four egress surfaces, and an unmatched request on any of them REJECTS while recording
+ * itself: 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.
+ *
+ * `activity` counts a request STARTING and a request SETTLING, which is what lets readiness be
+ * "nothing changed for N frames" rather than "nothing is in flight" — the second is unreachable for
+ * a `pending` fixture, which is a state an author declares on purpose.
+ */
+const sealScript = (stubs: readonly IslandRouteStub[]): string => `
+var W=window.${HARNESS_GLOBAL};var STUBS=${embed(stubs)};
+function bump(){W.activity+=1}
+function stubFor(method,path){var k=method.toUpperCase()+' '+path;
+for(var i=0;i<STUBS.length;i+=1){if(k.indexOf(STUBS[i].match)===0)return STUBS[i].respond}
+W.unstubbed.push(k);return null}
+// Pathname AND query: the vocabulary says a stub's \`match\` is a PREFIX, so \`'GET /api/quota'\`
+// catching \`/api/quota?window=day\` is a property of the key carrying the query, not of the match.
+function pathOf(url){try{var u=new URL(url,location.href);return u.pathname+u.search}catch(e){return String(url)}}
+function refuse(k){return new Error('x shot: no stub answers '+k+' — declare it in the state\\'s routes')}
+function answer(respond,k){
+if(respond===null)return Promise.reject(refuse(k));
+if(respond.kind==='pending')return new Promise(function(){});
+if(respond.kind==='offline')return Promise.reject(new TypeError('x shot: offline fixture for '+k));
+return Promise.resolve(new Response(JSON.stringify(respond.body===undefined?null:respond.body),
+{status:respond.status||200,headers:{'content-type':'application/json'}}))}
+window.fetch=function(input,init){
+var url=typeof input==='string'?input:(input&&input.url)||String(input);
+var method=(init&&init.method)||(typeof input==='object'&&input&&input.method)||'GET';
+var path=pathOf(url);var k=method.toUpperCase()+' '+path;
+var respond=stubFor(method,path);bump();
+return answer(respond,k).then(function(r){bump();return r},function(e){bump();throw e})};
+// A socket and an event stream have no stub vocabulary at all, so both are refused outright and
+// recorded: a live component that opened one would otherwise sit in its loading branch forever.
+window.WebSocket=function(url){W.unstubbed.push('WS '+url);throw refuse('WS '+url)};
+window.EventSource=function(url){W.unstubbed.push('SSE '+url);throw refuse('SSE '+url)};
+var RealXHR=window.XMLHttpRequest;
+window.XMLHttpRequest=function(){var xhr=new RealXHR();var open=xhr.open;
+xhr.open=function(method,url){W.unstubbed.push(String(method).toUpperCase()+' '+pathOf(url));
+return open.apply(xhr,arguments)};return xhr};
+// Nothing here serves a service worker, and one an earlier page registered would answer requests
+// this seal never sees. A no-op registration keeps a component that asks from throwing.
+if(navigator.serviceWorker)navigator.serviceWorker.register=function(){return Promise.resolve(undefined)};
+`;
+
+/**
+ * The clock, pinned in both halves. A harness that freezes the INSTANT and leaves the zone ambient
+ * renders `12:00` on one machine and `14:00` on the next, and the review diff then reports a
+ * component change that never happened — so the zone is filled in for every `Intl.DateTimeFormat`
+ * built without one, and the instant replaces the argumentless `new Date()`.
+ *
+ * `toLocaleString` on a Date is NOT covered: it reaches the engine's own Intl and not this global.
+ * The framework's rule is that no date is formatted without an explicit `timeZone`, so a component
+ * obeying it is pinned; one that does not is a blind spot the verdict names rather than hides.
+ */
+const clockScript = (now: string, timeZone: string): string => `
+var FIXED=${embed(Date.parse(now))};var ZONE=${embed(timeZone)};
+class ShotDate extends Date{constructor(){if(arguments.length===0)super(FIXED);else super(...arguments)}
+static now(){return FIXED}}
+window.Date=ShotDate;
+var RealDTF=Intl.DateTimeFormat;
+function zoned(options){return options&&options.timeZone?options:Object.assign({},options,{timeZone:ZONE})}
+function ShotDTF(locales,options){return new RealDTF(locales,zoned(options))}
+ShotDTF.prototype=RealDTF.prototype;
+ShotDTF.supportedLocalesOf=RealDTF.supportedLocalesOf.bind(RealDTF);
+Intl.DateTimeFormat=ShotDTF;
+`;
+
+/**
+ * Ready is quiet, not idle. Fonts first — a picture taken mid-swap photographs the fallback face —
+ * then `QUIET_FRAMES` consecutive frames in which nothing started and nothing settled.
+ */
+const readyScript = (): string => `
+var last=-1;var still=0;
+function tick(){var seen=W.activity;
+if(seen===last)still+=1;else{still=0;last=seen}
+if(still>=${QUIET_FRAMES}){W.ready=true;return}
+requestAnimationFrame(tick)}
+(document.fonts?document.fonts.ready:Promise.resolve()).then(function(){requestAnimationFrame(tick)});
+`;
+
+/** The whole prelude, in the one order that works: state, seal, clock, then the readiness watch. */
+export function harnessScript(options: HarnessScriptOptions): string {
+  return [
+    `window.${HARNESS_GLOBAL}={harness:true,activity:0,ready:false,unstubbed:[]};`,
+    sealScript(options.stubs),
+    clockScript(options.now, options.timeZone),
+    readyScript(),
+  ].join('\n');
+}
+
+/**
+ * What the CLI evaluates before every capture, as one expression — `CdpPageLike.evaluate` takes
+ * the string form only. Every clause is a fact a picture cannot carry: a host that never attached,
+ * a mount that rejected, a box of zero pixels, a box holding nothing, a request nobody stubbed.
+ *
+ * `selector` is the crop target the manifest declared; the island's own host element when absent.
+ */
+export const readinessProbe = (selector: string): string =>
+  `(function(){var W=window.${HARNESS_GLOBAL}||{};` +
+  'var host=document.querySelector("[data-x-island]");' +
+  `var box=document.querySelector(${JSON.stringify(selector)})||host;` +
+  'var r=box?box.getBoundingClientRect():{width:0,height:0,x:0,y:0};' +
+  'return{harness:W.harness===true,ready:W.ready===true,' +
+  'unstubbed:(W.unstubbed||[]).slice(),' +
+  'attached:host!==null&&document.body.contains(host),' +
+  'mounted:host!==null&&host.hasAttribute("data-x-mounted"),' +
+  'failed:host&&host.hasAttribute("data-x-failed")?host.getAttribute("data-x-failed"):null,' +
+  // Children OR text: a component that renders one text node has painted, and one that mounted
+  // and rendered nothing is the silence a non-zero box would otherwise read as success.
+  'filled:box?(box.children.length>0||(box.textContent||"").trim().length>0):false,' +
+  'box:{x:Math.round(r.x),y:Math.round(r.y),width:Math.round(r.width),height:Math.round(r.height)}};})()';

package/src/island-harness.ts

@@ -0,0 +1,98 @@
+// The harness document: one island, one state, one theme, mounted over the SEAM the framework
+// already has — `data-x-entry` for the chunk, `data-x-props` for the props, and
+// `@ultimat3/render`'s own hydration runtime to boot it. A second mounting mechanism here would be
+// a picture of something no page ever renders.
+
+// why: no Bun native takes a path apart; the surface is a segment of an app-root-relative path.
+import { basename } from 'node:path';
+import type { IslandDirective, Surface } from '@ultimat3/render';
+import {
+  emitIslandAttributes,
+  emitIslandProps,
+  hydrateRuntime,
+  islandModuleId,
+  SURFACES,
+} from '@ultimat3/render';
+import { stylesFor } from '@ultimat3/render/server';
+import type { IslandShotTarget, IslandState } from '@ultimat3/testing';
+import { harnessScript } from './island-harness-script';
+
+/** Where the harness lives in `x dev`'s own namespace, so no app route can shadow it. */
+export const ISLAND_HARNESS_PATH = '/_x/island';
+
+/**
+ * `idle`, and not because the picture should wait: it is the only strategy whose runtime boots an
+ * island nothing has scrolled to or clicked, and reusing a shipped strategy is what keeps the
+ * `data-x-mounted` / `data-x-failed` markers — the two facts a picture cannot carry — landing here
+ * exactly as they land on a real page.
+ */
+const HARNESS_STRATEGY = 'idle';
+
+/**
+ * `apps/web/app/settings/settings.island.tsx` → `app`. The CSS a document carries is per surface
+ * (axiom 6 applied to bytes the browser parses), so a `site/` island photographed against `app/`'s
+ * stylesheet would be a picture of styling that page never receives.
+ */
+export function surfaceOf(island: string): Surface | null {
+  const segment = island.split('/')[2];
+  return SURFACES.find((surface) => surface === segment) ?? null;
+}
+
+/**
+ * The frame, and every rule in it is about what a REVIEWER sees. Animations and transitions are
+ * off because a picture taken mid-transition is a picture of a moment no user experiences; the
+ * caret is invisible because a focused input blinks and two otherwise identical runs then differ.
+ * Colours are semantic tokens, never literals — the app's own global layer defines them.
+ */
+const FRAME_STYLE = `
+*,*::before,*::after{animation:none !important;transition:none !important;
+scroll-behavior:auto !important;caret-color:transparent !important}
+html{background:rgb(var(--color-bg) / 1)}
+body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+background:rgb(var(--color-bg) / 1)}
+#x-shot-frame{padding:var(--space-4, 16px);max-width:100%;box-sizing:border-box}
+`.trim();
+
+export interface HarnessPageInput {
+  readonly target: IslandShotTarget;
+  readonly state: IslandState;
+  /** The built chunk's immutable URL — what `data-x-entry` carries and what the runtime imports. */
+  readonly entry: string;
+}
+
+/**
+ * One address, one document, and every address is a FULL PAGE LOAD. Switching islands or states
+ * client-side would carry the previous state's fixtures, its resolved resources and its mounted
+ * DOM into the next picture, which is the one way a screenshot tool can lie about its own subject.
+ */
+export function harnessPage(input: HarnessPageInput): string {
+  const moduleId = islandModuleId(basename(input.target.island));
+  const directive: IslandDirective = {
+    islandId: moduleId,
+    moduleId,
+    strategy: HARNESS_STRATEGY,
+    entry: input.entry,
+    props: input.state.props,
+  };
+  const css = stylesFor(surfaceOf(input.target.island));
+  return [
+    '<!doctype html>',
+    `<html lang="en" data-theme="${input.target.theme}">`,
+    '<head><meta charset="utf-8">',
+    `<title>${input.target.name} · ${input.target.state} · ${input.target.theme}</title>`,
+    css.length === 0 ? '' : `<style>${css}</style>`,
+    `<style>${FRAME_STYLE}</style>`,
+    // Before the body and before every module script, which is the only ordering in which the
+    // seal can catch a component's first request.
+    `<script>${harnessScript({
+      stubs: input.state.routes,
+      now: input.target.now,
+      timeZone: input.target.timeZone,
+    })}</script>`,
+    '</head><body>',
+    `<div id="x-shot-frame"><div ${emitIslandAttributes(directive)}></div></div>`,
+    emitIslandProps(directive),
+    hydrateRuntime([directive]),
+    '</body></html>',
+  ].join('');
+}