@motujs/cli 0.0.0-stage → 0.1.1

package/src/commands/verify/screens-runtime.mjs

@@ -0,0 +1,123 @@
+// Screens at runtime: every declared screen opened alone, its calls held to `flow-calls`, and the
+// screens' own FLOWS replayed — a step can click the app's own links, `navigate` to a path, and assert
+// which screen is open (`expectScreen`) and what a slot renders (`expectRender`).
+//
+// Screen flows live in `src/screens/screens.evidence.ts`, beside `screens.ts`, exporting `scenarios`:
+//
+//   export const scenarios = [{
+//     name: 'the sidebar opens the team base',
+//     screen: 'club',
+//     steps: [{ click: 'Ma base - Mes équipes', expectScreen: 'base' }],
+//   }];
+//
+// Read with the same loader as a region's evidence, so the same rule holds: no `@/` imports there.
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { declaredScreens, screensFile } from '../../lib/screens.mjs';
+import { describeCall } from '../../lib/flow-calls.mjs';
+import { runScreens } from '../../playwright-lagoon.mjs';
+import { readScenarios } from './island-runtime.mjs';
+
+export function screenFlowsFile() {
+  return resolve(dirname(screensFile()), 'screens.evidence.ts');
+}
+
+/**
+ * Findings, in the shape `screenFindings()` already uses ({ level, check, msg }), so `motu check`
+ * prints them in the screens section. Null when the project declares no screens.
+ */
+export async function screenRuntimeFindings({ only = null } = {}) {
+  const decl = declaredScreens();
+  if (!decl?.screens?.length) return null;
+  const known = new Set(decl.screens.map((s) => s.id));
+  const findings = [];
+  const add = (level, check, msg) => findings.push({ level, check, msg });
+  if (only && !known.has(only)) {
+    add('error', 'screen-runtime', `no declared screen "${only}" — declared: ${[...known].join(', ')}`);
+    return findings;
+  }
+  const ids = only ? [only] : [...known];
+
+  const file = screenFlowsFile();
+  const declared = existsSync(file) ? readScenarios(file) : [];
+  const flows = [];
+  for (const f of declared) {
+    if (!known.has(f.screen)) {
+      add('error', 'screen-flow', `"${f.name ?? 'screen flow'}" starts on screen "${f.screen}", which is not declared`);
+      continue;
+    }
+    if (!only || f.screen === only) flows.push(f);
+  }
+
+  let run;
+  try {
+    run = await runScreens({ port: 5600 + Math.floor(Math.random() * 300), screens: ids, flows });
+  } catch (err) {
+    add('inconclusive', 'screen-runtime', `could not open the screens: ${String(err?.message ?? err).split('\n')[0]}`);
+    return findings;
+  }
+
+  let calls = 0;
+  let bad = 0;
+  // ONE FINDING PER CALL, naming every screen that makes it. The layout makes the same call on every
+  // screen, so per-screen findings were 21 copies of one fix.
+  const byCall = new Map();
+  for (const s of run.screens) {
+    calls += s.calls;
+    if (!s.ok) add('error', 'screen-render', `screen "${s.screen}" did not open: ${s.error}`);
+    for (const c of s.undeclared) {
+      const k = `${c.method} ${c.label || c.url} ${c.status}`;
+      if (!byCall.has(k)) byCall.set(k, { call: c, screens: new Set() });
+      byCall.get(k).screens.add(s.screen);
+    }
+  }
+  for (const { call, screens } of byCall.values()) {
+    bad++;
+    const list = [...screens];
+    const where = list.length === run.screens.length && list.length > 1 ? `every screen (${list.length})` : `screen${list.length > 1 ? 's' : ''} ${list.map((x) => `"${x}"`).join(', ')}`;
+    add('error', 'flow-calls', `${where}: ${describeCall(call)}`);
+  }
+  const opened = run.screens.filter((s) => s.ok).length;
+  if (opened === run.screens.length) add('ok', 'screen-render', `${opened} screen(s) open from their own address`);
+
+  for (const r of run.flows) {
+    calls += r.calls;
+    const where = `"${r.flow}" step ${r.step}`;
+    if (!r.ok) {
+      add('error', 'screen-flow', `${where}: ${r.error ?? r.mismatches.map((m) => `${m.key}: expected ${m.expected}, got ${m.actual}`).join('; ')}`);
+    }
+    for (const c of r.undeclared) {
+      bad++;
+      add('error', 'flow-calls', `${where}: ${describeCall(c)}`);
+    }
+  }
+  if (run.flows.length) {
+    const passed = run.flows.filter((r) => r.ok).length;
+    if (passed === run.flows.length) add('ok', 'screen-flow', `${passed} screen flow step(s) end as declared`);
+  } else {
+    add('warn', 'screen-flow', `no screen flows declared — ${file.replace(process.cwd() + '/', '')} would hold what navigating between screens must do`);
+  }
+  // A CHECK THAT LOOKED AT NOTHING HAS NOT PASSED: no calls at all is a skip, not a clean bill.
+  if (!bad) add(calls ? 'ok' : 'skip', 'flow-calls', calls ? `every call the screens made was answered by a declaration · ${calls} call(s)` : 'the screens made no backend calls — nothing to hold to a declaration');
+  return findings;
+}
+
+/** `motu screen verify [id]` — the screens' runtime pass on its own, for the loop on one screen. */
+export async function screenVerifyCommand(argv) {
+  const only = typeof argv._?.[0] === 'string' ? argv._[0] : null;
+  const findings = await screenRuntimeFindings({ only });
+  if (!findings) {
+    console.error('this project declares no screens (src/screens/screens.ts)');
+    return 2;
+  }
+  if (argv.json) console.log(JSON.stringify({ findings }, null, 2));
+  else {
+    for (const f of findings) {
+      const mark = f.level === 'error' ? '✗' : f.level === 'warn' ? '!' : f.level === 'ok' ? '✓' : '–';
+      console.log(`  ${mark} ${f.check.padEnd(16)} ${f.msg}`);
+    }
+  }
+  if (findings.some((f) => f.level === 'error')) return 1;
+  if (findings.some((f) => f.level === 'inconclusive')) return 2;
+  return 0;
+}

