@ultimat3/cli 11.1.0 → 11.2.0

package/src/island-shot.ts

@@ -0,0 +1,303 @@
+// `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.
+
+// why: no Bun native joins a path; `Bun.write` and `Bun.file` both take one already joined.
+import { join } from 'node:path';
+import type { 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 { 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;
+
+/**
+ * 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;
+  /**
+   * `--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.
+   */
+  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;
+}
+
+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;
+}
+
+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,
+): 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;
+    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,
+      });
+    }
+    // Never `fullPage`: the frame is the state's own declared viewport, and a full-page capture
+    // would grow with whatever the component scrolled.
+    const bytes = await page.screenshot({ fullPage: false });
+    const floor = options.minBytes ?? MIN_SHOT_BYTES;
+    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,
+  expected: readonly IslandShotTarget[],
+): Promise<readonly string[]> {
+  const missing: string[] = [];
+  for (const target of expected) {
+    if (!(await Bun.file(join(outDir, target.file)).exists())) missing.push(target.file);
+  }
+  return missing;
+}
+
+/**
+ * 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.
+ */
+export async function runIslandShot(options: IslandShotRun): Promise<IslandArtifacts> {
+  // 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 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.
+      try {
+        shots.push(await captureOne(options, server, target));
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+  } 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`);
+  // 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 first = failures[0];
+    if (first !== undefined) throw first;
+    throw new IslandShotsMissingError({
+      island: options.manifest.name,
+      missing,
+      expected: targets.length,
+      dir,
+    });
+  }
+  return { verdict, dir, verdictFile };
+}

package/src/island-states-load.ts

@@ -0,0 +1,78 @@
+// Step one of photographing an island: find every `*.island.states.ts` in the app, prove each is
+// pure data BEFORE importing it, and hand back the manifests. It happens with no browser and no
+// dev server on purpose — the complete expected picture list has to exist before a capture starts,
+// or "produced nothing and exited 0" is a result nobody can tell from success.
+
+// why: no Bun native joins a path or relativises one; `Bun.file` and `import()` both take one joined.
+import { join, relative, sep } from 'node:path';
+import { ISLAND_EXTENSION } from '@ultimat3/render';
+import type { IslandStatesManifest } from '@ultimat3/testing';
+import {
+  assertIslandFiles,
+  assertIslandStatesPure,
+  assertUniqueIslandStates,
+  isIslandStatesManifest,
+  islandStatesFile,
+} from '@ultimat3/testing';
+import { ISLAND_GLOB } from './island-bundle';
+import { IslandStatesFileEmptyError } from './island-shot-errors';
+
+/**
+ * `.island.states.ts`, built from the two constants that own its halves and restated as neither:
+ * `@ultimat3/render` owns the island extension and `@ultimat3/testing` owns what a states file
+ * beside one is called. A third spelling here is the drift the derivation exists to prevent.
+ */
+export const ISLAND_STATES_SUFFIX = islandStatesFile(ISLAND_EXTENSION);
+
+/**
+ * `ISLAND_GLOB` with the island extension swapped for the states suffix, so a states file is
+ * discovered exactly where its island is and nowhere else. One shape, derived, never a second
+ * glob: a states file the discovery misses is a state nobody photographs and nothing says so —
+ * which is what `findIslandStates` listing every declared name is the backstop for.
+ */
+export const ISLAND_STATES_GLOB = ISLAND_GLOB.replace(ISLAND_EXTENSION, ISLAND_STATES_SUFFIX);
+
+/** App-root-relative POSIX paths of every states file, sorted, so a run is reproducible. */
+export async function discoverIslandStates(root: string): Promise<readonly string[]> {
+  const files: string[] = [];
+  const scan = new Bun.Glob(ISLAND_STATES_GLOB).scan({ cwd: root, absolute: true });
+  for await (const absolute of scan) {
+    if (absolute.includes('node_modules')) continue;
+    files.push(relative(root, absolute).split(sep).join('/'));
+  }
+  return files.sort();
+}
+
+/**
+ * One file's manifests. The purity check runs against the file's TEXT and BEFORE the import,
+ * which is the whole reason the rule is static: a states file that imports Solid evaluates
+ * perfectly well under Bun, so nothing about loading it can notice, and by the time it has been
+ * loaded the damage — a module graph that needs a browser — is already done.
+ */
+async function manifestsIn(root: string, file: string): Promise<readonly IslandStatesManifest[]> {
+  const absolute = join(root, file);
+  assertIslandStatesPure(file, await Bun.file(absolute).text());
+  const module: unknown = await import(absolute);
+  const exported = typeof module === 'object' && module !== null ? Object.values(module) : [];
+  const found = exported.filter(isIslandStatesManifest);
+  // A file named `*.island.states.ts` that exports no manifest is the same silence one level up:
+  // it expands to no picture, and a run over it reports success having photographed nothing.
+  if (found.length === 0) throw new IslandStatesFileEmptyError({ file });
+  return found;
+}
+
+/**
+ * Every manifest this app declares, checked as a SET: two islands answering to one name share a
+ * shot directory (`assertUniqueIslandStates`), and a manifest naming a file that is not on disk
+ * expands to pictures that can never be taken (`assertIslandFiles`). Both are asked once here
+ * rather than discovered by whichever lookup happens to be made.
+ */
+export async function loadIslandStates(root: string): Promise<readonly IslandStatesManifest[]> {
+  const all: IslandStatesManifest[] = [];
+  for (const file of await discoverIslandStates(root)) {
+    all.push(...(await manifestsIn(root, file)));
+  }
+  assertUniqueIslandStates(all);
+  await assertIslandFiles(all, root);
+  return all;
+}

package/src/island-verdict.ts

@@ -0,0 +1,194 @@
+// What a run of `x shot --island` CLAIMS, and what it refuses to claim. The route verdict's shape
+// extended rather than forked: `ok` is still "nothing logged an error, nothing threw, no mount
+// rejected", with the two facts only a component capture has — the requests nobody stubbed, and
+// the declared pictures that never landed on disk.
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { t, validate } from '@ultimat3/schema';
+import type { ConsoleLine, PageError } from '@ultimat3/scraping';
+import type { IslandShotTarget } from '@ultimat3/testing';
+import { msg } from './messages';
+import type { JsonValue } from './output';
+
+/** Every key this path renders. `msg()` answers `⟦key⟧` for a miss, which no build can see. */
+export const ISLAND_SHOT_MESSAGE_KEYS = [
+  'cli.shot.island.ok',
+  'cli.shot.island.failed',
+  'cli.shot.island.missing',
+  'cli.shot.island.picture',
+  'cli.shot.island.verdict',
+  'cli.shot.island.state',
+  'cli.shot.island.blind.crop',
+  'cli.shot.island.blind.locale',
+] as const;
+
+/**
+ * What a component picture cannot see, named every time. `errors: 0` read without them is a claim
+ * this tool cannot support — and both are properties of the port rather than of a run, which is
+ * why they are a constant and not a per-run list.
+ *
+ * The crop one is the honest limit of the shipped browser port: `CaptureRequest` is `fullPage`
+ * alone (`packages/scraping/src/page.ts`), so a picture is the VIEWPORT and the framing knob is the
+ * state's own `viewport`, not a clip rectangle. The locale one is the reach of a page-side clock
+ * patch: `date.toLocaleString()` resolves the zone inside the engine and never through the patched
+ * `Intl.DateTimeFormat`.
+ */
+export const ISLAND_BLIND_SPOTS = [
+  'cli.shot.island.blind.crop',
+  'cli.shot.island.blind.locale',
+] as const;
+
+export interface IslandBox {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** What `readinessProbe` answers. Parsed, never cast: a page can return anything at all. */
+export interface IslandReadiness {
+  readonly harness: boolean;
+  readonly ready: boolean;
+  readonly unstubbed: readonly string[];
+  readonly attached: boolean;
+  readonly mounted: boolean;
+  readonly failed: string | null;
+  readonly filled: boolean;
+  readonly box: IslandBox;
+}
+
+const readinessSchema: StandardSchemaV1<unknown, IslandReadiness> = t.object({
+  harness: t.boolean,
+  ready: t.boolean,
+  unstubbed: t.array(t.string),
+  attached: t.boolean,
+  mounted: t.boolean,
+  failed: t.nullable(t.string),
+  filled: t.boolean,
+  box: t.object({ x: t.number, y: t.number, width: t.number, height: t.number }),
+}) as unknown as StandardSchemaV1<unknown, IslandReadiness>;
+
+/**
+ * `null` for anything that does not fit, and the caller treats that as "the page answered no
+ * probe" — never as a page that is ready. A malformed probe reported as readiness would be the
+ * capture asserting nothing while looking like it asserted everything.
+ */
+export function parseReadiness(value: unknown): IslandReadiness | null {
+  const result = validate(readinessSchema, value);
+  return result.issues === undefined ? result.value : null;
+}
+
+export interface IslandStateShot {
+  readonly state: string;
+  readonly theme: string;
+  /** `<name>/<state>-<theme>.png`, relative to the run's output directory. */
+  readonly file: string;
+  readonly bytes: number;
+  readonly box: IslandBox;
+  readonly mounted: boolean;
+  readonly unstubbed: readonly string[];
+  readonly console: readonly ConsoleLine[];
+  readonly pageErrors: readonly PageError[];
+}
+
+/** One state's picture is clean when nothing on the page logged, threw, or went unanswered. */
+export const stateShotOk = (shot: IslandStateShot): boolean =>
+  shot.mounted &&
+  shot.unstubbed.length === 0 &&
+  shot.pageErrors.length === 0 &&
+  shot.console.every((line) => line.level !== 'error');
+
+export interface IslandVerdictInput {
+  readonly island: string;
+  readonly name: string;
+  readonly server: 'booted' | 'reused';
+  readonly capturedAt: string;
+  /** Computed BEFORE a browser existed — the complete picture list this run owes. */
+  readonly expected: readonly IslandShotTarget[];
+  readonly shots: readonly IslandStateShot[];
+  /** Declared `target.file`s that are not on disk. The gate the browser cannot influence. */
+  readonly missing: readonly string[];
+}
+
+export interface IslandVerdict extends IslandVerdictInput {
+  readonly ok: boolean;
+  readonly blind: readonly string[];
+}
+
+export function buildIslandVerdict(input: IslandVerdictInput): IslandVerdict {
+  return {
+    ...input,
+    // The missing list gates on its own, and that is the whole point of computing it from the
+    // expansion rather than from what the loop believes it did: a capture that produced nothing
+    // and threw nothing would otherwise be a run with no shots, no failures and `ok: true`.
+    ok: input.missing.length === 0 && input.shots.every(stateShotOk),
+    blind: ISLAND_BLIND_SPOTS.map((key) => msg(key)),
+  };
+}
+
+const shotJson = (shot: IslandStateShot): JsonValue => ({
+  state: shot.state,
+  theme: shot.theme,
+  file: shot.file,
+  bytes: shot.bytes,
+  box: { x: shot.box.x, y: shot.box.y, width: shot.box.width, height: shot.box.height },
+  mounted: shot.mounted,
+  ok: stateShotOk(shot),
+  unstubbed: [...shot.unstubbed],
+  console: shot.console.map((line) => ({ level: line.level, text: line.text, at: line.at })),
+  pageErrors: shot.pageErrors.map((error) => ({
+    message: error.message,
+    stack: error.stack ?? null,
+    at: error.at,
+  })),
+});
+
+/** The artifact, and the same object `--json` carries under `data.verdict`. One shape, two files. */
+export function islandVerdictJson(verdict: IslandVerdict): JsonValue {
+  return {
+    ok: verdict.ok,
+    island: verdict.island,
+    name: verdict.name,
+    server: verdict.server,
+    capturedAt: verdict.capturedAt,
+    expected: verdict.expected.map((target) => target.file),
+    missing: [...verdict.missing],
+    states: verdict.shots.map(shotJson),
+    blind: [...verdict.blind],
+  };
+}
+
+export interface IslandArtifacts {
+  readonly verdict: IslandVerdict;
+  /** Absolute path of the directory the pictures and the verdict were written to. */
+  readonly dir: string;
+  readonly verdictFile: string;
+}
+
+export function islandShotLines(artifacts: IslandArtifacts): readonly string[] {
+  const verdict = artifacts.verdict;
+  return [
+    ...verdict.shots.map((shot) =>
+      msg('cli.shot.island.state', {
+        state: 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.verdict', { path: artifacts.verdictFile }),
+  ];
+}
+
+/** 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
+    ? msg('cli.shot.island.ok', { island: verdict.name, pictures: verdict.shots.length })
+    : msg('cli.shot.island.failed', {
+        island: verdict.name,
+        taken: verdict.shots.length,
+        expected: verdict.expected.length,
+      });

package/src/mcp-errors.ts

@@ -53,6 +53,17 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_WORKSPACE_DEP_UNDECLARED:
     'x verify --json   # the package-shape finding carries the dependency line to add',
   X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
+  // The four island-capture codes. Each one's real repair is an edit to the app's own states file
+  // or component, which no command can perform — so each names the command that REPRODUCES it with
+  // the file and the reason attached, which is the runnable half.
+  X_SHOT_ISLAND_STATES_EMPTY:
+    'x help shot --json   # then export the manifest from the states file the cause names',
+  X_SHOT_ISLAND_UNPHOTOGRAPHABLE:
+    'x help shot --json   # the cause names the assertion that did not hold; --settle buys the slow ones more time',
+  X_SHOT_ISLAND_UNSTUBBED_REQUEST:
+    'x help shot --json   # the cause lists every request the state must answer under routes',
+  X_SHOT_ISLAND_MISSING:
+    'x help shot --json   # every absent picture carries its own named refusal in the run above',
   X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
   X_GH_NOT_AUTHENTICATED: 'gh auth login',
   X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',

package/src/messages.ts

@@ -196,6 +196,20 @@ const CATALOG = {
   'cli.shot.verdict': '  verdict  {path}',
   'cli.shot.blind.status':
     'HTTP response status is not observed — the port records requests, never responses',
+  // `--island`. A component capture reports per STATE, so the summary counts pictures and the
+  // lines name one state each; nothing here restates a fact `--json` does not carry.
+  'cli.shot.island.ok':
+    '{island} clean — {pictures} picture(s), every one mounted, nothing logged and nothing threw',
+  'cli.shot.island.failed':
+    '{island}: {taken} of {expected} declared picture(s) taken — verdict.json names each refusal',
+  'cli.shot.island.state': '  {state}  {theme}  {width}x{height}  {file}',
+  '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.blind.crop':
+    'the picture is the viewport, not a crop — the browser port takes no clip rectangle, so a state sizes its own frame with viewport',
+  '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':
     '{failed} of {runs} workflow run(s) on {branch} failed — {findings} finding(s) recovered from the log',
   'cli.ci.green': 'every one of {runs} workflow run(s) on {branch} passed',

package/src/reexport-manifest.ts

@@ -0,0 +1,62 @@
+// Whether a file is a pure re-export manifest — every statement in it an `import` or an `export`
+// that declares nothing. The line ceiling is a rule about REVIEWABLE LOGIC, and such a file has
+// none: its length is a function of the package's API size, so the ceiling measures the wrong
+// thing there. One added statement of logic disqualifies it and re-arms the ceiling on the spot.
+
+import { CLOSERS, maskLiterals, OPENERS } from './ts-scan';
+
+/** Every statement a manifest may hold begins with one of these two words. */
+const IMPORT_OR_EXPORT = /^(?:import|export)\b/;
+
+/**
+ * An `export` that DECLARES rather than re-exports. `export const LIMIT = 1` is a value with an
+ * initialiser, `export function` is logic outright, and both are exactly what the ceiling is for —
+ * so a file holding one is an ordinary source file that happens to start with re-exports.
+ */
+const DECLARES =
+  /^export\s+(?:default|declare|abstract|async|const|let|var|function|class|enum|namespace|module|interface)\b/;
+
+/**
+ * `export type { Ctx } from './ctx'` is a re-export; `export type Ctx = { … }` is a type alias, and
+ * an alias is a declaration a reviewer reads. The brace is the whole distinction.
+ */
+const TYPE_ALIAS = /^export\s+type\s+[A-Za-z_$]/;
+
+/**
+ * Top-level statements, split at the `;` that ends each one at bracket depth 0, over MASKED source
+ * — comments and string contents blanked — so a `;` inside a specifier or a comment is not read as
+ * a boundary. `undefined` when the file ends in something this cannot read as a statement: a scan
+ * that guesses would exempt a file on the strength of not understanding it.
+ */
+function topLevelStatements(masked: string): readonly string[] | undefined {
+  const statements: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < masked.length; i += 1) {
+    const ch = masked[i] as string;
+    if (OPENERS.has(ch)) depth += 1;
+    // Clamped, because an unbalanced closer would otherwise put every later `;` at a negative
+    // depth and the whole file would read as one unterminated statement.
+    else if (CLOSERS.has(ch)) depth = Math.max(0, depth - 1);
+    else if (ch === ';' && depth === 0) {
+      statements.push(masked.slice(start, i));
+      start = i + 1;
+    }
+  }
+  return masked.slice(start).trim() === '' ? statements : undefined;
+}
+
+/**
+ * True when every statement in `source` is an import or a declaration-free export. A file with no
+ * statement at all is NOT a manifest: an exemption has to be earned by what a file holds, and
+ * "this scan found nothing" is the one answer that must never grant one.
+ */
+export function isReExportManifest(source: string): boolean {
+  const statements = topLevelStatements(maskLiterals(source));
+  if (statements === undefined || statements.length === 0) return false;
+  return statements.every((statement) => {
+    const text = statement.trim();
+    if (text === '') return true;
+    return IMPORT_OR_EXPORT.test(text) && !DECLARES.test(text) && !TYPE_ALIAS.test(text);
+  });
+}