@ultimat3/cli 19.4.0 → 20.1.0

package/src/island-shot.ts

@@ -1,270 +1,60 @@
-// `x shot --island <name>` — one component, in the states it declares, photographed one address at
-// a time. The order matters and is the whole design: the complete expected picture list is
-// computed from the states file BEFORE a browser exists, and what landed on disk is diffed against
-// that list afterwards, so "produced nothing and exited 0" is a state this command can refuse.
+// `x shot --island` — the RUN: which islands, in which order, and which artifacts land. One
+// picture at a time is `island-capture.ts`; the order here is the whole design, because the
+// complete expected picture list is computed from the states files BEFORE a browser exists and
+// what landed on disk is diffed against that list afterwards, so "produced nothing and exited 0"
+// is a state this command can refuse.
+//
+// A sweep never aborts on a failure: every state the app CAN photograph is captured, every verdict
+// 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.
 
 // why: no Bun native joins a path; `Bun.write` and `Bun.file` both take one already joined.
 import { join } from 'node:path';
 import { finiteCount } from '@ultimat3/core';
-import type { CaptureClip, ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
-import { systemScrapeClock } from '@ultimat3/scraping';
-import type { IslandShotTarget, IslandStatesManifest, IslandViewport } from '@ultimat3/testing';
-import { islandShotTargets, islandStatesFile } from '@ultimat3/testing';
-import { ISLAND_HARNESS_PATH } from './island-harness';
-import { readinessProbe } from './island-harness-script';
-import {
-  IslandRequestUnstubbedError,
-  IslandShotsMissingError,
-  IslandUnphotographableError,
-} from './island-shot-errors';
-import type { IslandArtifacts, IslandReadiness, IslandStateShot } from './island-verdict';
-import { buildIslandVerdict, islandVerdictJson, parseReadiness } from './island-verdict';
+import type { IslandShotTarget, IslandStatesManifest } from '@ultimat3/testing';
+import { islandShotPlan, islandShotTargets } from '@ultimat3/testing';
+import type { IslandCaptureRun } from './island-capture';
+import { captureIslandState, MIN_SHOT_BYTES } from './island-capture';
+import { IslandShotsMissingError } from './island-shot-errors';
+import { ISLAND_INDEX, renderIslandIndex } from './island-shot-index';
+import type { IslandArtifacts, IslandStateShot, IslandSweepArtifacts } from './island-verdict';
+import { buildIslandVerdict, islandVerdictJson } from './island-verdict';
 import type { ShotServer } from './shot-server';
-import { allowHostsFrom } from './shot-server';
-import { SETTLE_POLL_MS, settleReadiness } from './shot-settle';
 
 /** Where a component's pictures land, under the same `.x/shot` tree a route's picture does. */
 export const ISLAND_SHOT_DIR = 'island';
 export const ISLAND_VERDICT = 'verdict.json';
 
-/**
- * A backstop and not a quality bar: it catches the answers that are not an image at all — a driver
- * that hands back a handshake, an empty buffer, a PNG signature with nothing behind it. A real
- * capture of any viewport clears it by an order of magnitude.
- */
-export const MIN_SHOT_BYTES = 512;
+// Re-exported, not re-declared: the capture's own vocabulary is what a caller and a test both
+// name, and a second spelling of a browser or a floor would be a second answer.
+export type { IslandBrowser } from './island-capture';
+export { ISLAND_CROP_MARGIN_PX, MIN_SHOT_BYTES, photographFault } from './island-capture';
+export { ISLAND_INDEX } from './island-shot-index';
 
-/**
- * A browser sized to one viewport. A FUNCTION and not a driver, because the shipped browser port
- * takes the viewport as a LAUNCH option (`LocalBrowserOptions.options`) and a state declares its
- * own — so "photograph this state at 480x320" is a different browser, not a different call.
- */
-export type IslandBrowser = (viewport: IslandViewport) => Promise<ScrapeDriver>;
-
-export interface IslandShotRun {
-  readonly manifest: IslandStatesManifest;
+export interface IslandSweepRun extends IslandCaptureRun {
+  /** Every island this run photographs. One entry is the `--island <name>` form. */
+  readonly manifests: readonly IslandStatesManifest[];
   /**
-   * `--state`, or every declared state when absent. The caller validates it: `defineIslandStates`
-   * refuses a manifest with no states, so the only way this expansion comes back empty is a filter
-   * naming a state that does not exist — which is a typo, and belongs to the flag that made it.
+   * `--state`, or every declared state when absent. The caller validates it against ONE manifest:
+   * `defineIslandStates` refuses a manifest with no states, so the only way this expansion comes
+   * back empty is a filter naming a state that does not exist — a typo, and it belongs to the flag
+   * that made it.
    */
   readonly state?: string | undefined;
-  readonly outDir: string;
-  readonly driver: IslandBrowser;
   readonly boot: () => Promise<ShotServer>;
-  readonly settleMs: number;
-  readonly timeoutMs: number;
-  readonly extraHosts?: string | undefined;
   readonly minBytes?: number | undefined;
   readonly now?: (() => Date) | undefined;
 }
 
+/** The one-island form, kept as its own shape because its artifacts name one directory. */
+export interface IslandShotRun extends Omit<IslandSweepRun, 'manifests'> {
+  readonly manifest: IslandStatesManifest;
+}
+
 const quietly = async (stop: () => Promise<void>): Promise<void> => {
   await stop().catch(() => undefined);
 };
 
-/**
- * Every assertion that has to hold before a shutter opens, in the order a failure is most useful
- * in. Each one names a fact the picture would have hidden rather than shown: an absent harness is
- * a dev server that does not know this island, an unattached host photographs the frame's
- * background, a zero box photographs whatever is behind it, and an empty box is a component that
- * mounted and rendered nothing — every one of which comes out as a plausible image of the wrong
- * thing.
- */
-interface Refusal {
-  readonly reason: string;
-  readonly fix: string;
-}
-
-/**
- * The first assertion that does not hold, in the order a failure is most useful in — or
- * `undefined`, which is the only way a shutter opens. Each clause names a fact the picture would
- * have hidden rather than shown: an absent harness is a dev server that does not know this island,
- * an unattached host photographs the frame's background, a zero box photographs whatever is behind
- * it, and an empty box is a component that mounted and rendered nothing. Every one of them comes
- * out as a plausible image of the wrong thing.
- *
- * A value and not a throw, so the whole ladder is one pure function a test can walk.
- */
-export function photographFault(
-  target: IslandShotTarget,
-  seen: IslandReadiness | null,
-): Refusal | undefined {
-  const settle = `x shot --island ${target.name} --settle 8000 --json`;
-  if (seen === null) {
-    return {
-      reason: 'answered no readiness probe at all, so nothing about the page can be asserted',
-      fix: `x shot --island ${target.name} --state ${target.state} --timeout 60000 --json`,
-    };
-  }
-  if (!seen.harness) {
-    return {
-      reason:
-        'was served a document that is not the shot harness — the dev server this run reused was booted against a different set of states files',
-      fix: 'restart x dev, then run this command again',
-    };
-  }
-  if (!seen.attached) {
-    return { reason: 'rendered no [data-x-island] host element', fix: hostFix(target) };
-  }
-  if (seen.failed !== null) {
-    return {
-      reason: `mounted and its mount() REJECTED: ${seen.failed}`,
-      fix: `x shot --island ${target.name} --state ${target.state} --json   # the verdict carries the throw and its frame`,
-    };
-  }
-  if (!seen.mounted) {
-    return { reason: 'did not finish mounting inside the settle window', fix: settle };
-  }
-  if (!seen.ready) {
-    return {
-      reason:
-        'never went quiet: something kept starting or settling requests for the whole settle window',
-      fix: settle,
-    };
-  }
-  if (seen.box.width === 0 || seen.box.height === 0) {
-    return {
-      reason: `has a ${seen.box.width}x${seen.box.height} bounding box, so the picture would be of whatever is behind it`,
-      fix: cropFix(target),
-    };
-  }
-  if (!seen.filled) {
-    return {
-      reason:
-        'has a box with no child elements and no text in it — it mounted and rendered nothing',
-      fix: cropFix(target),
-    };
-  }
-  return undefined;
-}
-
-/**
- * The capture rectangle for a readiness answer, in PAGE coordinates.
- *
- * `seen` is non-null and its box has area by the time this is reached — `photographFault` refuses
- * both above, and it refuses them BEFORE the shutter for exactly this reason: a zero-area clip is
- * `X_SCRAPE_CAPTURE_CLIP_EMPTY` from the port, which is a worse report of the same fault than
- * "rendered nothing". The `?? 0` pair is the parser's floor and not a second opinion.
- */
-const clipFor = (seen: IslandReadiness | null): CaptureClip => ({
-  x: (seen?.box.x ?? 0) + (seen?.scroll.x ?? 0),
-  y: (seen?.box.y ?? 0) + (seen?.scroll.y ?? 0),
-  width: seen?.box.width ?? 0,
-  height: seen?.box.height ?? 0,
-});
-
-const hostFix = (target: IslandShotTarget): string =>
-  `in ${islandStatesFile(target.island)} set island to a path that exports mount(el, props)`;
-
-const cropFix = (target: IslandShotTarget): string =>
-  `in ${islandStatesFile(target.island)} set target to a selector the component really renders, or widen the state's props`;
-
-/**
- * One address, one full page load, one picture. Never a client-side switch between states: the
- * previous state's fixtures, its resolved resources and its mounted DOM would ride into the next
- * picture, which is the one way a screenshot tool can lie about its own subject.
- *
- * A session PER TARGET, and it costs a browser launch each: `page.console()` and `page.pageErrors()`
- * are bounded rings over the whole SESSION, so a shared one would file state A's console errors
- * under state B — and per-state attribution is the half of this artifact that gates.
- */
-async function captureOne(
-  options: IslandShotRun,
-  server: ShotServer,
-  target: IslandShotTarget,
-  floor: number,
-): Promise<IslandStateShot> {
-  const url = new URL(`${ISLAND_HARNESS_PATH}${target.query}`, server.url).toString();
-  let session: ScrapeSession | undefined;
-  try {
-    const driver = await options.driver(target.viewport);
-    session = await driver.open({
-      name: 'x shot --island',
-      rules: { allowHosts: allowHostsFrom(server.url, options.extraHosts) },
-      clock: systemScrapeClock,
-      timeoutMs: options.timeoutMs,
-    });
-    const page = session.page;
-    // BEFORE the navigation, so the first paint already has it: `prefers-color-scheme` is a live
-    // media query, and the theme a component resolves on mount is the one it will keep.
-    //
-    // This is the INPUT and the harness's `data-theme` attribute is the OUTCOME, and both are set
-    // deliberately. The attribute is right for a component that READS a theme it does not own; the
-    // preference is the only thing that reaches one that RESOLVES its own. `examples/dummy`'s
-    // settings island is the second kind — its state's `theme` prop is `'system'`, so on mount it
-    // DELETES the attribute the harness set, both pictures fall through to `:root`, and the two
-    // came back byte-identical with the same md5 (issue #338). Re-setting the attribute after
-    // readiness is not the repair: it photographs a state the component would never reach.
-    await page.colorScheme(target.theme);
-    await page.goto(url, { timeout: options.timeoutMs });
-    const expression = readinessProbe(target.target ?? '[data-x-island]');
-    const probe = (): Promise<IslandReadiness | null> =>
-      page
-        .evaluate(expression)
-        .then(parseReadiness)
-        .catch(() => null);
-    const seen = await settleReadiness(probe, {
-      windowMs: options.settleMs,
-      pollMs: SETTLE_POLL_MS,
-    });
-    // Ahead of every other assertion about the picture: a component whose fetch went unanswered
-    // paints its own loading branch, and the picture then shows a fixture gap dressed up as a
-    // real component state. The list is the page's own, published by the seal.
-    if (seen !== null && seen.unstubbed.length > 0) {
-      throw new IslandRequestUnstubbedError({
-        island: target.island,
-        state: target.state,
-        requests: seen.unstubbed,
-        statesFile: islandStatesFile(target.island),
-      });
-    }
-    const fault = photographFault(target, seen);
-    if (fault !== undefined) {
-      throw new IslandUnphotographableError({
-        island: target.island,
-        state: target.state,
-        theme: target.theme,
-        ...fault,
-      });
-    }
-    // The COMPONENT, not the viewport it happens to sit in — the crop this feature was designed
-    // around, and which nothing passed until 2026-08-26 (issue #338). The rectangle is the
-    // readiness probe's own box, which is the crop target the manifest declared, translated from
-    // the DOM's viewport coordinates into the page coordinates a capture clip is in.
-    //
-    // The clip ALONE. `fullPage: false` beside it is accepted — `assertCaptureFraming` refuses only
-    // `=== true`, and `cdp-target.ts` sends `{ clip }` and nothing else either way, so all four
-    // pictures really were written with the pair — but it is a field that says nothing: the two
-    // are exclusive, and spelling out the default of the one you did not ask for reads as a choice.
-    const bytes = await page.screenshot({ clip: clipFor(seen) });
-    if (bytes.byteLength < floor) {
-      throw new IslandUnphotographableError({
-        island: target.island,
-        state: target.state,
-        theme: target.theme,
-        reason: `produced ${bytes.byteLength} bytes, under the ${floor}-byte floor — that is not an image`,
-        fix: `x shot --island ${target.name} --browser /usr/bin/chromium --json`,
-      });
-    }
-    await Bun.write(join(options.outDir, target.file), bytes);
-    return {
-      state: target.state,
-      theme: target.theme,
-      file: target.file,
-      bytes: bytes.byteLength,
-      box: seen?.box ?? { x: 0, y: 0, width: 0, height: 0 },
-      mounted: seen?.mounted === true,
-      unstubbed: seen?.unstubbed ?? [],
-      console: page.console(),
-      pageErrors: page.pageErrors(),
-    };
-  } finally {
-    const open = session;
-    if (open !== undefined) await quietly(() => open.close());
-  }
-}
-
 /** Declared pictures that are not on disk. Read from the EXPANSION, never from the loop's beliefs. */
 export async function missingShots(
   outDir: string,
@@ -278,34 +68,34 @@ export async function missingShots(
 }
 
 /**
- * Boot (or find) the server, photograph every declared state, write the pictures and the verdict,
- * then refuse if any declared picture is absent. The driver and the boot are ARGUMENTS for the
- * reason `runShot`'s are: `bun test` drives this with a fake browser and a stub server, so the
- * whole command is proved on a machine with no Chrome.
+ * Boot (or find) the server, photograph every declared state of every island named, write the
+ * pictures, the per-island verdicts and the index, then refuse if any declared picture is absent.
+ * The driver and the boot are ARGUMENTS for `runShot`'s reason: `bun test` drives this with a fake
+ * browser and a stub server, so the whole command is proved on a machine with no Chrome.
  */
-export async function runIslandShot(options: IslandShotRun): Promise<IslandArtifacts> {
+export async function runIslandSweep(options: IslandSweepRun): Promise<IslandSweepArtifacts> {
   // A Set and not an `===`: `bun run secret-compare` reads the NAME of a comparison's operands and
   // `state` is on its list, because an OAuth handshake state is compared under exactly that name.
   // This one is a screenshot filename stem, and the membership test says so.
   const chosen = options.state === undefined ? null : new Set([options.state]);
-  const targets = islandShotTargets(options.manifest).filter(
-    (target) => chosen === null || chosen.has(target.state),
-  );
+  const wanted = (target: IslandShotTarget): boolean => chosen === null || chosen.has(target.state);
+  const targets = islandShotPlan(options.manifests).filter(wanted);
   // Before the boot, and before a browser: `bytes.byteLength < NaN` is false for every picture, so
   // an unchecked floor does not lower the backstop — it removes it, and "produced nothing and
   // exited 0" is the one outcome a reader cannot tell from success. 0 stays legal and is what
   // `island-shot.test.ts` passes: the fake driver answers an 8-byte PNG signature.
-  const floor = finiteCount('runIslandShot', 'minBytes', options.minBytes ?? MIN_SHOT_BYTES);
+  const floor = finiteCount('runIslandSweep', 'minBytes', options.minBytes ?? MIN_SHOT_BYTES);
   const server = await options.boot();
   const shots: IslandStateShot[] = [];
   const failures: unknown[] = [];
   try {
     for (const target of targets) {
-      // A state that cannot be photographed does not stop the run: the reader wants every picture
-      // the app CAN produce plus a named reason for each one it cannot, and the missing-shot gate
-      // below is what turns those reasons into a non-zero exit.
+      // A state that cannot be photographed does not stop the run — not the next state, and not
+      // the next ISLAND. The reader wants every picture the app CAN produce plus a named reason
+      // for each one it cannot, and the missing-shot gate below is what turns those reasons into
+      // a non-zero exit.
       try {
-        shots.push(await captureOne(options, server, target, floor));
+        shots.push(await captureIslandState(options, server, target, floor));
       } catch (error) {
         failures.push(error);
       }
@@ -313,30 +103,70 @@ export async function runIslandShot(options: IslandShotRun): Promise<IslandArtif
   } finally {
     await quietly(() => server.stop());
   }
-  const missing = await missingShots(options.outDir, targets);
-  const verdict = buildIslandVerdict({
-    island: options.manifest.island,
-    name: options.manifest.name,
-    server: server.origin,
-    capturedAt: (options.now ?? (() => new Date()))().toISOString(),
-    expected: targets,
-    shots,
-    missing,
-  });
-  const dir = join(options.outDir, options.manifest.name);
-  const verdictFile = join(dir, ISLAND_VERDICT);
-  await Bun.write(verdictFile, `${JSON.stringify(islandVerdictJson(verdict), null, 2)}\n`);
+  const capturedAt = (options.now ?? (() => new Date()))().toISOString();
+  const pairs = [];
+  for (const manifest of options.manifests) {
+    const expected = islandShotTargets(manifest).filter(wanted);
+    const verdict = buildIslandVerdict({
+      island: manifest.island,
+      name: manifest.name,
+      server: server.origin,
+      capturedAt,
+      expected,
+      shots: shots.filter((shot) => expected.some((target) => target.file === shot.file)),
+      missing: await missingShots(options.outDir, expected),
+    });
+    await Bun.write(
+      join(options.outDir, manifest.name, ISLAND_VERDICT),
+      `${JSON.stringify(islandVerdictJson(verdict), null, 2)}\n`,
+    );
+    pairs.push({ manifest, verdict });
+  }
+  // The index is written for a single-island run too: the file that says what a picture IS cannot
+  // be a property of how many islands the reader asked for.
+  const indexFile = join(options.outDir, ISLAND_INDEX);
+  await Bun.write(
+    indexFile,
+    renderIslandIndex({ pairs, capturedAt, blind: pairs[0]?.verdict.blind ?? [] }),
+  );
+  const artifacts: IslandSweepArtifacts = {
+    verdicts: pairs.map((pair) => pair.verdict),
+    dir: options.outDir,
+    indexFile,
+    ok: pairs.every((pair) => pair.verdict.ok),
+  };
   // The first failure is re-thrown ONLY when it explains a missing picture. A run that took every
   // declared picture and also logged a failure is a contradiction; the artifact is what decides.
-  if (missing.length > 0) {
+  const short = artifacts.verdicts.find((verdict) => verdict.missing.length > 0);
+  if (short !== undefined) {
     const first = failures[0];
     if (first !== undefined) throw first;
     throw new IslandShotsMissingError({
-      island: options.manifest.name,
-      missing,
-      expected: targets.length,
-      dir,
+      island: short.name,
+      missing: short.missing,
+      expected: short.expected.length,
+      dir: join(options.outDir, short.name),
+    });
+  }
+  return artifacts;
+}
+
+/**
+ * One island. The sweep with a single manifest, so there is one capture loop and one artifact
+ * writer in this package — two would be two answers to "what did this run produce".
+ */
+export async function runIslandShot(options: IslandShotRun): Promise<IslandArtifacts> {
+  const { manifest, ...rest } = options;
+  const artifacts = await runIslandSweep({ ...rest, manifests: [manifest] });
+  const verdict = artifacts.verdicts[0];
+  if (verdict === undefined) {
+    throw new IslandShotsMissingError({
+      island: manifest.name,
+      missing: islandShotTargets(manifest).map((target) => target.file),
+      expected: manifest.states.length,
+      dir: join(options.outDir, manifest.name),
     });
   }
-  return { verdict, dir, verdictFile };
+  const dir = join(options.outDir, manifest.name);
+  return { verdict, dir, verdictFile: join(dir, ISLAND_VERDICT), indexFile: artifacts.indexFile };
 }

package/src/island-verdict.ts

@@ -18,6 +18,7 @@ export const ISLAND_SHOT_MESSAGE_KEYS = [
   'cli.shot.island.picture',
   'cli.shot.island.verdict',
   'cli.shot.island.state',
+  'cli.shot.island.index',
   'cli.shot.island.blind.crop',
   'cli.shot.island.blind.locale',
 ] as const;
@@ -66,6 +67,19 @@ export interface IslandReadiness {
    * answer there.
    */
   readonly scroll: { readonly x: number; readonly y: number };
+  /**
+   * Whether the crop target's own content is wider or taller than its box — `scrollWidth >
+   * clientWidth` on the element the picture is of. RECORDED, never gating: content spilling out of
+   * its box is the single most common ugly-UI symptom and a pixel-tight PNG frequently cannot show
+   * it, so a reader needs the fact stated. Gating on it would be gating on a layout opinion.
+   */
+  readonly overflow: { readonly x: boolean; readonly y: boolean };
+  /**
+   * The scrollable extent of the document, in PAGE coordinates. The one bound a crop margin can be
+   * clamped against: a margin that runs off the page asks CDP to photograph coordinates no content
+   * is at, and a rectangle a driver silently resolves is the picture lying about its own subject.
+   */
+  readonly page: { readonly width: number; readonly height: number };
 }
 
 const readinessSchema: StandardSchemaV1<unknown, IslandReadiness> = t.object({
@@ -78,6 +92,8 @@ const readinessSchema: StandardSchemaV1<unknown, IslandReadiness> = t.object({
   filled: t.boolean,
   box: t.object({ x: t.number, y: t.number, width: t.number, height: t.number }),
   scroll: t.object({ x: t.number, y: t.number }),
+  overflow: t.object({ x: t.boolean, y: t.boolean }),
+  page: t.object({ width: t.number, height: t.number }),
 }) as unknown as StandardSchemaV1<unknown, IslandReadiness>;
 
 /**
@@ -101,9 +117,27 @@ export interface IslandStateShot {
   readonly unstubbed: readonly string[];
   readonly console: readonly ConsoleLine[];
   readonly pageErrors: readonly PageError[];
+  /**
+   * The crop target's own overflow at the moment the shutter opened. On `IslandStateShot` and in
+   * `--json` because a PNG cannot carry it — and deliberately absent from `stateShotOk` below.
+   */
+  readonly overflow: { readonly x: boolean; readonly y: boolean };
 }
 
-/** One state's picture is clean when nothing on the page logged, threw, or went unanswered. */
+/**
+ * Console lines at `warn`. Its own reader rather than a second field: `page.console()` already
+ * records every level and `shotJson` already ships the whole array, so a `warnings` array beside
+ * `console` would be one fact in two places — what was missing is that nobody COUNTED them.
+ */
+export const stateShotWarnings = (shot: IslandStateShot): readonly ConsoleLine[] =>
+  shot.console.filter((line) => line.level === 'warn');
+
+/**
+ * One state's picture is clean when nothing on the page logged an ERROR, threw, or went
+ * unanswered. A console WARNING and an overflowing box are recorded beside it and read by neither
+ * clause on purpose: a signal that fails a run is a signal an author switches off, and both of
+ * these are facts a reviewer judges rather than verdicts a machine can reach.
+ */
 export const stateShotOk = (shot: IslandStateShot): boolean =>
   shot.mounted &&
   shot.unstubbed.length === 0 &&
@@ -146,6 +180,9 @@ const shotJson = (shot: IslandStateShot): JsonValue => ({
   box: { x: shot.box.x, y: shot.box.y, width: shot.box.width, height: shot.box.height },
   mounted: shot.mounted,
   ok: stateShotOk(shot),
+  // Counted, never gating — `ok` above is computed without either of them.
+  warnings: stateShotWarnings(shot).length,
+  overflow: { x: shot.overflow.x, y: shot.overflow.y },
   unstubbed: [...shot.unstubbed],
   console: shot.console.map((line) => ({ level: line.level, text: line.text, at: line.at })),
   pageErrors: shot.pageErrors.map((error) => ({
@@ -175,6 +212,8 @@ export interface IslandArtifacts {
   /** Absolute path of the directory the pictures and the verdict were written to. */
   readonly dir: string;
   readonly verdictFile: string;
+  /** The gallery index, written for a single-island run as well as for a sweep. */
+  readonly indexFile: string;
 }
 
 export function islandShotLines(artifacts: IslandArtifacts): readonly string[] {
@@ -192,9 +231,59 @@ export function islandShotLines(artifacts: IslandArtifacts): readonly string[] {
     ...verdict.missing.map((file) => msg('cli.shot.island.missing', { file })),
     msg('cli.shot.island.picture', { path: artifacts.dir }),
     msg('cli.shot.island.verdict', { path: artifacts.verdictFile }),
+    msg('cli.shot.island.index', { path: artifacts.indexFile }),
+  ];
+}
+
+export interface IslandSweepArtifacts {
+  readonly verdicts: readonly IslandVerdict[];
+  /** The island root — every island's own directory sits under it, and so does the index. */
+  readonly dir: string;
+  readonly indexFile: string;
+  readonly ok: boolean;
+}
+
+/**
+ * The sweep's own lines: one per state per island, every missing picture, then the index. The
+ * per-island verdict files are named by the index rather than repeated here — a sweep over twenty
+ * islands would otherwise print twenty paths nobody reads before the one that matters.
+ */
+export function islandSweepLines(artifacts: IslandSweepArtifacts): readonly string[] {
+  return [
+    ...artifacts.verdicts.flatMap((verdict) => [
+      ...verdict.shots.map((shot) =>
+        msg('cli.shot.island.state', {
+          state: `${verdict.name}/${shot.state}`,
+          theme: shot.theme,
+          width: shot.box.width,
+          height: shot.box.height,
+          file: shot.file,
+        }),
+      ),
+      ...verdict.missing.map((file) => msg('cli.shot.island.missing', { file })),
+    ]),
+    msg('cli.shot.island.picture', { path: artifacts.dir }),
+    msg('cli.shot.island.index', { path: artifacts.indexFile }),
   ];
 }
 
+/**
+ * The same two keys the one-island summary uses, with the island NAMES joined — never a count with
+ * a hand-written plural in it, which would be a user-facing string built in code rather than in
+ * the catalog. A reader who asked for every island is told which ones there were.
+ */
+export function islandSweepSummary(artifacts: IslandSweepArtifacts): string {
+  const island = artifacts.verdicts.map((verdict) => verdict.name).join(', ');
+  const taken = artifacts.verdicts.reduce((total, verdict) => total + verdict.shots.length, 0);
+  const expected = artifacts.verdicts.reduce(
+    (total, verdict) => total + verdict.expected.length,
+    0,
+  );
+  return artifacts.ok
+    ? msg('cli.shot.island.ok', { island, pictures: taken })
+    : msg('cli.shot.island.failed', { island, taken, expected });
+}
+
 /** The one line a reader sees first, and it names the gating fact rather than the file count. */
 export const islandShotSummary = (verdict: IslandVerdict): string =>
   verdict.ok

package/src/messages.ts

@@ -216,8 +216,9 @@ const CATALOG = {
   'cli.shot.island.missing': '  missing  {file} — no picture was taken for this declared state',
   'cli.shot.island.picture': '  pictures {path}',
   'cli.shot.island.verdict': '  verdict  {path}',
+  'cli.shot.island.index': '  index    {path}',
   'cli.shot.island.blind.crop':
-    'the picture is the crop target and nothing around it — a component that overflows its own box, or whose fault is the space beside it, is outside the frame',
+    "the picture is the crop target and a thin margin around it — anything further out, including the space a component's own fault sits in, is outside the frame; content that overflows the box is recorded per state as overflow, never shown",
   'cli.shot.island.blind.locale':
     'toLocaleString() on a Date resolves its zone inside the engine — only an explicit timeZone is pinned by this harness',
   'cli.ci.failed':

package/src/prerender.ts

@@ -28,6 +28,7 @@ import {
   SW_REGISTER_PATH,
   serviceWorkerArtifacts,
   serviceWorkerHead,
+  serviceWorkerRegistration,
 } from './sw-artifacts';
 
 // Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
@@ -194,6 +195,17 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // header). `serviceWorkerHead` is the one predicate behind both, so a page can never name a
   // script the export does not carry.
   const swHead = pwa === undefined ? undefined : serviceWorkerHead(pwa);
+  // The registration's BYTES now too, and not beside `sw.js` at the end. Every document below
+  // names this file and `measureDocumentJs` weighs it off disk, so writing it last made the
+  // measurement read whatever happened to be there: nothing on a clean `out` (recorded as 0) and
+  // the PREVIOUS build's copy on a reused one. That is the run-order dependence the `jsBytes`
+  // split removed, and it came straight back in `frameworkJsBytes` because the field changed and
+  // the ORDER did not. `serviceWorkerRegistration()` depends on two constants and no document, so
+  // it has nothing to wait for; `sw.js` still comes last, because its precache manifest really is
+  // built from the hashes of pages that do not exist yet.
+  if (swHead !== undefined) {
+    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorkerRegistration());
+  }
   if (pwa !== undefined) {
     await Bun.write(join(options.out, WEB_MANIFEST_PATH.slice(1)), pwa.body);
     // And the icons that manifest NAMES. A static host runs no `assetRoutes()`, so every
@@ -252,6 +264,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         routes.push({
           path: entry.path,
           jsBytes: measured.jsBytes,
+          frameworkJsBytes: measured.frameworkBytes,
           ...(chain === undefined ? {} : { heaviestChain: chain }),
         });
       } catch (error) {
@@ -314,6 +327,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       heaviest = {
         path: entry.path,
         jsBytes: measured.jsBytes,
+        frameworkJsBytes: measured.frameworkBytes,
         ...(chain === undefined ? {} : { heaviestChain: chain }),
       };
     }
@@ -334,9 +348,10 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
           styles,
           documents,
         });
+  // `sw.js` only: `serviceWorker.register` IS `serviceWorkerRegistration()`, already on disk above
+  // and identical by construction. A second writer of one path is how the two could ever disagree.
   if (serviceWorker !== undefined) {
     await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
-    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorker.register);
   }
   const stats = await writeBuildStats(options.root, { routes });
   // Written LAST and by the same call that writes the stats, so an app whose `prerender.ts` does