package/src/commands/verify.mjs

@@ -0,0 +1,18 @@
+// `motu island verify <name>` — the deterministic gate that turns the README's island rules into
+// machine-checkable pass/fail, so an agent can close the loop without a human eyeballing the host.
+//
+//   static  (AST over the component): no bare fetch, no history/pushState, no document reach-out into
+//           the host, all server I/O via @motujs/contract, renders from default props alone.
+//   config  (AST over the registry):  registered with a REQUIRED legacy-fit strategy; archipelago
+//           membership (warn if standalone).
+//   runtime (lagoon):                 boots the focused lagoon and asserts the island renders a
+//           non-empty shadow DOM in both native and legacy fit. Default: a REAL browser (Playwright/
+//           Chromium) so layout/CSS/paint are exercised; `--fast` uses an in-process happy-dom mount.
+//
+// The checks live in ./verify/, one module per concern; this file is the public surface.
+
+export { setProgressScope, setVerbose, profiledMs, step, verifyExitCode, sweepExitCode, summaryOf, printSweep } from './verify/report.mjs';
+export { reportReachDrift, operationReachCheck } from './verify/reach.mjs';
+export { readScenarios } from './verify/island-runtime.mjs';
+export { verifyCommand, runIslandVerify } from './verify/island.mjs';
+export { archipelagoVerifyCommand, runArchipelagoVerify } from './verify/region.mjs';

package/src/lagoon-build.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// The lagoon build, run as its own process.
+//
+// `motu lagoon publish|serve` shells out to this rather than building in-process, for the same reason
+// it used to shell out to the vite CLI: the build runs inside sync watcher and request callbacks, and
+// a subprocess keeps those call sites unchanged. What changed is WHAT is run — the config now comes
+// from @motujs/cli (see lib/lagoon-vite.mjs) instead of a vite.config.ts scaffolded into the project.
+//
+// Invoked with the project as cwd; every MOTU_* input arrives through the environment, exactly as the
+// vite CLI received it.
+import { resolve } from 'node:path';
+import { loadMotuConfig } from './lib/config.mjs';
+import { buildLagoonViteConfig, resolveVite } from './lib/lagoon-vite.mjs';
+
+const paths = loadMotuConfig();
+const vite = await resolveVite(paths);
+const config = await buildLagoonViteConfig(paths, process.env);
+// Vite resolves `outDir` against ROOT, and root is now `.motu/cache/lagoon` for a project that does
+// not own its entries — so the artifact would land in the cache while `publish`/`serve` look for it
+// under the project's lagoon. Pin it back with an absolute path: where the build INPUT lives is a
+// framework detail, where the OUTPUT lands is the project's.
+config.build.outDir = resolve(paths.lagoonDir, 'dist');
+config.build.emptyOutDir = true;
+config.logLevel = process.env.MOTU_VITE_LOGLEVEL ?? 'warn';
+await vite.build(config);

package/src/lagoon-dev.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// The lagoon dev server, run as its own process.
+//
+// Two callers: `motu lagoon dev` (a human iterating) and `motu island|archipelago verify`, which boots
+// a FOCUSED server (MOTU_TARGET) in its own process group so it can be killed cleanly and cannot
+// outlive the run holding a strict port. Both used to spawn the vite CLI against a vite.config.ts
+// scaffolded into the project; the config now comes from @motujs/cli instead.
+//
+// Invoked with the project as cwd. Flags mirror the vite CLI's, because verify's process handling
+// depends on them: --port, --strictPort.
+import { loadMotuConfig } from './lib/config.mjs';
+import { buildLagoonViteConfig, resolveVite } from './lib/lagoon-vite.mjs';
+
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 ? (argv[i + 1]?.startsWith('--') ? true : (argv[i + 1] ?? true)) : undefined;
+};
+
+const paths = loadMotuConfig();
+const vite = await resolveVite(paths);
+const config = await buildLagoonViteConfig(paths, process.env);
+
+const port = flag('port');
+if (port) config.server.port = Number(port);
+if (flag('strictPort')) config.server.strictPort = true;
+config.clearScreen = false;
+config.logLevel = process.env.MOTU_VITE_LOGLEVEL ?? 'info';
+
+const server = await vite.createServer(config);
+await server.listen();
+server.printUrls();

package/src/lib/alias-core.mjs

@@ -0,0 +1,49 @@
+// The alias map, shared by the ESM hook and the CJS patch so the two cannot disagree.
+//
+// Two module systems reach for the same specifier: an island's ESM `import` and, further down, a
+// dependency's CJS `require`. acme got past `@/app` through the ESM hook and then died on
+// `require('@/lib/utils')`, because a resolver hook is not in that path at all.
+import { existsSync, statSync } from 'node:fs';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** A bundler resolves these; node cannot even parse them. */
+export const ASSET = /\.(css|scss|sass|less|svg|png|jpe?g|gif|webp|avif|woff2?|ttf|eot)(\?.*)?$/i;
+/** What an asset import becomes: an inert module, so the component's own code still runs. */
+export const ASSET_STUB = resolvePath(HERE, '..', 'asset-stub.mjs');
+export const ASSET_STUB_CJS = resolvePath(HERE, '..', 'asset-stub.cjs');
+
+const CANDIDATES = ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '/index.ts', '/index.tsx', '/index.js'];
+
+export function aliasEntries() {
+  return JSON.parse(process.env.MOTU_NODE_ALIASES ?? '[]').map((e) => ({
+    find: e.source ? new RegExp(e.source, e.flags) : e.find,
+    replacement: e.replacement,
+  }));
+}
+
+/** A bundler finds `app/index.tsx` for `@/app`; node looks for a file called exactly `app`. */
+export function onDisk(base) {
+  for (const suffix of CANDIDATES) {
+    const candidate = base + suffix;
+    try {
+      if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+    } catch {
+      /* keep looking */
+    }
+  }
+  return null;
+}
+
+/** The file this specifier means, or null to let the host resolver have it. */
+export function mapSpecifier(specifier, entries) {
+  for (const { find, replacement } of entries) {
+    const hit = find instanceof RegExp ? find.test(specifier) : specifier === find;
+    if (!hit) continue;
+    const mapped = find instanceof RegExp ? specifier.replace(find, replacement) : replacement;
+    return onDisk(resolvePath(mapped));
+  }
+  return null;
+}

package/src/lib/archipelagos.mjs

@@ -0,0 +1,111 @@
+// What the REGION side of a project needs generated.
+//
+// WHY THIS FILE EXISTS AT ALL, and it is a correction. Coverage's deployment config —
+// `configureCoverage({ enabled, regions })` — used to be emitted into the ISLAND registry by
+// the island registry's generator. Nothing about it is island-shaped: `regions: ["actions"]` names regions, and the
+// two other pieces of coverage already live where they belong (`coverage: { enums }` is declared on
+// the archipelago, and `offerRegionToCoverage` is called by `defineArchipelago`).
+//
+// It went there because the island registry was the one generated module an application is guaranteed
+// to import and execute at startup. That is a fact about which files happened to exist, not a reason,
+// and it made the island registry quietly responsible for something outside its own noun.
+//
+// A SEPARATE FILE RATHER THAN A HAND-OWNED ONE. `archipelagos/registry.ts` is scaffolded once and
+// edited by `motu archipelago init` — it is the project's, and generated content inside it would
+// blur the line that says a generated file is never hand-edited. So this writes its own neighbour and
+// the registry imports it.
+//
+// WRITTEN EVEN WHEN COVERAGE IS OFF, as an empty module. The load-bearing property is that a project
+// with coverage off never NAMES `@motujs/coverage` — a module nothing imports is a module no bundler
+// ships. An empty generated file satisfies that while keeping the registry's import line constant, so
+// turning coverage on and off never edits a hand-owned file.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const COVERAGE_MODULE = 'coverage.generated.ts';
+
+/** The import the archipelago registry needs, exactly as it must appear. */
+const IMPORT_LINE = "import './coverage.generated';";
+
+export function renderCoverageModule(coverage) {
+  const head = `// GENERATED by \`motu sync\` — do not edit.
+//
+// Region-level deployment facts from motu.config.json. Imported for its SIDE EFFECT: it configures
+// the coverage fold before any region mounts, and exports nothing.
+`;
+  if (!coverage?.enabled) {
+    return `${head}//
+// Coverage is off in motu.config.json, so this module is deliberately empty — and empty is the point.
+// Nothing here names \`@motujs/coverage\`, so no bundler ships it, while the registry's import line
+// stays constant whether coverage is on or off. Turning it on never edits a hand-owned file.
+export {};
+`;
+  }
+  return `${head}//
+// THE IMPORT IS THE SWITCH. \`@motujs/coverage\` is its own package precisely so a project with coverage
+// off never names it. Core holds only a seam (\`offerRegionToCoverage\`) that stays a dead branch until
+// this line fills it.
+//
+// It arrives by IMPORT rather than as a build constant. \`__MOTU_DEBUG__\` exists so the seam lens'
+// whole import tree dead-code-eliminates — the lens must not ship. Coverage is MEANT to ship, so a
+// define would only oblige every host's bundler to declare a global or fail with a ReferenceError.
+//
+// NOT HERE: which of a region's keys are closed sets — that is a fact about the key, declared on the
+// archipelago beside it. Nor the ADDRESSES: the lagoon imports this, and a published lagoon is a
+// public page, so an endpoint baked here becomes a public string. The application renders those as
+// meta tags instead:
+//
+//   <meta name="motu-coverage-endpoint" content="…" />
+//   <meta name="motu-coverage-known"    content="…" />
+import { configureCoverage } from '@motujs/coverage';
+
+configureCoverage(${JSON.stringify({ enabled: true, ...(coverage.regions ? { regions: coverage.regions } : {}) })});
+`;
+}
+
+/**
+ * Make sure the project's archipelago registry imports the generated module.
+ *
+ * The registry is HAND-OWNED, so this touches it once and never again: a single import line, added at
+ * the top if it is absent, left alone if it is there. `motu archipelago init` already edits this
+ * file, so tooling writing one line into it is the established arrangement rather than a new liberty.
+ */
+function ensureRegistryImports(registryPath) {
+  if (!existsSync(registryPath)) return 'no registry';
+  const src = readFileSync(registryPath, 'utf8');
+  if (src.includes(IMPORT_LINE)) return 'already imported';
+  const lines = src.split('\n');
+  // BEFORE THE OTHER IMPORTS, and the first version of this got it backwards.
+  //
+  // It went after them, reasoning that "after the imports is where a reader looks for a side effect".
+  // True of a side effect that ACTS; wrong for one that CONFIGURES. ES modules evaluate dependencies
+  // in source order, so every archipelago below this line defined itself — and offered itself to the
+  // coverage seam — before the module that fills that seam had run. The offers went nowhere and
+  // coverage was silently off in production.
+  //
+  // The seam remembers offers now, so this no longer decides whether coverage works. It is still
+  // first, because a configuration side effect belongs above the thing it configures and the next
+  // reader should not have to know the seam is forgiving.
+  let at = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^import\s/.test(lines[i])) { at = i; break; }
+  }
+  lines.splice(
+    at,
+    0,
+    '// Region-level deployment facts, generated by `motu sync`. Imported for its side',
+    '// effect, and FIRST: it configures the seam every archipelago below offers itself to.',
+    IMPORT_LINE,
+    '',
+  );
+  writeFileSync(registryPath, lines.join('\n'));
+  return 'import added';
+}
+
+/** Write the region-level generated module for a project. Returns what it did. */
+export function syncArchipelagos(archipelagosDir, coverage = null) {
+  const out = resolve(archipelagosDir, COVERAGE_MODULE);
+  writeFileSync(out, renderCoverageModule(coverage));
+  const registry = ensureRegistryImports(resolve(archipelagosDir, 'registry.ts'));
+  return { path: out, enabled: Boolean(coverage?.enabled), registry };
+}

package/src/lib/assurance.mjs

@@ -0,0 +1,144 @@
+// ASSURANCE — one row per DECLARED THING, with the strongest evidence that holds it.
+//
+// A check report has one row per CHECK, and "green" means "nothing contradicted what was checked" —
+// the reader cannot see how much was. This inverts the axis (docs/proposals/constraint-loop.md, item
+// 3): every slot, write, shared key and flow's calls, each with a LEVEL, the evidence behind it, and
+// what is missing. A residual motu cannot hold — a handler driven only through `emit` — is then SHOWN
+// as such instead of passing green, and a person can decide about it (a unit test, or accept it).
+//
+// Derived from the declarations and the evidence files alone, so it is static and fast. A level says
+// what the evidence CLAIMS; `motu check --runtime` is what confirms the claim holds.
+//
+//   unchecked     nothing in the evidence exercises it
+//   static        declared, typed and placed — the static checks hold it, no flow does
+//   runtime·emit  a flow drives it through the island's DECLARED OUTPUT — past the component's handler
+//   runtime       a flow asserts it (a slot's render, a key a reader shows)
+//   runtime·user  a flow reaches it by the path a person takes: a `click` on the rendered control
+//
+// KNOWN LIMIT: a `click` is credited to a write only when its step `expect`s the written key. A click
+// asserted by its render alone (demo-app's "sorting by level ranks the whole club") cannot be tied to a
+// declared write without running it — the runtime trace `motu diff` records is where that belongs.
+//
+// Pure: everything it reads is passed in, so it is tested without a project.
+
+export const LEVELS = ['unchecked', 'static', 'runtime·emit', 'runtime', 'runtime·user'];
+const rank = (l) => LEVELS.indexOf(l);
+
+const where = (flow, i) => `"${flow.name ?? 'flow'}" step ${i + 1}`;
+const keyOf = (target) => (typeof target === 'string' ? target : (target?.key ?? Object.keys(target ?? {})[0] ?? '?'));
+
+/** The region keys a slot's island READS — its `bind` (both forms) and its declared `reads`. */
+function readKeys(island) {
+  const out = new Set(island.reads ?? []);
+  for (const entry of [].concat(island.bind ?? [])) {
+    if (typeof entry === 'string') out.add(entry);
+    else if (entry && typeof entry === 'object') for (const v of Object.values(entry)) if (typeof v === 'string') out.add(v);
+  }
+  return out;
+}
+
+/**
+ * Rows for one region. `region` is what `readRegions` returns (`islands` with slot, element, writes,
+ * bind, reads, planned); `flows` is the region's declared scenarios.
+ */
+export function assuranceRows(region, flows) {
+  const rows = [];
+  const islands = (region?.islands ?? []).filter((i) => !i.planned);
+  const steps = flows.flatMap((f) => (f.steps ?? []).map((st, i) => ({ flow: f, st, i })));
+
+  // Who produces each key, so a slot can be asked about the coupling it actually HAS.
+  const producerOf = new Map();
+  for (const isl of islands) for (const t of Object.values(isl.writes ?? {})) producerOf.set(keyOf(t), isl.slot);
+
+  // SLOTS — does any flow assert what this slot renders?
+  for (const isl of islands) {
+    // Only a slot that READS another island's key has a coupling to show; a pure producer (a search
+    // box) does not, and saying it is missing one was noise on every region.
+    const coupled = [...readKeys(isl)].some((k) => producerOf.has(k) && producerOf.get(k) !== isl.slot);
+    const asserting = steps.filter(({ st }) => st.expectRender && Object.hasOwn(st.expectRender, isl.slot));
+    const driven = asserting.filter(({ st }) => st.emit && st.emit.slot !== isl.slot);
+    rows.push(
+      asserting.length
+        ? {
+            kind: 'slot',
+            subject: isl.slot,
+            level: 'runtime',
+            evidence: `expectRender in ${asserting.length} step(s), first ${where(asserting[0].flow, asserting[0].i)}` +
+              (driven.length ? `; asserted after ANOTHER island moved in ${driven.length}` : ''),
+            missing: coupled && !driven.length ? 'it reads another island’s key, and no step asserts it after that island moved — the coupling is not shown' : null,
+          }
+        : {
+            kind: 'slot',
+            subject: isl.slot,
+            level: 'static',
+            evidence: 'declared and placed',
+            missing: 'no flow asserts what it renders — it could show a neighbour’s data and stay green',
+          },
+    );
+  }
+
+  // WRITES — is the island's declared output exercised, and by which path?
+  for (const isl of islands) {
+    for (const [event, target] of Object.entries(isl.writes ?? {})) {
+      const key = keyOf(target);
+      const subject = `${isl.slot} · ${event} → ${key}`;
+      const clicked = steps.filter(({ st }) => st.click && st.expect && Object.hasOwn(st.expect, key));
+      const emitted = steps.filter(({ st }) => st.emit?.slot === isl.slot && st.emit?.event === event);
+      if (clicked.length) {
+        rows.push({ kind: 'write', subject, level: 'runtime·user', evidence: `a click moves ${key} in ${where(clicked[0].flow, clicked[0].i)}`, missing: null });
+      } else if (emitted.length) {
+        rows.push({
+          kind: 'write',
+          subject,
+          level: 'runtime·emit',
+          evidence: `emitted in ${emitted.length} step(s), first ${where(emitted[0].flow, emitted[0].i)}`,
+          missing: 'the component’s own handler is never driven — `emit` enters past it, so a handler that ignores its input passes. A `click` step, or a unit test',
+        });
+      } else {
+        rows.push({ kind: 'write', subject, level: 'static', evidence: 'declared and typed (`wiring`)', missing: 'no flow drives it — the island could stop producing it and nothing would change' });
+      }
+    }
+  }
+
+  // SHARED KEYS — a key one island writes and another reads: is a reader shown REACTING to it?
+  for (const [key, producer] of producerOf) {
+    const readers = islands.filter((i) => i.slot !== producer && readKeys(i).has(key)).map((i) => i.slot);
+    if (!readers.length) {
+      rows.push({ kind: 'key', subject: key, level: 'unchecked', evidence: `written by ${producer}`, missing: 'no other island reads it — a key nobody reads is not shared state' });
+      continue;
+    }
+    const writers = new Set(Object.entries(islands.find((i) => i.slot === producer)?.writes ?? {}).filter(([, t]) => keyOf(t) === key).map(([e]) => e));
+    const shown = steps.find(
+      ({ st }) =>
+        ((st.emit?.slot === producer && writers.has(st.emit?.event)) || (st.click && st.expect && Object.hasOwn(st.expect, key))) &&
+        readers.some((r) => st.expectRender && Object.hasOwn(st.expectRender, r)),
+    );
+    rows.push(
+      shown
+        ? { kind: 'key', subject: key, level: shown.st.click ? 'runtime·user' : 'runtime', evidence: `${producer} → ${readers.join(', ')}: a reader’s render is asserted as it moves, ${where(shown.flow, shown.i)}`, missing: null }
+        : { kind: 'key', subject: key, level: 'static', evidence: `${producer} → ${readers.join(', ')}, declared`, missing: 'no flow moves it and asserts what a reader then shows' },
+    );
+  }
+
+  // CALLS — what each flow's states ask the backend for. `flow-calls` holds every call to an ANSWER;
+  // only `expectCalls` holds a state to WHICH calls it makes.
+  for (const f of flows) {
+    const n = (f.steps ?? []).length;
+    const declared = (f.steps ?? []).filter((st) => st.expectCalls !== undefined).length;
+    rows.push({
+      kind: 'calls',
+      subject: `flow "${f.name ?? 'flow'}"`,
+      level: declared ? 'runtime' : 'static',
+      evidence: declared ? `${declared}/${n} step(s) declare \`expectCalls\`` : 'every call is held to an answer (`flow-calls`)',
+      missing: declared === n ? null : `${n - declared}/${n} step(s) do not say which calls they make — an extra request that is answered goes unseen`,
+    });
+  }
+  return rows;
+}
+
+/** Counts per level, for the summary line. */
+export function summarize(rows) {
+  const by = Object.fromEntries(LEVELS.map((l) => [l, 0]));
+  for (const r of rows) by[r.level]++;
+  return { total: rows.length, byLevel: by, weakest: rows.reduce((m, r) => (rank(r.level) < rank(m) ? r.level : m), 'runtime·user') };
+}

package/src/lib/baselines.mjs

@@ -0,0 +1,107 @@
+// Talking to the lagoon host about visual baselines.
+//
+// The repository stores no PNGs. A run renders locally, POSTs each shot, and the HOST decides whether
+// it is new, matches the accepted baseline, or differs from it — because "accepted" is a decision
+// somebody made, not whatever happened to be on disk last. That distinction is the whole reason this
+// lives on the host: `--update` overwriting files is why a stale baseline and a real regression look
+// identical.
+//
+// Diff images are still produced, and still locally: the host hands back the accepted bytes, the same
+// pixelmatch comparison runs here, and the artifacts land under `.motu/` where they are ignored. The
+// answer to "what changed?" stays an image you can open.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { gzipSync } from 'node:zlib';
+import { REPO_ROOT } from './util.mjs';
+import { loadHostConfig, gitIdentity } from './remote.mjs';
+
+/** Where the host is, by the same precedence `lagoon publish --remote` uses. */
+export function resolveBaselineHost(argv) {
+  const cfg = loadHostConfig();
+  const url = (typeof argv.remote === 'string' ? argv.remote : null) || process.env.MOTU_HOST_URL || cfg.url;
+  const token = (typeof argv.token === 'string' ? argv.token : null) || process.env.MOTU_HOST_TOKEN || cfg.token || null;
+  if (!url) return null;
+  return { base: String(url).replace(/\/+$/, ''), token, id: gitIdentity(REPO_ROOT) };
+}
+
+async function api(host, path, init = {}) {
+  let res;
+  try {
+    res = await fetch(`${host.base}${path}`, {
+      ...init,
+      headers: { ...(init.headers ?? {}), ...(host.token ? { authorization: `Bearer ${host.token}` } : {}) },
+    });
+  } catch (err) {
+    throw new Error(`cannot reach the lagoon host at ${host.base} — ${err.message}`);
+  }
+  const text = await res.text();
+  let payload = null;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    /* something other than the host answered */
+  }
+  if (!res.ok) throw new Error(payload?.error ?? `${res.status} ${text.slice(0, 160).replace(/\s+/g, ' ').trim()}`);
+  return payload;
+}
+
+/** `<scenario>@<viewport>` — the shot's identity, derived from the same name the files used. */
+export const shotId = (file) => file.replace(/\.png$/, '');
+
+/** Send one rendered shot. Returns { status: 'new'|'match'|'changed', accepted, hash }. */
+export async function putShot(host, island, file, png) {
+  const q = new URLSearchParams({ repo: host.id.repo, island, shot: shotId(file) });
+  if (host.id.sha) q.set('sha', host.id.sha);
+  if (host.id.branch) q.set('branch', host.id.branch);
+  return api(host, `/api/baseline?${q}`, {
+    method: 'POST',
+    headers: { 'content-type': 'image/png', 'content-encoding': 'gzip' },
+    body: gzipSync(png),
+  });
+}
+
+/** The accepted bytes, so a difference can be shown rather than reported as a percentage. */
+export async function fetchShot(host, hash) {
+  const res = await fetch(`${host.base}/shot/${hash}`);
+  if (!res.ok) return null;
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/**
+ * Every shot this repo has, with its status.
+ *
+ * THROUGH `api`, WHICH SENDS THE TOKEN, and that is the whole reason this function exists rather than
+ * a bare `fetch` at the call site. `/api/baselines` is gated by `readable(repo)`, so on a PRIVATE repo
+ * an unauthenticated read gets 404 — and the caller that did this swallowed the failure in a
+ * `try/catch`, leaving "which member islands also changed" empty. An empty answer there does not read
+ * as an error; it reads as `no member changed`, which is how a region diff concludes THE ARRANGEMENT
+ * MOVED when in truth it could not see the members at all.
+ */
+export async function listShots(host, island = null) {
+  const q = new URLSearchParams({ repo: host.id.repo });
+  if (island) q.set('island', island);
+  return api(host, `/api/baselines?${q}`);
+}
+
+/** Move the accepted pointer. `island` null accepts everything the repo has pending. */
+export async function acceptShots(host, island) {
+  const q = new URLSearchParams({ repo: host.id.repo });
+  if (island) q.set('island', island);
+  return api(host, `/api/baseline/accept?${q}`, { method: 'POST' });
+}
+
+/**
+ * Failure artifacts, under `.motu/` rather than beside the evidence.
+ *
+ * They are outputs of a run, not sources: writing them into the island's folder is what taught people
+ * to gitignore the whole directory, and it is why removing baselines from the repo has to move these
+ * too. Returns the path to show.
+ */
+export function writeRemoteArtifacts(island, file, actual, diff) {
+  const dir = resolve(REPO_ROOT, '.motu/snapshots', island);
+  mkdirSync(dir, { recursive: true });
+  const base = file.replace(/\.png$/, '');
+  writeFileSync(resolve(dir, `${base}.actual.png`), actual);
+  if (diff) writeFileSync(resolve(dir, `${base}.diff.png`), diff);
+  return resolve(dir, `${base}.diff.png`);
+}