@motujs/cli 0.0.0-stage → 0.1.0

package/src/playwright-lagoon.mjs

@@ -0,0 +1,2305 @@
+// Real-browser lagoon check. Boots the focused lagoon (the configured lagoon root via Vite,
+// MOTU_TARGET=island:<tag>) and drives it with Playwright/Chromium, so verification exercises real
+// layout, CSS and paint — not just an in-process DOM. Exposes runLagoon() for `motu island verify`;
+// also runnable directly for a screenshot: `node --import tsx playwright-lagoon.mjs <tag> <fit> [screenshotPath]`.
+import { judgeRenders, scenarioInputs } from './lib/data-flow.mjs';
+import { expectCallsMismatches } from './lib/expect-calls.mjs';
+import { readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { createConnection } from 'node:net';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { REPO_ROOT, paths, color } from './lib/util.mjs';
+import { installIslandRender } from './lib/island-render.mjs';
+
+/** The framework's own lagoon dev-server runner (see lagoon-dev.mjs). */
+const LAGOON_DEV = fileURLToPath(new URL('./lagoon-dev.mjs', import.meta.url));
+
+const LAGOON_DIR = paths.lagoonDir;
+
+
+/**
+ * The lagoon is the loop: without it `verify` has static checks and nothing else. Both of its
+ * preconditions used to fail as a bare spawn ENOENT (an unhandled 'error' event that killed the
+ * process with a stack trace), which reads as a motu bug rather than a missing composition root.
+ * Diagnose them up front instead.
+ */
+function assertLagoonBootable() {
+  if (!existsSync(LAGOON_DIR)) {
+    throw new Error(
+      `no lagoon root at ${paths.rel(LAGOON_DIR)} — the lagoon is where verify mounts the island, so ` +
+        `there is nothing to verify against. Run \`motu init --host <angularjs|next|none>\` to scaffold ` +
+        `one, or point "lagoon" in motu.config.json at an existing composition root.`,
+    );
+  }
+
+}
+
+function waitForPort(port, timeoutMs = 30000) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const tryOnce = () => {
+      const sock = createConnection({ port, host: 'localhost' });
+      sock.once('connect', () => {
+        sock.destroy();
+        resolve();
+      });
+      sock.once('error', () => {
+        sock.destroy();
+        if (Date.now() > deadline) reject(new Error(`vite did not open port ${port} in time`));
+        else setTimeout(tryOnce, 200);
+      });
+    };
+    tryOnce();
+  });
+}
+
+// One server, one browser, for the whole run.
+//
+// Every runtime check used to boot its own Vite and its own Chromium: four per island, sixty for a
+// project the size of acme, each paying a cold dep-optimize before it could answer a question that
+// takes 200ms. The target is now read from the URL as well as the env, so the SAME server can serve
+// every island and every region — a check navigates instead of booting. What still forces a separate
+// server is what is baked at build time (fit, isolation, forced error, transport), so the pool is
+// keyed by exactly those.
+const servers = new Map();
+let sharedBrowser = null;
+let poolClosing = false;
+let exitHooked = false;
+
+/**
+ * Kill the pool on the way out.
+ *
+ * Commands end with `process.exit`, so a `finally` in the caller is not enough — and a leaked vite
+ * holds its port, which the next run then connects to and measures a stale build with.
+ */
+function hookExit() {
+  if (exitHooked) return;
+  exitHooked = true;
+  const kill = () => {
+    for (const entry of servers.values()) stopLagoonProcess(entry.child);
+    servers.clear();
+  };
+  process.on('exit', kill);
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    process.on(sig, () => {
+      kill();
+      process.exit(130);
+    });
+  }
+}
+
+/** Everything the pool holds, released at the end of a command (see `closeLagoonPool`). */
+export async function closeLagoonPool() {
+  poolClosing = true;
+  for (const page of pages.values()) await page.close().catch(() => {});
+  pages.clear();
+  for (const entry of servers.values()) stopLagoonProcess(entry.child);
+  servers.clear();
+  if (sharedBrowser) {
+    await sharedBrowser.close().catch(() => {});
+    sharedBrowser = null;
+  }
+  poolClosing = false;
+}
+
+/**
+ * A CHROMIUM THIS MACHINE ALREADY HAS, when it has one motu did not install.
+ *
+ * `chromium.launch()` insists on the exact build the pinned Playwright expects and ignores a working
+ * browser sitting on disk. That is right on a developer machine, where `npx playwright install` is
+ * one command — and it makes the whole runtime tier unrunnable everywhere that command cannot reach
+ * the CDN: a hardened CI image, a distro- or nix-packaged chromium, an air-gapped build box, a
+ * sandbox whose egress policy does not list `cdn.playwright.dev`. All of them HAVE a browser.
+ *
+ * Opt-in, and never silent — see `browserOverrideNote`. A build motu did not pin can render and
+ * behave differently from the one it did, so a green `--runtime` that used one is claiming slightly
+ * more than it checked unless it says so.
+ */
+export const chromiumOverride = () => process.env.MOTU_CHROMIUM_PATH || null;
+
+/**
+ * What to SAY about the browser, or '' when it is the pinned one.
+ *
+ * Returned rather than printed: this module drives checks, and a check's report is where a caveat
+ * belongs — a line on stdout is read by whoever is watching and lost by everyone else.
+ */
+export function browserOverrideNote() {
+  const exe = chromiumOverride();
+  return exe ? `not the pinned Chromium — launched \`${exe}\` via MOTU_CHROMIUM_PATH` : '';
+}
+
+/** The one Chromium every check drives. */
+async function getBrowser() {
+  const { chromium } = await import('playwright');
+  const exe = chromiumOverride();
+  if (!sharedBrowser || !sharedBrowser.isConnected()) {
+    sharedBrowser = await chromium.launch(exe ? { executablePath: exe } : {});
+  }
+  return sharedBrowser;
+}
+
+// ONE PAGE, RE-AIMED.
+//
+// The lagoon is a single page holding the whole registry, every fixture and a mock transport. Loading
+// it again to look at the next island rebuilt all of that to ask a question that takes milliseconds —
+// which is what made the runtime lane feel like an integration suite. The page is opened once per run
+// and each check asks it to show something else: a different island, a whole region, the same island
+// with a failing backend. Feeding data and firing declared outputs then happen in the page that is
+// already standing, which is the thing a browser-per-spec suite cannot do.
+const pages = new Map();
+/**
+ * How long to wait for an island to paint.
+ *
+ * It used to be fifteen seconds because the page was loading from cold each time — Vite's first-run
+ * dep optimization can reload underneath the check. The page is loaded once now, so a re-aimed mount
+ * paints in tens of milliseconds, and the only thing the long wait still bought was thirty seconds per
+ * island that legitimately renders nothing from its defaults. The first load keeps the long deadline;
+ * everything after it gets the short one.
+ */
+const PAINT_TIMEOUT_COLD = 15000;
+const PAINT_TIMEOUT_WARM = 3000;
+let paintTimeout = PAINT_TIMEOUT_COLD;
+/** How long a mounted island may stay empty before its empty default is taken as its answer. */
+const EMPTY_DEFAULT_SETTLE_MS = 2000;
+/** Diagnostics of the CHECK currently running — console/pageerror listeners are per page, not per check. */
+let diagnosticSink = [];
+/**
+ * Requests that LEFT the machine during the check currently running — same per-page-listener,
+ * per-check-sink shape as `diagnosticSink`.
+ *
+ * A lagoon is supposed to be self-contained: every backend call answered by a stub or the fake fetch,
+ * nothing reaching a real host. Nothing checked that. Worse, the one signal that would have shown it
+ * is deliberately silenced — `NOISE` filters `net::ERR` and `Failed to load resource` out of console
+ * diagnostics, which is right for a dev server's own chatter and exactly wrong for an island quietly
+ * trying to reach the ocean and swallowing the failure in its own catch block. That renders as an
+ * empty state and passes every check.
+ */
+let networkSink = [];
+
+/** Loopback = the lagoon's own dev server (and its reload poll, which can name a different loopback
+ *  host than the page). Anything else is the page reaching for the world. */
+function isLoopback(hostname) {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+}
+
+/** The page for a build posture, opened on first use. */
+/** The view each pooled page is currently showing, so a check never inherits the previous one's. */
+const pageView = new Map();
+
+async function lagoonPage(server, target, view) {
+  const existing = pages.get(server.key);
+  const wanted = view ?? 'region';
+  // A view change is a different render, not a re-aim: the warm path swaps the TARGET in place and
+  // keeps whatever view the page already had. Left unhandled it is a silent contaminated result —
+  // the region-render check inherited the wiring probe's 'mountpoints' page and reported every
+  // declared slot as mounted, including one the arrangement never places.
+  if (existing && !existing.isClosed() && pageView.get(server.key) === wanted) {
+    // Re-aim it. `false` means this build has no harness (an older lagoon entry) — fall back to a load.
+    paintTimeout = PAINT_TIMEOUT_WARM;
+    const aimed = await existing
+      .evaluate(
+        ([t, fit, forceError]) => !!window.__motuLagoonHarness?.mount(t, { fit, forceError }),
+        [target, server.fit ?? '', server.forceError ?? 0],
+      )
+      .catch(() => false);
+    if (aimed) return existing;
+    // A FULL LOAD IS COLD AGAIN, whatever the last check was.
+    //
+    // `paintTimeout` is latched to WARM by the first re-aim and was never put back, so every full
+    // load after it got a fifth of the deadline a first paint is budgeted. Not hypothetical in this
+    // lane: a VIEW change cannot be re-aimed, so it opens a fresh page and loads it cold, and the
+    // region checks change view three times per region — every one of those after the first re-aim
+    // was racing a 3s clock meant for a page that is already booted.
+    //
+    // Found while chasing something else (the target, below in `lagoon-bootstrap`) and fixed on its
+    // own merits: it is a flake waiting on a slow CI runner, and the failure it produces is
+    // "nothing mounted under that slot" — which names the region and not the clock.
+    paintTimeout = PAINT_TIMEOUT_COLD;
+    pageView.set(server.key, view ?? 'region');
+    await existing.goto(lagoonUrl(server, target, view), { waitUntil: 'load' });
+    return existing;
+  }
+  // CLOSE THE PAGE THIS ONE REPLACES. A view change lands here with the previous view's page still
+  // open, and the pool entry below was simply overwritten — so that page was never closed and kept
+  // running its region for the rest of the command. The region checks change view three times per
+  // region: on a 23-region project (Peps) `motu check --runtime` held ~45 live pages by the end, ran
+  // the machine out of memory, and every region ran slower than the one before it — 30 minutes and
+  // a CI timeout for checks that take ~25 alone, and a "hang" for whichever region came last.
+  if (existing) await existing.close().catch(() => {});
+  const browser = await getBrowser();
+  const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
+  await setupPageDiagnostics(page, null);
+  paintTimeout = PAINT_TIMEOUT_COLD;
+  pageView.set(server.key, view ?? 'region');
+  await page.goto(lagoonUrl(server, target, view), { waitUntil: 'load' });
+  pages.set(server.key, page);
+  return page;
+}
+
+/**
+ * Run one check against the shared page: re-aim it, collect this check's diagnostics, restore the
+ * viewport it was handed.
+ */
+async function onLagoonPage({ target, fit, forceError, transport, port, viewport, diagnostics, view }, fn) {
+  const server = await startLagoon({ target, fit, forceError, transport, port });
+  const page = await lagoonPage(server, target, view);
+  const previousSink = diagnosticSink;
+  const previousNetwork = networkSink;
+  diagnosticSink = diagnostics ?? [];
+  networkSink = [];
+  try {
+    if (viewport) await page.setViewportSize(viewport);
+    return await fn(page, server);
+  } finally {
+    diagnosticSink = previousSink;
+    networkSink = previousNetwork;
+  }
+}
+
+/** `/lagoon.html` for a target, on a pooled server. */
+function lagoonUrl(server, target, view) {
+  const q = new URLSearchParams({ target: target ?? '' });
+  if (view) q.set('view', view);
+  if (server.fit) q.set('fit', server.fit);
+  if (server.forceError) q.set('forceError', String(server.forceError));
+  // Verify mounts an island on its OWN defaults; the region's seed is for a human looking at the page.
+  if (String(target ?? '').startsWith('island:')) q.set('seed', 'off');
+  // NO INFERRED COLOUR WHILE THE CHECKS ARE DRIVING. A published lagoon detects its own primary from
+  // its pixels, which depends on what has painted by the time the raster runs — fine for a person
+  // opening the page, and a flaky visual baseline for `island snapshot`, which pictures islands
+  // through this same boot. The harness always sees motu's declared colour.
+  q.set('autoPrimary', 'off');
+  // AND NO PAGE-INSET. `responsive` measures the APPLICATION at each declared viewport; the dock is
+  // not part of the application, so reserving its strip during that run would measure the app 46px
+  // narrower than the viewport it declares and report an overflow the app does not have.
+  q.set('dockInset', 'off');
+  return `http://localhost:${server.port}/lagoon.html?${q}`;
+}
+
+/** Start the lagoon Vite dev server focused on one target ("island:x-…" | "archipelago:id"). */
+async function startLagoonProcess({ target, fit = 'native', port, forceError, transport }) {
+  assertLagoonBootable();
+  // Spawn vite DIRECTLY (not via `pnpm exec`) in its own process group: a pnpm wrapper would spawn
+  // vite as a grandchild that gets orphaned on kill and keeps holding the strict port, so a later run
+  // would connect to the stale server. `detached: true` lets us SIGKILL the whole group in stop().
+  const child = spawn(
+    process.execPath,
+    [LAGOON_DEV, '--port', String(port), '--strictPort'],
+    {
+      // The project root, not the lagoon: the runner resolves motu.config.json by walking up from cwd.
+      cwd: REPO_ROOT,
+      env: {
+        ...process.env,
+        MOTU_NO_SSL: '1',
+        MOTU_TARGET: target,
+        MOTU_FIT: fit,
+        ...(forceError ? { MOTU_FORCE_ERROR: String(forceError) } : {}),
+        ...(transport ? { MOTU_TRANSPORT: transport } : {}),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: true,
+    },
+  );
+  let log = '';
+  child.stdout.on('data', (d) => (log += d));
+  child.stderr.on('data', (d) => (log += d));
+  try {
+    await waitForPort(port);
+  } catch (err) {
+    stopLagoon(child);
+    throw new Error(`${err.message}\n--- vite output ---\n${log}`);
+  }
+  return child;
+}
+
+/**
+ * Take (or start) a pooled server for this build posture. The `target` is passed for the first boot's
+ * env — later callers pass theirs in the URL.
+ */
+async function startLagoon(opts) {
+  // Only what is BAKED at build time can force another server. Target, fit and the forced error all
+  // travel in the URL, so what is left is the transport choice, which vite compiles in.
+  const key = String(opts.transport ?? '');
+  const existing = servers.get(key);
+  if (existing) return { ...existing, target: opts.target, fit: opts.fit, forceError: opts.forceError };
+  hookExit();
+  const port = opts.port ?? 5200 + Math.floor(Math.random() * 700);
+  const child = await startLagoonProcess({ ...opts, port });
+  const entry = { key, child, port };
+  servers.set(key, entry);
+  return { ...entry, target: opts.target, fit: opts.fit, forceError: opts.forceError };
+}
+
+/** A pooled server is not stopped by its caller — the pool outlives the check (see closeLagoonPool). */
+function stopLagoon(server) {
+  if (poolClosing || !server) return;
+  if (servers.has(server.key)) return;
+  stopLagoonProcess(server.child ?? server);
+}
+
+/** Kill the vite process group started by startLagoon. */
+function stopLagoonProcess(child) {
+  if (!child || child.killed) return;
+  try {
+    process.kill(-child.pid, 'SIGKILL'); // negative pid → the whole detached group
+  } catch {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+// Dev-server / framework noise that isn't the island's fault — filtered out of diagnostics.
+const NOISE = /\[vite\]|Download the React DevTools|favicon|net::ERR|Failed to load resource/i;
+
+/**
+ * Wire a page's diagnostics capture: (1) a resolver that finds an island even when it's nested in a
+ * <motu-archipelago> shadow root (the lagoon wraps island targets in a one-island archipelago that
+ * owns the shadow boundary; the island renders LIGHT inside it, so it has no own shadowRoot and isn't
+ * reachable from document.querySelector); (2) console.error / uncaught / unhandled-rejection collection.
+ */
+async function setupPageDiagnostics(page, diagnostics) {
+  // `null` means "the shared sink" — the page outlives any one check, so its listeners write into
+  // whichever check is running (see onLagoonPage).
+  const sink = diagnostics ?? { push: (line) => diagnosticSink.push(line) };
+  await page.addInitScript(() => {
+    window.__motuFindIsland = (t) => {
+      let el = document.querySelector(t);
+      if (!el) {
+        for (const arch of document.querySelectorAll('motu-archipelago')) {
+          const hit = arch.shadowRoot && arch.shadowRoot.querySelector(t);
+          if (hit) {
+            el = hit;
+            break;
+          }
+        }
+      }
+      // React mount path: the island renders in the host's own tree, so there is no <x-tag> element.
+      // Its wrapper carries the tag instead (display:contents, so it is the same box as the content).
+      if (!el) el = document.querySelector('[data-motu-island="' + t + '"]');
+      return el;
+    };
+    // EXPAND printf-style console.error before it leaves the page. React logs its warnings as a
+    // format string plus arguments ("Each child in a list should have a unique \"key\" prop.%s%s"),
+    // and the text Playwright reports is the bare format — the component that broke the rule was in
+    // the arguments and never reached the finding.
+    const origError = console.error.bind(console);
+    console.error = (...args) => {
+      if (typeof args[0] === 'string' && /%[sdifoOc]/.test(args[0])) {
+        let rest = args.slice(1);
+        const text = args[0].replace(/%[sdifoOc]/g, (m) => (rest.length ? (m === '%c' ? (rest.shift(), '') : String(rest.shift())) : m));
+        return origError(text, ...rest);
+      }
+      return origError(...args);
+    };
+    window.addEventListener('unhandledrejection', (e) => {
+      const r = e && e.reason;
+      (window.__motuRejections = window.__motuRejections || []).push(
+        'unhandledrejection: ' + String((r && (r.stack || r.message)) || r),
+      );
+    });
+  });
+  // Rendered output = the island's own shadow (standalone) or its light DOM (nested in an
+  // archipelago), PLUS what its own mount portaled to <body> (a dialog, a sheet) — attributed by React
+  // ancestry, never by position, so lagoon chrome and other mounts stay out. See lib/island-render.mjs.
+  await page.addInitScript(installIslandRender);
+  page.on('console', (msg) => {
+    if (msg.type() === 'error' && !NOISE.test(msg.text())) sink.push(`console.error: ${msg.text()}`);
+  });
+  page.on('pageerror', (err) => {
+    const m = String(err?.message || err);
+    if (!NOISE.test(m)) sink.push(`pageerror: ${m}`);
+  });
+  // Every request the page issues, whether it succeeded or not — a stub gap usually FAILS (the lagoon
+  // points the app at an unresolvable host), and a failed request is exactly what `NOISE` hides.
+  page.on('request', (req) => {
+    const url = req.url();
+    if (!/^https?:/i.test(url)) return; // data:, blob:, about: — not the network
+    try {
+      if (!isLoopback(new URL(url).hostname)) networkSink.push({ method: req.method(), url });
+    } catch {
+      /* unparseable URL — not something to fail a check over */
+    }
+  });
+}
+
+/** What has escaped during the check currently running. Read from inside an `onLagoonPage` callback. */
+function currentNetworkEscapes() {
+  return networkSink.slice();
+}
+
+/**
+ * Requests the lagoon's fake fetch (`@motujs/runtime/postgrest-fetch`) could not resolve against any
+ * declared table/fixture — accumulated in `window.__motuUnscopedRequests` by the fake itself. Read
+ * the same way `window.__motuRejections` is: a call that ran against nothing scoped for it is exactly
+ * as much a finding as an unhandled rejection, and both are populated by code running IN the page.
+ *
+ * Paired with the TOTAL request count the fake saw (`window.__motuFakeFetchRequestCount`) — a run
+ * that made zero requests has zero unscoped ones too, and that is not the same claim as "every
+ * request was covered". `undefined` when the fake never ran at all (a project still on module-alias
+ * stubs), so the caller can skip reporting the check rather than fabricate a count of 0.
+ */
+async function readUnscopedRequests(page) {
+  return page
+    .evaluate(() => {
+      // ANY of the three, not just the first two. A fake that CLAIMED nothing never initialises its
+      // request counter, so a lagoon whose `appRoutes` miss the path the app actually calls looked
+      // identical to one with no fake installed at all — and the `unanswered` list, which is the whole
+      // evidence for that case, was discarded on the way out. That is the exact shape of the gap this
+      // list was added to close, hiding one layer above it.
+      if (
+        window.__motuUnscopedRequests === undefined &&
+        window.__motuFakeFetchRequestCount === undefined &&
+        window.__motuUnansweredRequests === undefined
+      ) {
+        return undefined;
+      }
+      const unscoped = window.__motuUnscopedRequests || [];
+      // Delegated-and-failed: the fake never claimed it, and the dev server answered with an error.
+      const unanswered = window.__motuUnansweredRequests || [];
+      const seen = window.__motuFakeFetchRequestCount || 0;
+      const reach = window.__motuDataReach || { tables: {}, rpcs: [], by: {} };
+      return { unscoped, unanswered, seen, reach };
+    })
+    .catch(() => undefined);
+}
+
+/**
+ * Neutralise auto-generated element ids before two renders are compared.
+ *
+ * React's `useId` hands out ids from a per-root counter, so a second mount legitimately produces
+ * `radix-_r_1_` where the first had `radix-_r_0_`. Any component library built on it (Radix, and so
+ * every shadcn UI) therefore differs between mounts for a reason that says nothing about the island.
+ * Comparing raw HTML made that look like leaked module state, and — in the other direction — could
+ * make two identical scenarios look meaningfully different and pass the data-flow check for free.
+ * Both comparisons are about CONTENT, so strip the counter from both.
+ */
+function normalizeRender(html) {
+  return String(html)
+    .replace(/_r_[0-9a-z]+_/gi, '_r_#_') // React 19
+    .replace(/:r[0-9a-z]+:/gi, ':r#:') //   React 18
+    .replace(/\u00abr[0-9a-z]+\u00bb/gi, 'r#'); // React 18, SSR-safe form
+
+}
+
+/**
+ * Wait for the island's rendered output to SETTLE, and return it.
+ *
+ * "Non-empty" is not the same as "finished". An island that loads through the contract paints an empty
+ * shell first and fills in a tick later, so a snapshot taken at first paint is a race: the re-mount
+ * check compares an empty first mount against a warm, already-filled second one and reports phantom
+ * instability, and the data-flow check compares two shells and calls them identical. Since almost every
+ * island that talks to a backend behaves this way, settling has to be the default, not an opt-in.
+ *
+ * Settled = non-empty and unchanged across consecutive samples. Returns '' if it never rendered.
+ */
+/**
+ * `quietSamples × intervalMs` is a floor every mount pays, and a project pays it per island per
+ * scenario: 3 × 120ms = 360ms, five or six mounts per island, sixteen islands. Most of a
+ * `check --runtime` run was this deliberate waiting.
+ *
+ * 60ms keeps three confirmations — the shape of the check is unchanged, it is the same "has it stopped
+ * moving" question — while halving the floor to 180ms. An island still changing resets the counter and
+ * keeps its full deadline, so what this can miss is a render whose only remaining update lands in a
+ * gap longer than 180ms and never changes anything again. Measured across three projects (16, 4 and 5
+ * islands) nothing regressed.
+ */
+async function waitForStableRender(page, tag, { timeoutMs, quietSamples = 3, intervalMs = 60 } = {}) {
+  const started = Date.now();
+  const deadline = started + (timeoutMs ?? paintTimeout);
+  let last = null;
+  let stable = 0;
+  while (Date.now() < deadline) {
+    let html = '';
+    try {
+      html = await page.evaluate((t) => window.__motuRendered(window.__motuFindIsland(t)), tag);
+    } catch {
+      // Execution context destroyed by Vite's dep re-optimization reload — re-poll on the new one.
+      last = null;
+      stable = 0;
+      html = null;
+    }
+    if (html !== null && html === (last ?? '')) {
+      // EMPTY settles too, after a grace period. Only counting non-empty output as settled meant an
+      // island that legitimately renders nothing from its defaults (a pure projection with no input)
+      // burned the whole timeout on every check — fifteen seconds to observe an emptiness that was
+      // decided in the first frame.
+      const grace = html === '' ? started + 1000 : started;
+      if (++stable >= quietSamples && Date.now() >= grace) return html;
+    } else if (html !== null) {
+      stable = 0;
+      last = html;
+    }
+    await sleep(intervalMs);
+  }
+  return last ?? '';
+}
+
+/**
+ * Mount one island in the real-browser lagoon and report whether it rendered. Optionally screenshots.
+ * Returns { ok, mounted, shadowLength, diagnostics, remountIdentical }.
+ *   diagnostics       — console.error lines + uncaught errors + unhandled rejections (empty = clean).
+ *   remountIdentical  — true/false if the re-mount check ran, null if it couldn't (island never rendered).
+ */
+export async function runLagoon({ tag, fit = 'native', port = 5199, screenshotPath, checkRemount = true, forceError }) {
+  const { chromium } = await import('playwright');
+  const diagnostics = [];
+  return onLagoonPage({ target: `island:${tag}`, fit, port, forceError, viewport: { width: 900, height: 720 }, diagnostics }, async (page, server) => {
+
+    // Poll the DOM until the island upgrades and paints. This is a retry loop rather than a single
+    // waitForFunction because Vite's first-run dep re-optimization can trigger a full page reload that
+    // destroys the execution context mid-check — we simply re-poll on the new one.
+    let result = { mounted: false, shadowLength: 0 };
+    const deadline = Date.now() + paintTimeout;
+    while (Date.now() < deadline) {
+      try {
+        result = await page.evaluate((t) => {
+          const el = window.__motuFindIsland(t);
+          const html = window.__motuRendered(el);
+          return { mounted: !!el, shadowLength: html.length };
+        }, tag);
+        if (result.mounted && result.shadowLength > 0) break;
+      } catch {
+        // Execution context destroyed by an HMR/full reload — wait and retry on the fresh context.
+      }
+      await sleep(200);
+    }
+    // Let an async-loading island finish before anything is measured from it.
+    if (result.mounted) {
+      const settled = await waitForStableRender(page, tag);
+      result.shadowLength = settled.length;
+      result.portals = await portalCount(page, tag);
+    }
+
+    if (screenshotPath) await page.screenshot({ path: screenshotPath, fullPage: true }).catch(() => {});
+
+    // Re-mount identical: dispose the element and mount a fresh clone, then diff the rendered output. A
+    // difference means the island carries accidental module-level state (islands mount/unmount often).
+    let remountIdentical = null;
+    if (checkRemount && result.mounted && result.shadowLength > 0) {
+      remountIdentical = await remountAndCompare(page, tag);
+    }
+
+    const rejections = await page.evaluate(() => window.__motuRejections || []).catch(() => []);
+    for (const r of rejections) if (!NOISE.test(r)) diagnostics.push(r);
+    const fixtureCoverage = await readUnscopedRequests(page);
+    const networkEscapes = currentNetworkEscapes();
+
+    return { ok: result.mounted && result.shadowLength > 0, ...result, diagnostics, remountIdentical, fixtureCoverage, networkEscapes };
+  });
+}
+
+/** How many body-level nodes the island's own mount portaled (0 when none, or unreadable). */
+async function portalCount(page, tag) {
+  return page
+    .evaluate((t) => {
+      const el = window.__motuFindIsland(t);
+      return el ? window.__motuPortals(el).length : 0;
+    }, tag)
+    .catch(() => 0);
+}
+
+/** Snapshot the island's rendered output, swap in a fresh clone (fires disconnect+reconnect), diff. */
+async function remountAndCompare(page, tag) {
+  try {
+    const before = await page.evaluate((t) => {
+      const el = window.__motuFindIsland(t);
+      if (!el) return null;
+      const html = window.__motuRendered(el);
+      // React mount path: swapping the DOM node only detaches React's tree — the "fresh" node would
+      // stay empty and every island would look unstable. Tear the tree down and rebuild it instead,
+      // which is the same question asked of the same code: does anything survive that should not.
+      if (window.__motuLagoon && typeof window.__motuLagoon.remount === 'function') {
+        window.__motuLagoon.remount();
+        return html;
+      }
+      const parent = el.parentNode;
+      const clone = el.cloneNode(false); // attributes only — a genuinely fresh element, no shadow
+      parent.removeChild(el); // disconnectedCallback -> __motuDispose
+      parent.appendChild(clone); // connectedCallback -> fresh mount
+      return html;
+    }, tag);
+    if (before == null) return null;
+
+    const after = await waitForStableRender(page, tag, { timeoutMs: 8000 });
+    return normalizeRender(after) === normalizeRender(before);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run a region's declared FLOWS: seed, fire a declared output, check what the region holds.
+ *
+ * The executable form of a coupling. `wiring-live` proves a declared write reaches its key; this
+ * proves the region ends up in the state the flow says it should — which is the difference between
+ * "the wire is connected" and "answering a card raises the banner's number".
+ *
+ * Returns [{ scenario, step, ok, mismatches: [{ key, expected, actual }] }].
+ */
+/**
+ * `onStep(page, { scenario, step })`, when given, runs after each step settles — `motu lagoon try`
+ * uses it to picture what a step left on screen. It sees the page; it must not drive it.
+ */
+export async function runRegionFlows({ id, port = 5199, scenarios = [], chartWith = null, trace = false, onStep = null }) {
+  const { chromium } = await import('playwright');
+  // See probeWiring: the flows are where writes happen, so this is where a store complaint lands.
+  const diagnostics = [];
+  return onLagoonPage({ target: `archipelago:${id}`, port, viewport: { width: 1280, height: 900 }, diagnostics, view: 'mountpoints' }, async (page, server) => {
+    await page.waitForFunction(() => !!window.__motuLagoon, null, { timeout: 15000 }).catch(() => {});
+    await sleep(400);
+
+    // WHAT MOVED WHILE THE REGION MERELY RENDERED — captured HERE, before the first `emit`.
+    //
+    // Every later read is contaminated for this purpose: a flow's emit goes through the same seam a
+    // component's own output does and writes with the same source, so afterwards "the key moved" is
+    // true whether the component produced it or the harness did. Before any emit, the only thing that
+    // can have moved a key is the region rendering itself.
+    //
+    // WAIT FOR THE REGION, do not sleep at it — the same rule the scenario loop below learned. Reading
+    // after `sleep(400)` alone reported every effect-driven output as never fired on a region where
+    // they all fire: the slots had not mounted yet, so the honest answer was "nothing has rendered",
+    // and it came out as "your components stopped emitting".
+    // RESET, REMOUNT, READ. The lane opens one page for the whole run, so the wiring probe has already
+    // fired every declared write on it — a tally read without clearing says everything emitted,
+    // including outputs a component only fires from a click. Remounting re-runs the effects, so what
+    // lands in the cleared tally is what RENDERING alone produced.
+    await page.evaluate(() => window.__motuLagoon?.resetOutputs?.()).catch(() => {});
+    await page.evaluate(() => window.__motuLagoon?.remount?.()).catch(() => {});
+    await page
+      .waitForFunction(() => document.querySelectorAll('[data-motu-slot]').length > 0, null, { timeout: 10000 })
+      .catch(() => {});
+    await sleep(600);
+    const renderOutputs = await page
+      .evaluate(() => (typeof window.__motuLagoon?.outputs === 'function' ? window.__motuLagoon.outputs() : []))
+      .catch(() => []);
+
+    const out = [];
+    // THE CALL WATERMARK: every landed call carries a monotonic `seq`, so "what did this step cause"
+    // is "what landed after the mark". The first step's mark is taken BEFORE the scenario's reset and
+    // remount, so calls the seed and the mount make are that step's too.
+    const lastSeq = () =>
+      page.evaluate(() => Math.max(0, ...((window.__motuLagoon?.calls?.() ?? []).map((c) => c.seq)))).catch(() => 0);
+    const callsSince = (seq) =>
+      page.evaluate((s) => (window.__motuLagoon?.calls?.() ?? []).filter((c) => c.seq > s), seq).catch(() => []);
+    // THE WORLD each flow runs in (`world` on the flow; absent = the default lagoon). Switching makes
+    // the focused entry re-render the region with that world's answers — its channels rebuilt with
+    // the world's args — so the flow drives what that world hands the app.
+    let activeWorld = 'default';
+    const switchWorld = async (want) => {
+      if (want === activeWorld) return true;
+      const ok = await page.evaluate((w) => window.__motuLagoonHarness?.setWorld?.(w) ?? false, want).catch(() => false);
+      if (!ok) return false;
+      activeWorld = want;
+      await page
+        .waitForFunction(() => document.querySelectorAll('[data-motu-slot]').length > 0, null, { timeout: 10000 })
+        .catch(() => {});
+      await sleep(600);
+      return true;
+    };
+    // WHERE THE LANE'S TIME WENT, per scenario. `region-flow` was 73% of a `check --runtime` on Peps and
+    // printed as one number; the real flows, the flow-mutation mutants, the world mutants and the
+    // null-island mutants all ride this lane, and which of them costs what is the whole question.
+    const timings = [];
+    const laneStarted = Date.now();
+    // ANSWERED GROUPS. A scenario carrying `__killGroup` belongs to a set whose verdict is "did ANY of
+    // these fail?" (a null-island slot and mode). The first failure answers it, so the rest of the
+    // group is not run — on Peps' `actions` the null-island mutants were 260 of 284 scenarios and 89%
+    // of the region's time, nearly all of it replaying flows for groups already answered.
+    const killed = new Set();
+    const suspects = [];
+    const suspectSeen = new Set();
+    // Every mutant the lane carries is tagged by the caller; a scenario with any of these is not a flow.
+    const isMutantScenario = (sc) => Boolean(sc.__nullIsland || sc.__killGroup || sc.__world || /^µ /.test(String(sc.name ?? '')));
+    // HOW LONG EACH REAL STEP TOOK TO HOLD. The real flows run first in the lane, so by the time a
+    // null-island replay of a step runs, the region has already shown how long that step needs. The
+    // replay's assertion is meant to FAIL — a nulled island renders less — and waiting the full 2s for
+    // each failure was most of what null-island still cost after the kill groups (~46s of 70 on
+    // Peps' `actions`). A replay whose assertion still holds holds about as fast as the real step did,
+    // so it gets three times that plus a margin; a step whose real run never held keeps the full 2s.
+    const settledIn = new Map();
+    const budgetFor = (of, index) => {
+      const real = settledIn.get(`${of}#${index}`);
+      return real == null ? 2000 : Math.min(2000, Math.max(400, 3 * real + 250));
+    };
+    for (const scenario of scenarios) {
+      if (scenario.__killGroup && killed.has(scenario.__killGroup)) continue;
+      const scenarioStarted = Date.now();
+      if (!(await switchWorld(scenario.world ?? 'default'))) {
+        out.push({ scenario: scenario.name ?? 'flow', step: 1, ok: false, error: `world "${scenario.world}" is not declared in the lagoon`, mismatches: [], calls: 0, undeclared: [] });
+        continue;
+      }
+      // A NULL-ISLAND MUTANT names one slot to render from defaults or not at all; every other flow
+      // clears it. Set before the reset and remount below, so the region mounts already nulled.
+      const nullable = await page
+        .evaluate((n) => {
+          const set = window.__motuLagoon?.nullIsland;
+          if (!set) return false;
+          set(null);
+          if (n) set(n.slot, n.mode);
+          return true;
+        }, scenario.__nullIsland ?? null)
+        .catch(() => false);
+      // A MUTANT THIS MOUNT PATH CANNOT MAKE IS NOT RUN. The custom-element path (demo-app) has no
+      // null-island switch; running the flow anyway replayed the REAL flow, every one held, and every
+      // slot of demo-app was reported unconstrained — a verdict about a mutant nobody made.
+      if (scenario.__nullIsland && !nullable) {
+        out.push({ scenario: scenario.name ?? 'flow', step: 1, ok: false, unsupported: true, error: 'this mount path cannot null an island', mismatches: [], calls: 0, undeclared: [] });
+        continue;
+      }
+      let mark = await lastSeq();
+      // A fresh REGION per scenario: forget the store, THEN rebuild the tree. One flow CAN leave the
+      // region unrenderable — seed an index past the end of a list and the component that reads it
+      // throws, React tears the tree down, and every later flow reports "no island mounted under that
+      // slot", which is true and completely misleading. Isolation keeps each verdict about its own flow.
+      //
+      // `remount()` ALONE WAS NOT ISOLATION, and the gap silently broke flow-mutation. The store is
+      // registered per archipelago id and deliberately survives a remount, so whatever a scenario put
+      // in it was still there when the next one started. Mutants run after the real flows, so a mutant
+      // whose effect a REAL scenario had already produced asserted against that leftover state and
+      // "still held" — reported as "the assertion does not depend on what the step does" when in truth
+      // the step's own effect was already in the store. Measured on a region whose list island asks a
+      // source to open a detail: the real scenario selected a candidate, the mutant emitted `null`,
+      // nothing happened, and the assertion passed on the previous scenario's selection. That is the
+      // worst shape of failure this check can have — it accuses a correct flow of being a tautology.
+      //
+      // `reset()` is documented "for SCENARIO lanes only" for exactly this call site: it forgets the
+      // keys and re-applies the region's own seed. A flow's own STEPS still build on each other, which
+      // is why this sits outside the step loop.
+      // One `evaluate` each, like the pre-flow reset above: remounting tears down the React tree, and
+      // doing it in the same evaluate as the store reset destroyed the execution context mid-call
+      // ("Execution context was destroyed"), which took the whole flow lane down with it.
+      await page.evaluate(() => window.__motuLagoon?.reset?.()).catch(() => {});
+      // LET THE SOURCE LAND BEFORE THE SCENARIO SEEDS. Restarting the channels starts the region's
+      // first production again, and that write is ASYNC — so without this pause it arrived after the
+      // flow's own seed and overwrote it. Measured across three regions: a Conseil seeded "séance en
+      // cours" rendered the default next-séance fixture instead, and the flow failed on a state it had
+      // asked for and been given, then silently lost. A scenario's seed is the authoritative starting
+      // state; the source's initial answer belongs before it, not on top of it.
+      await sleep(400);
+      // SEED, THEN MOUNT. The flow's seed used to land in step 1, AFTER this remount — so every flow
+      // first mounted the region in its DEFAULT state and only then moved it to the one it asked for.
+      // Whatever the mount did under the wrong state stayed done: on shlink the app's own "fetch the
+      // remote servers when the store starts empty" fired on every flow, because the store WAS empty
+      // for one mount, and a flow declaring "this state asks for nothing" (`expectCalls: []`) could
+      // never hold. Step 1 still applies the seed again after the mount (a source the reset restarted
+      // may answer late); this makes the mount itself happen in the flow's own state.
+      await page
+        .evaluate((seed) => {
+          const lagoon = window.__motuLagoon;
+          for (const [k, v] of Object.entries(seed ?? {})) (lagoon?.seed ?? lagoon?.provide)?.(k, v);
+        }, scenario.seed ?? {})
+        .catch(() => {});
+      // Step 1's calls start HERE: the mount is part of what the flow's first state does (`flow-calls`
+      // counts it), the reset to the region's default above is not.
+      mark = await lastSeq();
+      await page.evaluate(() => window.__motuLagoon?.remount?.()).catch(() => {});
+      // WAIT FOR THE REGION, do not sleep at it. 250ms was enough for stand-in islands and is not
+      // enough for an app's real component tree (Twenty's widgets mount a dozen providers, read a
+      // metadata store and issue queries) — the assertions then ran against a region that had not
+      // rendered yet and reported "the region rendered nothing after this step", which is a timing
+      // artefact wearing the costume of a real failure.
+      await page
+        .waitForFunction(() => document.querySelectorAll('[data-motu-slot]').length > 0, null, { timeout: 10000 })
+        .catch(() => {});
+      for (let [index, step] of (scenario.steps ?? []).entries()) {
+        // The first step of a scenario establishes the page's starting state; the rest build on it.
+        step = index === 0 ? { ...step, __seedNow: true } : step;
+        if (trace) step = { ...step, __trace: true };
+        if (scenario.__nullIsland && scenario.__of) step = { ...step, __budgetMs: budgetFor(scenario.__of, index) };
+        // WHAT THIS STEP CRASHED, if anything. A mutant's crude value can throw inside an island
+        // (`null.toLowerCase()`), the region empties, and the assertion "fails" — which read as the
+        // assertion discriminating. `flow-mutation` needs to tell a crash from a kill, so every step
+        // records the page errors raised while it ran.
+        const crashes = [];
+        const onCrash = (err) => crashes.push(String(err?.message || err).split('\n')[0].slice(0, 200));
+        page.on('pageerror', onCrash);
+        const result = await page.evaluate(
+          async ({ seed, step: st }) => {
+            const lagoon = window.__motuLagoon;
+            if (!lagoon || typeof lagoon.emit !== 'function') return { error: 'no emit seam on this mount path' };
+            // A flow's `seed` is a SEED — the page establishing a starting value — even when the key
+            // belongs to an island. Applying it as a host write made the harness trip motu's own
+            // ownership guard on every produced key a flow starts from.
+            //
+            // ONCE PER SCENARIO, not per step. Re-seeding before every step silently undid whatever
+            // the previous steps had done: a booking flow that picked two seats, then applied a promo,
+            // asserted the discounted total against a fare whose seats had been reset to zero. Every
+            // flow written before this had a single step, so nothing noticed. A journey is a sequence
+            // or it is three unrelated assertions wearing one name.
+            if (st.__seedNow) {
+              for (const [k, v] of Object.entries(seed ?? {})) (lagoon.seed ?? lagoon.provide)(k, v);
+              await new Promise((r) => setTimeout(r, 120));
+            }
+            // Setup done. From here, a host write is a RESPONSE to what the island did.
+            window.__motuSuspects?.reset?.();
+            if (st.emit) {
+              if (!lagoon.emit(st.emit.slot, st.emit.event, st.emit.detail)) {
+                return { error: `no island mounted under slot "${st.emit.slot}"` };
+              }
+            } else if (st.provide) {
+              // The APPLICATION moving its own state, which is how a host-fed key ever changes.
+              for (const [k, v] of Object.entries(st.provide)) lagoon.provide(k, v);
+            } else if (st.click) {
+              // THE USER'S HALF. `emit` enters the region past the component's own handler, so a
+              // control whose callback was dropped leaves an emit-only flow green while the screen is
+              // dead — measured twice. Clicking the RENDERED control makes the component fire its own
+              // declared output, which is the path a person actually takes.
+              //
+              // Accessible name, never a selector: the same rule island scenarios follow, resolved the
+              // same way. Exact match first so a short name is not stolen by a longer control that
+              // contains it, then the narrowest containing match; visible elements only; the whole
+              // document, so a control inside a portal is reachable.
+              const name = String(st.click).trim();
+              const CLICKABLE =
+                'button, [role="button"], input[type="checkbox"], [role="checkbox"], [role="switch"], [role="radio"], [role="menuitem"], [role="tab"], a[href], label, summary';
+              const nameOf = (el) => {
+                const aria = el.getAttribute('aria-label') ?? el.getAttribute('title') ?? el.getAttribute('alt');
+                return `${aria ?? ''} ${el.innerText ?? el.textContent ?? ''}`.replace(/\s+/g, ' ').trim();
+              };
+              const candidates = [...document.querySelectorAll(CLICKABLE)].filter(
+                (el) => el.offsetParent !== null || el.getClientRects().length > 0,
+              );
+              const el =
+                candidates.find((c) => nameOf(c) === name) ??
+                candidates.filter((c) => nameOf(c).includes(name)).sort((a, b) => nameOf(a).length - nameOf(b).length)[0];
+              if (!el) {
+                // NAME WHAT WAS THERE. "nothing is named X" turns writing a flow into guessing at the
+                // accessible names a component happens to produce; the whole point of naming controls
+                // this way is that the names are legible, so print them.
+                const available = [...new Set(candidates.map(nameOf).filter(Boolean))].slice(0, 12);
+                return {
+                  error:
+                    `nothing clickable is named "${name}" — clickable here: ` +
+                    (available.length ? available.map((n) => `"${n}"`).join(', ') : '(nothing clickable is rendered)'),
+                };
+              }
+              el.click();
+            } else if (Object.keys(st.expectRender ?? {}).length) {
+              // A COVERAGE step: no stimulus, only "this slot renders its own island". Legitimate and
+              // not a data flow — some islands take no input at all (Twenty's tasks and timeline
+              // widgets ignore the row they are bound to and render from the record context), so
+              // there is nothing to drive and the claim is still worth making: it is what catches a
+              // slot wired to another island's data.
+            } else {
+              return { error: 'a step must `emit`, `provide`, `click`, or assert with `expectRender`' };
+            }
+            // Settle, then re-check: an assertion may become true a tick or three after the write —
+            // a store subscriber, an effect, a real component's render pass. Polling keeps the check
+            // exactly as strict (it still fails if the claim never becomes true) while removing the
+            // race that a single fixed wait bakes in.
+            // A MUTANT IS EXPECTED TO FAIL, so waiting the full budget for it is pure cost: every
+            // mutant polled 2s before concluding what it was always going to conclude, and
+            // flow-mutation became 30% of a whole `check --runtime` run. A mutant that DOES still hold
+            // holds immediately — the prefix steps already settled the region — so a short budget
+            // loses nothing. Real steps keep the long one, because that is where a slow effect is
+            // genuinely being waited for.
+            // `__budgetMs`: a null-island replay is given what its REAL step needed (set by the lane
+            // below), not the 2s a real step is allowed for an effect nobody has timed yet.
+            const budgetMs = st.__budgetMs ?? (st.__mutant ? 300 : 2000);
+            const settleStarted = Date.now();
+            const settled = async (check) => {
+              const until = Date.now() + budgetMs;
+              for (;;) {
+                if (check()) return true;
+                if (Date.now() >= until) return check();
+                await new Promise((r) => setTimeout(r, 50));
+              }
+            };
+            await new Promise((r) => setTimeout(r, 60));
+            const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+            await settled(() =>
+              Object.entries(st.expect ?? {}).every(([key, expected]) => same(expected, lagoon.read(key))),
+            );
+            const mismatches = Object.entries(st.expect ?? {})
+              .map(([key, expected]) => ({ key, expected, actual: lagoon.read(key) }))
+              .filter((m) => !same(m.expected, m.actual));
+
+            // What the islands SHOW. Read off the mountpoints the lagoon already marks, so this needs
+            // no selector from the project and cannot drift from where the region actually mounted.
+            /**
+             * What a person can PERCEIVE in this slot — not merely what is text.
+             *
+             * `innerText` alone cannot see a text field's value or a control's accessible name, so a
+             * booking flow could not assert that the passenger form shows "Ada Lovelace" (an input
+             * value) or that the seat map offers "Seat 2A, available" (an aria-label). Both are
+             * plainly perceivable — one on screen, one to a screen reader — and an island made of form
+             * controls had almost nothing assertable without them.
+             *
+             * Checkbox and radio state is included as `checked`/`unchecked` for the same reason: it is
+             * the control's value, and it is the only thing that distinguishes a ticked box from an
+             * empty one.
+             */
+            const perceivable = (el) => {
+              const parts = [el.innerText ?? el.textContent ?? ''];
+              const own = el.getAttribute?.('aria-label');
+              if (own) parts.push(own);
+              for (const f of el.querySelectorAll('input, textarea, select')) {
+                if (f.type === 'checkbox' || f.type === 'radio') parts.push(f.checked ? 'checked' : 'unchecked');
+                else if (f.value) parts.push(f.value);
+                if (f.placeholder) parts.push(f.placeholder);
+              }
+              for (const n of el.querySelectorAll('[aria-label], [alt], [title]')) {
+                for (const a of ['aria-label', 'alt', 'title']) {
+                  const v = n.getAttribute(a);
+                  if (v) parts.push(v);
+                }
+              }
+              // A CONTROL'S STATE, the way a screen reader announces it — "Not yet accepted, pressed".
+              // A toggle group's value lives in `aria-pressed`, a tab's in `aria-selected`, a nav
+              // link's in `aria-current`; none of it is text, so a flow could not say which choice a
+              // filter showed (host-app's `corpus-filter`, found by `null-island`). Each is reported
+              // as `<name> pressed|selected|current`, beside the name, as `checked` is for a checkbox.
+              for (const n of el.querySelectorAll('[aria-pressed="true"], [aria-selected="true"], [aria-current]:not([aria-current="false"])')) {
+                const name = (n.getAttribute('aria-label') || n.innerText || n.textContent || '').replace(/\s+/g, ' ').trim();
+                const state = n.getAttribute('aria-pressed') === 'true' ? 'pressed' : n.getAttribute('aria-selected') === 'true' ? 'selected' : 'current';
+                if (name) parts.push(`${name} ${state}`);
+              }
+              return parts.join(' ').replace(/\s+/g, ' ').trim();
+            };
+            /**
+             * THE SLOT, PLUS WHAT IT OPENED THROUGH A PORTAL.
+             *
+             * `expectRender` is slot-scoped, and a dialog/popover/dropdown/select built on a portal
+             * renders as a SIBLING of the slot under `document.body` — so everything a member sees
+             * after clicking a control in that slot was invisible to the assertion. A flow could open
+             * the challenges catalogue, click an info trigger and watch the warning appear on screen,
+             * and still have nothing it was allowed to assert. motu already met the mirror of this on
+             * the CLICK side and fixed it there (`runInteractions` searches page-wide "because a
+             * dialog/popover/dropdown built on a portal renders as a SIBLING of the island"); this is
+             * the same fix on the assertion side.
+             *
+             * ARIA OWNERSHIP, NOT "everything under body". The relation is read from the accessibility
+             * tree — `aria-controls` / `aria-owns` / `aria-describedby`, which is precisely how a
+             * portal declares "that content over there is mine" and how a screen reader follows it.
+             * Radix (and every shadcn component on it) wires these already: a trigger carries
+             * `aria-controls` to its content's id, so nothing in the application has to be annotated
+             * for motu. Widening to "any portal" instead would have let ANOTHER island's open dialog
+             * satisfy this slot's assertion, which is the coupling `expectRender` exists to catch.
+             *
+             * TRANSITIVE, because overlays nest: the slot owns the dialog, and a trigger INSIDE the
+             * dialog owns the popover. One hop would have stopped at the dialog.
+             *
+             * Three guards keep it honest: content already inside the slot is not re-collected;
+             * content that sits inside ANOTHER slot belongs to that slot and is skipped, so this can
+             * never let one island's render answer for another's; and invisible targets are ignored
+             * (`forceMount` keeps a closed overlay in the DOM, and a closed overlay is not perceived).
+             */
+            const perceivableRoots = (slotEl) => {
+              const roots = [slotEl];
+              const seen = new Set([slotEl]);
+              const visible = (el) => el.getClientRects().length > 0 || el.offsetParent !== null;
+              // Never collect content that belongs to ANOTHER slot: one island's overlay must not be
+              // able to satisfy another island's assertion, which is the coupling this check exists
+              // to catch. And never re-collect what the slot already contains.
+              // Also never collect a node that a root ALREADY collected contains: a dialog's own
+              // `aria-describedby` points at its description, which is inside the dialog, and adding
+              // it again duplicated the whole overlay in the reported surface.
+              const claimable = (el) =>
+                el &&
+                !seen.has(el) &&
+                !slotEl.contains(el) &&
+                !el.closest('[data-motu-slot]') &&
+                visible(el) &&
+                !roots.some((r) => r.contains(el));
+
+              /**
+               * WHO RENDERED THIS NODE — read from React, which is the only place that still knows.
+               *
+               * A portal moves a node in the DOM and NOT in the React tree: the content is still a
+               * child of the component that rendered it, and the fiber's `return` chain says so. So
+               * walking up from a portalled node until a host fiber lands inside the slot answers
+               * "did this slot's island put this on screen?" exactly, with no annotation in the
+               * application and no guessing from position in the DOM.
+               *
+               * This is what ARIA alone could not do. `aria-controls` works for a Radix trigger, but
+               * a dialog opened from component state (`<ResponsiveDialog open={open}>`) has no
+               * trigger and therefore no ARIA relation to follow at all — measured on peps' own
+               * challenges panel, where the slot contained ZERO aria-owning elements while a dialog
+               * it had plainly rendered sat under `body`. Both paths are kept: fibers are exact but
+               * React-specific, ARIA is portable and covers a host motu cannot read fibers from.
+               */
+              // `Object.keys`, not `for...in`: React attaches the fiber as an OWN property, and
+              // `for...in` would walk the whole DOM prototype chain to find it.
+              const FIBER = (node) => {
+                for (const k of Object.keys(node)) {
+                  if (k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$')) return node[k];
+                }
+                return null;
+              };
+              const renderedInsideSlot = (node) => {
+                let f = FIBER(node);
+                // Bounded: a corrupted or cyclic chain must not turn an assertion into a hang.
+                for (let hops = 0; f && hops < 4000; hops++, f = f.return) {
+                  const sn = f.stateNode;
+                  if (sn && sn.nodeType === 1 && slotEl.contains(sn)) return true;
+                }
+                return false;
+              };
+
+              // A portal's DOM home is a container, normally `document.body`. Scanning its children
+              // (rather than the whole document) keeps this cheap and is where every portal lands.
+              for (const node of Array.from(document.body.children)) {
+                if (!claimable(node)) continue;
+                if (!renderedInsideSlot(node)) continue;
+                seen.add(node);
+                roots.push(node);
+              }
+
+              // ARIA OWNERSHIP, as the second path — `aria-controls` / `aria-owns` /
+              // `aria-describedby` is how a portal declares that content is its own and how a screen
+              // reader follows it. Transitive, because overlays nest: the slot owns the dialog, and a
+              // trigger INSIDE the dialog owns the popover.
+              for (let i = 0; i < roots.length && roots.length < 64; i++) {
+                const from = roots[i];
+                const holders = [from, ...from.querySelectorAll('[aria-controls], [aria-owns], [aria-describedby]')];
+                for (const holder of holders) {
+                  for (const attr of ['aria-controls', 'aria-owns', 'aria-describedby']) {
+                    const raw = holder.getAttribute?.(attr);
+                    if (!raw) continue;
+                    for (const id of raw.split(/\s+/)) {
+                      if (!id) continue;
+                      let target = null;
+                      try {
+                        target = document.getElementById(id);
+                      } catch {
+                        target = null;
+                      }
+                      if (!claimable(target)) continue;
+                      seen.add(target);
+                      roots.push(target);
+                    }
+                  }
+                }
+              }
+              return roots;
+            };
+            const perceivableWithPortals = (slotEl) =>
+              perceivableRoots(slotEl)
+                .map(perceivable)
+                .join(' ')
+                .replace(/\s+/g, ' ')
+                .trim();
+            const renderText = (slot) => {
+              const el = document.querySelector(`[data-motu-slot="${slot}"]`);
+              return el ? perceivableWithPortals(el) : null;
+            };
+            /**
+             * CASE-INSENSITIVE, because `innerText` reports what `text-transform` produced.
+             *
+             * A flow asserts that DATA reached a slot. Whether the slot's stylesheet happens to
+             * uppercase it is a presentational choice that can change without the data flow changing
+             * at all — and an assertion that breaks when a caption's letter-case is restyled is
+             * asserting the wrong thing. Found the day the focused lagoon started applying the
+             * project's stylesheet: every flow asserting "changed" or "week-actions" failed against
+             * "CHANGED" and "WEEK-ACTIONS", having passed for as long as the page rendered naked.
+             *
+             * It does not weaken the check. A wrong value and another island's text both still fail;
+             * only the casing stops mattering.
+             */
+            const contains = (haystack, needle) => haystack.toLowerCase().includes(String(needle).toLowerCase());
+            await settled(() =>
+              Object.entries(st.expectRender ?? {}).every(([slot, want]) => {
+                const text = renderText(slot);
+                if (text === null) return false;
+                const wants = typeof want === 'string' ? { text: want } : want;
+                return (
+                  (wants.text == null || contains(text, wants.text)) &&
+                  (wants.notText == null || !contains(text, wants.notText))
+                );
+              }),
+            );
+            const renderMismatches = [];
+            for (const [slot, want] of Object.entries(st.expectRender ?? {})) {
+              const el = document.querySelector(`[data-motu-slot="${slot}"]`);
+              if (!el) {
+                renderMismatches.push({ key: `render:${slot}`, expected: want, actual: 'nothing mounted under that slot' });
+                continue;
+              }
+              const text = perceivableWithPortals(el);
+              const wants = typeof want === 'string' ? { text: want } : want;
+              if (wants.text != null && !contains(text, wants.text)) {
+                renderMismatches.push({ key: `render:${slot}`, expected: `text containing ${JSON.stringify(wants.text)}`, actual: text });
+              }
+              if (wants.notText != null && contains(text, wants.notText)) {
+                renderMismatches.push({ key: `render:${slot}`, expected: `text NOT containing ${JSON.stringify(wants.notText)}`, actual: text });
+              }
+            }
+            if (!Object.keys(st.expect ?? {}).length && !Object.keys(st.expectRender ?? {}).length && st.expectCalls === undefined) {
+              return { error: 'a step must assert something — `expect` a region key, `expectRender` an island, or `expectCalls` the backend' };
+            }
+            // Did the region survive its own flow? A step that leaves nothing on screen has broken
+            // something, even when every key it asserted holds the right value.
+            const alive = document.querySelectorAll('[data-motu-slot]').length > 0;
+            // FOR `motu diff`: what every slot renders, read the way `expectRender` reads it — through
+            // portals — so a dialog an island opened is part of its slot's surface on both sides.
+            let surface = null;
+            if (st.__trace) {
+              surface = {};
+              for (const el of document.querySelectorAll('[data-motu-slot]')) {
+                const slot = el.getAttribute('data-motu-slot');
+                const text = perceivableWithPortals(el);
+                surface[slot] = surface[slot] ? `${surface[slot]} | ${text}` : text;
+              }
+            }
+            // How long the step's assertions took to hold — what a null-island replay of it is allowed.
+            const settleMs = mismatches.length || renderMismatches.length ? null : Date.now() - settleStarted;
+            return { mismatches: [...mismatches, ...renderMismatches], alive, surface, settleMs };
+          },
+          { seed: scenario.seed ?? {}, step },
+        );
+        // A beat for the calls a step starts to land, then read them against the mark.
+        await sleep(150);
+        page.off('pageerror', onCrash);
+        const landed = await callsSince(mark);
+        // THE SMELL, read per step — the ledger is reset at the start of every step (above), so read
+        // once at the end of the lane it only ever held the LAST step's suspicions, and which step was
+        // last was whichever mutant happened to run last. Real flows only: a mutant's crude emit
+        // provoking a host write says nothing about how the application is written.
+        if (!isMutantScenario(scenario) && !step.__mutant) {
+          for (const sus of await page.evaluate(() => window.__motuSuspects?.list?.() ?? []).catch(() => [])) {
+            const key = JSON.stringify(sus);
+            if (!suspectSeen.has(key)) {
+              suspectSeen.add(key);
+              suspects.push(sus);
+            }
+          }
+        }
+        mark = landed.reduce((m, c) => Math.max(m, c.seq), mark);
+        // WHAT THE STEP WAS ALLOWED TO ASK FOR (`expectCalls`), held against what it asked for. Read
+        // after the beat above, with the same `mark` `flow-calls` uses, so step 1 includes the mount.
+        const callMismatches = result.error ? [] : expectCallsMismatches(step.expectCalls, landed);
+        // WHAT THIS STEP LEFT BEHIND, for `motu diff`: every key the region holds, and what each slot
+        // renders (the same perceivable surface `expectRender` reads). Values pass through JSON so
+        // a function or a cycle cannot break the comparison.
+        const traced = !trace
+          ? null
+          : await page
+              .evaluate(() => {
+                const safe = (v) => {
+                  try {
+                    return JSON.parse(JSON.stringify(v ?? null));
+                  } catch {
+                    return String(v);
+                  }
+                };
+                const keys = safe(window.__motuLagoon?.snapshot?.() ?? {});
+                const surface = null;
+                return { keys, surface };
+              })
+              .catch(() => null);
+        if (onStep) await onStep(page, { scenario: scenario.name ?? 'flow', step: index + 1 }).catch(() => {});
+        out.push({
+          ...(traced
+            ? { trace: { keys: traced.keys, surface: result.surface ?? {}, calls: landed.map((c) => `${c.method} ${c.label || c.url} ${c.status}`) } }
+            : {}),
+          scenario: scenario.name ?? 'flow',
+          step: index + 1,
+          ok: !result.error && result.mismatches.length === 0 && callMismatches.length === 0 && result.alive !== false,
+          error: result.error ?? (result.alive === false ? 'the region rendered nothing after this step' : null),
+          mismatches: [...(result.mismatches ?? []), ...callMismatches],
+          crashed: crashes[0] ?? null,
+          calls: landed.length,
+          // A FAILURE NOTHING DECLARED. A declared one (a fixture's `status: 500`) is the flow's own
+          // state and never lands here.
+          undeclared: landed.filter((c) => !c.ok && !c.declared),
+        });
+        if (!scenario.__nullIsland && !scenario.__killGroup && !step.__mutant && result.settleMs != null) {
+          settledIn.set(`${scenario.name ?? 'flow'}#${index}`, result.settleMs);
+        }
+        // A failing step answers the group; the steps after it cannot turn "it failed" into "it held".
+        if (scenario.__killGroup && !out[out.length - 1].ok) {
+          killed.add(scenario.__killGroup);
+          break;
+        }
+      }
+      timings.push({ scenario: scenario.name ?? 'flow', ms: Date.now() - scenarioStarted, steps: (scenario.steps ?? []).length });
+    }
+    const scenariosMs = Date.now() - laneStarted;
+    // One beat before reading: a host effect answering an island lands a tick later, and the last
+    // step's assertion returns before it does.
+    await sleep(300);
+    // No null island outlives the run — the page is pooled and the next check re-aims it.
+    await page.evaluate(() => window.__motuLagoon?.nullIsland?.(null)).catch(() => {});
+    // BACK TO THE DEFAULT WORLD before anything else reads this page: it is pooled, and the next check
+    // re-aims it rather than reloading — a world left on would be inherited by a check that never asked.
+    if (activeWorld !== 'default') await switchWorld('default');
+    // `suspects` — the smell: an island emitted, and the HOST answered by writing a key some island
+    // reads. Declared ownership cannot see this — the declaration is consistent, it is just not honest —
+    // so it is reported as a suspicion, never as a violation. Collected per real step, in the loop above.
+    // What the CHANNELS actually produced while the flows ran — the inbound seam's provenance. The
+    // declared `sources` say who feeds each host-fed key; this says who really did.
+    // WHERE THE INPUT CAME FROM, read after the flows have run.
+    const provenance = await page
+      .evaluate(() => (typeof window.__motuLagoon?.hostCalls === 'function' ? window.__motuLagoon.hostCalls() : []))
+      .catch(() => []);
+    // EVERY DOOR, not just the traced one. A region whose islands talk through the contract, or whose
+    // services read through the wire, recorded nothing in `hostCalls` and read as a region that
+    // fetched nothing — accurate about that one ledger and wrong about the question.
+    const outbound = await page
+      .evaluate(() => (typeof window.__motuLagoon?.outbound === 'function' ? window.__motuLagoon.outbound() : []))
+      .catch(() => []);
+    const channels = await page.evaluate(() =>
+      window.__motuLagoon && typeof window.__motuLagoon.channels === 'function' ? window.__motuLagoon.channels() : null,
+    );
+    // Which keys the region ended up HOLDING. A declared source that was seeded instead of installed
+    // leaves its keys full, and one that nothing feeds leaves them empty — the same "no channel wrote
+    // this" reads as either, and only one of the two is a real finding.
+    const held = await page
+      .evaluate(() => (typeof window.__motuLagoon?.held === 'function' ? window.__motuLagoon.held() : []))
+      .catch(() => []);
+    // THE CHART, LAST — after every ledger above has been read, because it replays the flows again
+    // and would add its own calls to them. Same page, no navigation: `chartRegion` is the in-page
+    // function the dock uses, so the check and the dock place every what-if by the same rule.
+    // The focused entry carries no evidence of its own, so the caller hands the chart the region's
+    // real flows (not the mutants) and each island's scenarios.
+    const chart = !chartWith
+      ? null
+      : await page
+          .evaluate(
+            ({ rid, evidence }) => (typeof window.__motuLagoonChart === 'function' ? window.__motuLagoonChart(rid, evidence) : null),
+            { rid: id, evidence: { flows: { [id]: chartWith.flows }, scenarios: chartWith.scenarios } },
+          )
+          .catch((err) => ({ error: String(err?.message ?? err) }));
+    return { flows: out, suspects, diagnostics, channels, provenance, outbound, held, renderOutputs, chart, timings, scenariosMs };
+  });
+}
+
+/**
+ * Probe every wire a region DECLARES: fire each `writes` event and see whether its key moved.
+ *
+ * This is the contract test the archipelago can write for itself. Nothing is hand-scripted and nothing
+ * touches the DOM — the harness can only emit what an island declares as an output, so the probe list
+ * IS the declaration. What it catches is the failure types cannot: a wire that resolves, compiles and
+ * never carries anything ("declared but never fired"), which is what a broken change looks like from
+ * the outside.
+ *
+ * Returns [{ slot, event, key, moved }].
+ */
+export async function probeWiring({ id, port = 5199, islands = [] }) {
+  const { chromium } = await import('playwright');
+  // Diagnostics belong to the page that WRITES. The console check runs on a page that only mounts the
+  // region, so anything the store says about a bad write — the ownership guard above all — was raised
+  // where nobody was listening. Collect them here and hand them back with the results.
+  const diagnostics = [];
+  return onLagoonPage({ target: `archipelago:${id}`, port, viewport: { width: 1280, height: 900 }, diagnostics, view: 'mountpoints' }, async (page, server) => {
+    await page.waitForFunction(() => !!window.__motuLagoon, null, { timeout: 15000 }).catch(() => {});
+    await sleep(400);
+
+    const results = [];
+    for (const island of islands) {
+      for (const [event, target] of Object.entries(island.writes ?? {})) {
+        const keys = typeof target === 'string' ? [target] : Object.values(target);
+        const fields = typeof target === 'string' ? null : Object.entries(target);
+        const probe = await page.evaluate(
+          ({ slot, event: ev, keys: ks, fields: fs }) => {
+            const lagoon = window.__motuLagoon;
+            if (!lagoon || typeof lagoon.emit !== 'function' || typeof lagoon.read !== 'function') {
+              return { kind: 'no-seam' };
+            }
+            // A sentinel that keeps the SHAPE of what is there. The first version wrote a string over
+            // the week's mission array, the island that renders it threw on `.filter`, React unmounted
+            // the tree, and every island probed after that looked unmounted — the probe destroying the
+            // page it was measuring. Different value, same type: enough to see the store move, safe
+            // enough to leave the region standing.
+            const nudge = (v) => {
+              if (typeof v === 'number') return v + 1;
+              if (typeof v === 'boolean') return !v;
+              if (typeof v === 'string') return `${v}\u00b7probe`;
+              if (Array.isArray(v)) return v.length ? v.slice(0, v.length - 1) : ['motu-probe'];
+              if (v && typeof v === 'object') return { ...v };
+              return 'motu-probe';
+            };
+            const read = () => ks.map((k) => lagoon.read(k));
+            const before = read();
+            const detail = fs
+              ? Object.fromEntries(fs.map(([field, key]) => [field, nudge(lagoon.read(key))]))
+              : nudge(lagoon.read(ks[0]));
+            if (!lagoon.emit(slot, ev, detail)) return { kind: 'not-mounted' };
+            const after = read();
+            const rows = ks.map((k, i) => ({ key: k, moved: before[i] !== after[i] }));
+            // Put the region back the way it was, so a later probe measures the page and not the wake
+            // of this one.
+            // Put it back as a SEED, not a host write: a rollback must not look like the host
+            // reaching into a key an island owns (that is what the ownership guard is for).
+            ks.forEach((k, i) => (lagoon.seed ?? lagoon.provide)(k, before[i]));
+            return { kind: 'measured', rows };
+          },
+          { slot: island.slot, event, keys, fields },
+        );
+        if (probe.kind === 'measured') {
+          for (const row of probe.rows) results.push({ slot: island.slot, event, ...row });
+        } else {
+          results.push({ slot: island.slot, event, key: keys.join(', '), moved: null, reason: probe.kind });
+        }
+      }
+    }
+    return { results, diagnostics };
+  });
+}
+
+/**
+ * Run axe against one island, in the lagoon, per scenario.
+ *
+ * Cheap because the browser is already open, and it catches the class of mistake that types cannot see
+ * at all: a clickable div, a control with no accessible name, text that fails contrast. Scoped to the
+ * island's own subtree — the lagoon's chrome is motu's, and an island should not fail for it.
+ */
+export async function axeLagoon({ tag, port = 5199, scenarios = [] }) {
+  const { chromium } = await import('playwright');
+  const { createRequire } = await import('node:module');
+  const require = createRequire(import.meta.url);
+  const axeSource = readFileSync(require.resolve('axe-core'), 'utf8');
+  return onLagoonPage({ target: `island:${tag}`, port, viewport: { width: 1280, height: 900 } }, async (page, server) => {
+    const deadline = Date.now() + paintTimeout;
+    while (Date.now() < deadline) {
+      const ready = await page
+        .evaluate((t) => {
+          const el = window.__motuFindIsland(t);
+          return !!el && window.__motuRendered(el).trim().length > 0;
+        }, tag)
+        .catch(() => false);
+      if (ready) break;
+      await sleep(250);
+    }
+    // FREEZE MOTION BEFORE MEASURING, the same way the snapshot lane does and for the same reason.
+    //
+    // axe reads computed colour, and an element mid-fade has an opacity the design never ships. The
+    // kit's lists swim in on a stagger, so re-seeding a scenario restarts the entrance and axe caught
+    // whichever row was still transparent — reporting a "serious" contrast failure on a colour that
+    // measures 5.3:1 at rest, and naming a different nth-child on each run. A check whose findings
+    // move between runs is a check people learn to ignore.
+    await page.addStyleTag({
+      content: '*,*::before,*::after{animation:none!important;transition:none!important}',
+    });
+    await page.addScriptTag({ content: axeSource });
+
+    const findings = [];
+    const list = scenarios.length ? scenarios : [{ name: 'default', seed: {} }];
+    const owned = scenarioKeys(list);
+    for (const scenario of list) {
+      await provideScenario(page, scenario.seed, { afterMount: scenario.afterMount, tag, owned });
+      const violations = await page.evaluate(async (t) => {
+        const el = window.__motuFindIsland(t);
+        if (!el) return [];
+        // A `display: contents` wrapper is not a valid axe context; its painted content is.
+        const target = el.getBoundingClientRect().height ? el : el.firstElementChild;
+        // What the island portaled (a dialog) is its UI too, and the part most likely to lack a name.
+        const include = [target, ...window.__motuPortals(el)].filter(Boolean);
+        if (!include.length) return [];
+        const res = await window.axe.run({ include }, { resultTypes: ['violations'] });
+        return res.violations.map((v) => ({
+          id: v.id,
+          impact: v.impact,
+          help: v.help,
+          nodes: v.nodes.length,
+          // The first offender, so a finding says WHERE — a count alone sends you hunting.
+          where: v.nodes[0]?.target?.join(' ') ?? '',
+          html: (v.nodes[0]?.html ?? '').slice(0, 120),
+        }));
+      }, tag);
+      for (const v of violations) findings.push({ scenario: scenario.name ?? 'default', ...v });
+    }
+    return findings;
+  });
+}
+
+/**
+ * Capture one island's rendered pixels, per scenario × viewport, in one browser.
+ *
+ * Same seams as everything else here: scenarios come from the island's declared evidence and are
+ * driven through `provide()`, viewports from `lagoon.config.json`. Nothing accepts a selector or a
+ * script — a capture can only put the island in a state the island itself declares, which is what
+ * keeps this a harness rather than a second, untyped test suite.
+ *
+ * Returns [{ scenario, viewport, width, png }].
+ */
+export async function captureLagoon({ tag, port = 5199, scenarios = [], viewports = [] }) {
+  const { chromium } = await import('playwright');
+  return onLagoonPage({ target: `island:${tag}`, port, viewport: { width: viewports[0]?.width ?? 1280, height: 900 } }, async (page, server) => {
+
+    const deadline = Date.now() + paintTimeout;
+    while (Date.now() < deadline) {
+      const ready = await page
+        .evaluate((t) => {
+          const el = window.__motuFindIsland(t);
+          return !!el && window.__motuRendered(el).trim().length > 0;
+        }, tag)
+        .catch(() => false);
+      if (ready) break;
+      await sleep(250);
+    }
+
+    // Motion makes a baseline flap. Freeze it rather than sampling and hoping.
+    await page.addStyleTag({
+      content: '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}',
+    });
+
+    const shots = [];
+    const list = scenarios.length ? scenarios : [{ name: 'default', seed: {} }];
+    const owned = scenarioKeys(list);
+    for (const scenario of list) {
+      // NO REMOUNT: this lane measures pixels, and a fresh mount replays every entrance animation the
+      // shot would then capture mid-flight. The reset inside still runs, so each picture is of the
+      // scenario it is named after.
+      await provideScenario(page, scenario.seed, { afterMount: scenario.afterMount, remount: false, owned });
+      for (const vp of viewports) {
+        await page.setViewportSize({ width: vp.width, height: 900 });
+        await sleep(250);
+        const handle = await page.evaluateHandle((t) => window.__motuFindIsland(t), tag);
+        const el = handle.asElement();
+        // An island that PORTALED something (a dialog over the page) is pictured as the viewport it
+        // covers — an element shot of its own box would miss the very thing it shows. The lagoon's
+        // chrome is hidden for that shot, so the picture is the island's and not the furniture's.
+        const portaled = el ? await el.evaluate((n) => window.__motuPortals(n).length) : 0;
+        if (portaled) {
+          await page.addStyleTag({ content: '[data-motu-chrome]{visibility:hidden!important}' });
+          shots.push({
+            scenario: scenario.name ?? 'default',
+            viewport: vp.name,
+            width: vp.width,
+            png: await page.screenshot({ animations: 'disabled' }),
+            portals: portaled,
+          });
+          continue;
+        }
+        // A `display: contents` wrapper cannot be screenshotted; its first painted child can.
+        const target = (await el?.evaluateHandle((n) => (n.getBoundingClientRect().height ? n : n.firstElementChild)))?.asElement();
+        const png = target
+          ? await target.screenshot({ animations: 'disabled' }).catch(() => null)
+          : await page.screenshot({ animations: 'disabled' });
+        if (png) shots.push({ scenario: scenario.name ?? 'default', viewport: vp.name, width: vp.width, png });
+      }
+    }
+    return shots;
+  });
+}
+
+/**
+ * Does the COMPOSED page fit, and is it usable — at each declared viewport.
+ *
+ * `responsive` and `a11y` are ISLAND checks: each island is mounted alone and asked whether it fits.
+ * Every island passes that on its own and the page still overflows, because the arrangement is where
+ * a layout breaks — a three-column grid with fixed rails fits nothing at 390px, and no island in it
+ * is at fault. The same blind spot as the frame that renders one island's data in another's slot.
+ *
+ * Measured on the first project to have a region of its own: every island green at every viewport,
+ * and the composed page scrolling sideways on a phone. A human opened the lagoon and saw it in a
+ * second; nothing in the suite could.
+ *
+ * Overflow of the DOCUMENT, not of the region — the same signal the island check uses, for the same
+ * reason: a card that scrolls its own table on purpose is fine, a page the reader has to pan is not.
+ */
+export async function auditRegionLagoon({ id, port = 5199, states = [], viewports = [], a11y = true }) {
+  const { chromium } = await import('playwright');
+  const { createRequire } = await import('node:module');
+  const require = createRequire(import.meta.url);
+  const axeSource = a11y ? readFileSync(require.resolve('axe-core'), 'utf8') : null;
+
+  return onLagoonPage(
+    { target: `archipelago:${id}`, port, viewport: { width: viewports[0]?.width ?? 1280, height: 900 }, view: 'region' },
+    async (page) => {
+      await page.waitForFunction(() => !!window.__motuLagoon, null, { timeout: 15000 }).catch(() => {});
+      await page
+        .waitForFunction(() => document.querySelectorAll('[data-motu-slot]').length > 0, null, { timeout: 15000 })
+        .catch(() => {});
+
+      const out = [];
+      const list = states.length ? states : [{ name: 'default', seed: {} }];
+      for (const state of list) {
+        await page.evaluate(() => window.__motuLagoon?.remount?.()).catch(() => {});
+        await page
+          .waitForFunction(() => document.querySelectorAll('[data-motu-slot]').length > 0, null, { timeout: 10000 })
+          .catch(() => {});
+        await page.evaluate((seed) => {
+          const l = window.__motuLagoon;
+          if (l) for (const [k, v] of Object.entries(seed || {})) l.seed(k, v);
+        }, state.seed ?? {});
+
+        for (const vp of viewports) {
+          await page.setViewportSize({ width: vp.width, height: 900 });
+          // Two beats: one for the resize to land, one for anything that re-measures on it.
+          await sleep(220);
+          const m = await page.evaluate(() => {
+            const doc = document.documentElement;
+            return {
+              overflow: doc.scrollWidth - doc.clientWidth,
+              client: doc.clientWidth,
+              slots: document.querySelectorAll('[data-motu-slot]').length,
+              // What the region view actually put on the page, for when the measurement disagrees
+              // with a human looking at the same URL.
+              // The ARRANGEMENT's own element, by class — `body.firstElementChild` is a mount
+              // container in both views and tells you nothing about which one you are in.
+              frame: !!document.querySelector('.rv, [class*="Frame"], main, aside'),
+              widest: Math.max(0, ...[...document.body.querySelectorAll('*')].map((e) => e.scrollWidth)),
+              styled: !!document.getElementById('motu-island-styles'),
+              cols: getComputedStyle(document.querySelector('.rv-body') ?? document.body).gridTemplateColumns,
+            };
+          });
+          out.push({ scenario: state.name ?? 'default', viewport: vp.name, width: vp.width, ...m });
+        }
+      }
+
+      let violations = [];
+      if (axeSource) {
+        // One axe pass, at the widest declared viewport: the composed page's structure — landmarks,
+        // heading order, contrast — does not change with width, and running it per viewport triples
+        // the cost of the slowest check for the same answer.
+        await page.setViewportSize({ width: viewports[viewports.length - 1]?.width ?? 1280, height: 900 });
+        // Same freeze as the island lane: axe reads computed colour, and a region re-lays-out on a
+        // viewport change, so its lists start their entrance again right before this runs.
+        await page.addStyleTag({
+          content: '*,*::before,*::after{animation:none!important;transition:none!important}',
+        });
+        await sleep(200);
+        await page.addScriptTag({ content: axeSource });
+        violations = await page.evaluate(async () => {
+          const res = await window.axe.run(document.body, { resultTypes: ['violations'] });
+          return res.violations.map((v) => ({
+            id: v.id,
+            impact: v.impact,
+            help: v.help,
+            nodes: v.nodes.length,
+            target: v.nodes[0]?.target?.join(' ') ?? '',
+          }));
+        });
+      }
+      return { measurements: out, violations };
+    },
+  );
+}
+
+/**
+ * Picture the REGION — the composed page, not its parts.
+ *
+ * WHAT THIS CATCHES THAT AN ISLAND SHOT CANNOT: arrangement. The frame is not declared and therefore
+ * not checked, and this project has already shipped the consequence — two agents each extended the
+ * frame's slot lookup, the naive merge made one agent's widget render as the other's, and
+ * `archipelago verify --runtime` was BYTE-IDENTICAL between the correct and broken resolutions. Every
+ * island rendered correctly in isolation. Only the composition was wrong.
+ *
+ * THE REGION VIEW, deliberately, not the mountpoints view: the question is what a person sees, and the
+ * mountpoints view is a diagnostic layout that exists for probing wires.
+ *
+ * STATES COME FROM THE FLOWS. A region has no `scenarios` of its own, and one picture of one state
+ * would miss the case where the screen changes SHAPE — an actions page with an empty week is a
+ * different page, not a different value. Each flow's first step establishes a state someone thought
+ * worth driving, so that is the state list. A region whose flows do not seed a shape worth seeing has
+ * an evidence gap, and the fix is a flow, which is worth having anyway.
+ */
+export async function captureRegionLagoon({ id, port = 5199, states = [], viewports = [] }) {
+  const { chromium } = await import('playwright');
+  return onLagoonPage(
+    { target: `archipelago:${id}`, port, viewport: { width: viewports[0]?.width ?? 1280, height: 900 }, view: 'region' },
+    async (page) => {
+      await page.waitForFunction(() => !!window.__motuLagoon, null, { timeout: 15000 }).catch(() => {});
+      // Wait for the region, do not sleep at it — an app's real component tree takes far longer than a
+      // stand-in, and a picture of a half-mounted page is a baseline that flaps forever.
+      await page
+        .waitForFunction(() => document.querySelectorAll('[data-motu-slot]').length > 0, null, { timeout: 15000 })
+        .catch(() => {});
+
+      // Motion makes a baseline flap. Freeze it rather than sampling and hoping.
+      await page.addStyleTag({
+        content: '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}',
+      });
+
+      const shots = [];
+      const list = states.length ? states : [{ name: 'default', seed: {} }];
+      for (const state of list) {
+        // A fresh mount per state, for the reason the flow runner remounts: one seed can leave the
+        // region unrenderable, and every later picture would then be of the wreckage.
+        await page.evaluate(() => window.__motuLagoon?.remount?.()).catch(() => {});
+        await page
+          .waitForFunction(() => document.querySelectorAll('[data-motu-slot]').length > 0, null, { timeout: 10000 })
+          .catch(() => {});
+        await page.evaluate((seed) => {
+          const l = window.__motuLagoon;
+          if (l) for (const [k, v] of Object.entries(seed || {})) l.seed(k, v);
+        }, state.seed ?? {});
+        for (const vp of viewports) {
+          await page.setViewportSize({ width: vp.width, height: 900 });
+          await sleep(300);
+          const png = await page.screenshot({ animations: 'disabled', fullPage: true }).catch(() => null);
+          if (png) shots.push({ scenario: state.name ?? 'default', viewport: vp.name, width: vp.width, png });
+        }
+      }
+      return shots;
+    },
+  );
+}
+
+/**
+ * Render one island at each declared viewport and report what does not fit.
+ *
+ * The check nobody was running: motu knew `native | legacy` (footprint and skin) and nothing about
+ * WIDTH, so "does this work on a phone" was a human dragging a window. One mount, resized — a browser
+ * per width would triple the wall clock for the same answer.
+ *
+ * Horizontal overflow of the DOCUMENT is the signal, not of the island: a card that scrolls its own
+ * table on purpose is fine; a page the member has to pan sideways is the bug this catches.
+ */
+export async function responsiveLagoon({ tag, port = 5199, viewports = [], scenarios = [] }) {
+  return onLagoonPage(
+    { target: `island:${tag}`, port, viewport: { width: viewports[0]?.width ?? 1280, height: 900 } },
+    async (page) => {
+    // Poll for a PAINTED island, not just a mounted one: Vite's first-run dep re-optimization reloads
+    // the page, and an island that fetches its own data paints a frame later.
+    const deadline = Date.now() + paintTimeout;
+    while (Date.now() < deadline) {
+      const ready = await page
+        .evaluate((t) => {
+          const el = window.__motuFindIsland(t);
+          return !!el && window.__motuRendered(el).trim().length > 0;
+        }, tag)
+        .catch(() => false);
+      if (ready) break;
+      await sleep(250);
+    }
+    await sleep(250);
+
+    const results = [];
+    // Per SCENARIO, not just the default state: an island whose empty state is legitimately blank (a
+    // notice with nothing to say) would otherwise be measured empty at every width and reported as
+    // rendering nothing — a false alarm that teaches people to ignore the check.
+    const list = scenarios.length ? scenarios : [{ name: 'default', seed: {} }];
+    const owned = scenarioKeys(list);
+    for (const scenario of list) {
+    // NO REMOUNT, for the same reason the snapshot lane skips it: this one measures layout, and a
+    // fresh mount would have it measuring a tree that is still filling in.
+    await provideScenario(page, scenario.seed, { afterMount: scenario.afterMount, remount: false, owned });
+    for (const vp of viewports) {
+      await page.setViewportSize({ width: vp.width, height: 900 });
+      // Two beats: one for the resize to land, one for anything that re-measures on it.
+      await sleep(200);
+      const measured = await page.evaluate((t) => {
+        // A React-mounted island's wrapper is `display: contents` — no box of its own — so measuring it
+        // directly reports every island as blank. Fall back to what it rendered, the same way the seam
+        // lens does for its outlines.
+        const boxOf = (el) => {
+          if (!el) return null;
+          const own = el.getBoundingClientRect();
+          if (own.width || own.height) return own;
+          let l = Infinity, t2 = Infinity, r = -Infinity, b = -Infinity;
+          for (const child of el.children) {
+            const c = boxOf(child);
+            if (!c || (!c.width && !c.height)) continue;
+            l = Math.min(l, c.left); t2 = Math.min(t2, c.top);
+            r = Math.max(r, c.right); b = Math.max(b, c.bottom);
+          }
+          return l === Infinity ? null : { left: l, top: t2, right: r, bottom: b, width: r - l, height: b - t2 };
+        };
+        const doc = document.documentElement;
+        const island = window.__motuFindIsland(t);
+        // The island's own box, grown by whatever it portaled — a dialog-only island is not "blank".
+        let rect = boxOf(island);
+        for (const p of island ? window.__motuPortals(island) : []) {
+          const b = boxOf(p);
+          if (!b || (!b.width && !b.height)) continue;
+          if (!rect || (!rect.width && !rect.height)) { rect = b; continue; }
+          const l = Math.min(rect.left, b.left), t2 = Math.min(rect.top, b.top);
+          const r = Math.max(rect.right, b.right), bt = Math.max(rect.bottom, b.bottom);
+          rect = { left: l, top: t2, right: r, bottom: bt, width: r - l, height: bt - t2 };
+        }
+        return {
+          overflow: doc.scrollWidth - doc.clientWidth,
+          rendered: !!rect && rect.width > 0 && rect.height > 0,
+          height: rect ? Math.round(rect.height) : 0,
+        };
+      }, tag);
+      results.push({ ...vp, scenario: scenario.name ?? 'default', ...measured });
+    }
+    }
+    return results;
+    },
+  );
+}
+
+/**
+ * Boot a whole archipelago in the real-browser lagoon and report every island slot it mounted. Returns
+ * { ok, region, islands: [{ slot, tag, len }], diagnostics }. `ok` is true when the region rendered and
+ * every declared slot MOUNTED its island element. Emptiness of content is NOT a failure — an island may
+ * legitimately render nothing (e.g. filter chips with no active filter); a real mount throw is caught by
+ * the diagnostics (console/pageerror) instead.
+ */
+export async function runArchipelagoLagoon({ id, port = 5199 }) {
+  const { chromium } = await import('playwright');
+  const diagnostics = [];
+  return onLagoonPage({ target: `archipelago:${id}`, port, viewport: { width: 1200, height: 900 }, diagnostics }, async (page, server) => {
+
+    let result = { region: false, islands: [] };
+    const deadline = Date.now() + paintTimeout;
+    while (Date.now() < deadline) {
+      try {
+        result = await page.evaluate(() => {
+          const rendered = (el) => (el ? (el.shadowRoot ? el.shadowRoot.innerHTML : el.innerHTML) : '');
+          const arch = document.querySelector('motu-archipelago');
+          if (arch) {
+            const root = arch.shadowRoot || arch;
+            const islands = [...root.querySelectorAll('motu-island')].map((marker) => {
+              const child = [...marker.children].find((c) => c.tagName.includes('-'));
+              return {
+                slot: marker.getAttribute('slot'),
+                tag: child ? child.tagName.toLowerCase() : null,
+                len: rendered(child || marker).length,
+              };
+            });
+            return { region: true, islands };
+          }
+          // React mount path: no region element and no markers — islands render in the host's own
+          // tree, each behind a wrapper carrying its slot and tag.
+          if (window.__motuLagoon) {
+            const islands = [...document.querySelectorAll('[data-motu-island]')].map((el) => ({
+              slot: el.getAttribute('data-motu-slot'),
+              tag: el.getAttribute('data-motu-island'),
+              len: rendered(el).length,
+            }));
+            return { region: true, islands };
+          }
+          return { region: false, islands: [] };
+        });
+        // Ready once the region is up and every declared slot has mounted its island element.
+        if (result.region && result.islands.length > 0 && result.islands.every((i) => i.tag)) break;
+      } catch {
+        // HMR/full reload destroyed the context — re-poll on the fresh one.
+      }
+      await sleep(200);
+    }
+
+    const rejections = await page.evaluate(() => window.__motuRejections || []).catch(() => []);
+    for (const r of rejections) if (!NOISE.test(r)) diagnostics.push(r);
+    const fixtureCoverage = await readUnscopedRequests(page);
+    const networkEscapes = currentNetworkEscapes();
+
+    const ok = result.region && result.islands.length > 0 && result.islands.every((i) => i.tag);
+    return { ok, ...result, diagnostics, fixtureCoverage, networkEscapes };
+  });
+}
+
+/**
+ * Establish ONE scenario's seed in the running lagoon, then RE-MOUNT the island so that seed is an
+ * input rather than a late update.
+ *
+ * The re-mount is not optional, and this is the bug it closes. `provide()` writes the store, which
+ * drives anything BOUND to a prop and drives NOTHING in an island that fetches its own data through a
+ * stubbed host module — that island's effect already ran, against whatever the previous scenario left
+ * behind. The happy-dom lane mounts once per scenario, so the two runtimes disagreed on the same
+ * evidence: acme's club-feed passed `data-flow` under `--fast` with three distinct renders and failed
+ * in the browser with "3 scenarios rendered identically". A stub answering with `seededValue()` only
+ * becomes a per-scenario input if something makes the effect run again.
+ *
+ * The store survives the re-mount (it is module state, not tree state), so the fresh island reads the
+ * seed just provided.
+ *
+ * NOT for region flows: a flow's steps ACCUMULATE by design, and re-mounting between them would throw
+ * away the state the next step builds on.
+ *
+ * NOT for the lanes that MEASURE either. `captureLagoon` and `responsiveLagoon` keep their own inline
+ * provide and are deliberately NOT routed through here: re-mounting made `snapshot --all` fail with
+ * "Execution context was destroyed" (that lane re-aims ONE shared page per island, and the teardown
+ * races the re-aim) and perturbed which element the screenshot found. Whether those two have their own
+ * frozen-state problem is open — it needs the page-pool interaction understood first, and a snapshot
+ * lane that dies is worse than one that might be stale.
+ */
+/**
+ * Every key a scenario SET declares — what a reset between scenarios is allowed to forget.
+ *
+ * Scoped to these keys rather than the whole store, because a region's CHANNELS write their keys once,
+ * when they are installed, and nothing re-fires them. Clearing everything took those with it and left
+ * each later scenario looking at a region with no page behind it.
+ */
+function scenarioKeys(scenarios) {
+  const keys = new Set();
+  for (const s of scenarios ?? []) for (const k of Object.keys(scenarioInputs(s))) keys.add(k);
+  return [...keys];
+}
+
+async function provideScenario(page, seed, { settleMs = 150, tag, remount = true, owned = [], afterMount } = {}) {
+  await page.evaluate(({ s, later, remount, owned }) => {
+    const arch = document.querySelector('motu-archipelago');
+    // Either mount path exposes the same seams: the element on the custom-element path,
+    // window.__motuLagoon on the React one.
+    const on = arch && typeof arch.provide === 'function' ? arch : window.__motuLagoon;
+    const provide = on ? (k, v) => on.provide(k, v) : null;
+
+    // FORGET THE LAST SCENARIO FIRST, and this is the whole reason a scenario means anything.
+    //
+    // Seeds were applied to one long-lived store, in order, so they ACCUMULATED: a scenario that seeds
+    // `{}` provided nothing and rendered whatever its predecessor left behind, under its own name, in
+    // the data-flow comparison and in the visual baseline alike. A scenario is a STATE — it says what
+    // the region holds, and everything it does not mention it does not hold — so each one starts from
+    // the region's own seed and adds only its own keys. (Flows are the opposite and do not come
+    // through here: their steps build on each other by design.)
+    //
+    // ONLY THE KEYS THE SCENARIO SET OWNS. A region's channels write their keys once, at install, and
+    // nothing re-fires them — so forgetting the whole store leaves every later scenario measuring a
+    // region with no page behind it, which reads as an island "rendering nothing from default props"
+    // while the lagoon a human opens shows it rendering perfectly.
+    //
+    // Tolerated when absent: an older host bundle has no `reset`, and the lane should degrade to the
+    // previous behaviour rather than fail with a TypeError from inside a page evaluate.
+    on?.reset?.(owned);
+    // THE SCENARIO'S KEYS ARE ITS OWN: pinned before they are provided, so a source the reset just
+    // restarted cannot replace them when it answers (the React harness exposes `pin`).
+    // `afterMount` keys too: they arrive later, and a source answering in between must not take them.
+    window.__motuLagoon?.pin?.([...Object.keys(s || {}), ...Object.keys(later || {})]);
+    if (provide) for (const [k, v] of Object.entries(s || {})) provide(k, v);
+
+    if (!remount) return;
+    // The React path exposes a real teardown. The custom-element path has none, so re-insert the
+    // marker: disconnectedCallback disposes the child, connectedCallback mounts a fresh one.
+    if (typeof window.__motuLagoon?.remount === 'function') {
+      window.__motuLagoon.remount();
+    } else {
+      for (const el of document.querySelectorAll('motu-island')) {
+        const parent = el.parentNode;
+        const next = el.nextSibling;
+        parent?.removeChild(el);
+        parent?.insertBefore(el, next);
+      }
+    }
+  }, { s: seed ?? {}, later: afterMount ?? {}, remount, owned });
+  // A re-mount re-runs the island's fetch, so a lane that MEASURES (screenshot, viewport fit, axe)
+  // would otherwise sample a tree that is still filling in — a fixed sleep was enough when `provide`
+  // only updated props. Wait for the render to go quiet instead, and keep the fixed settle for callers
+  // that wait for stability themselves.
+  if (tag) await waitForStableRender(page, tag, { timeoutMs: 8000 });
+  else await sleep(settleMs);
+  // WHAT ARRIVES AFTER MOUNT (`Scenario.afterMount`): only once the island has mounted and settled, so
+  // the component sees it as news rather than as where it started. Then settle again — the render
+  // that counts is the one after the arrival.
+  if (afterMount && Object.keys(afterMount).length) {
+    await page.evaluate((later) => {
+      const arch = document.querySelector('motu-archipelago');
+      const on = arch && typeof arch.provide === 'function' ? arch : window.__motuLagoon;
+      if (on) for (const [k, v] of Object.entries(later)) on.provide(k, v);
+    }, afterMount);
+    if (tag) await waitForStableRender(page, tag, { timeoutMs: 8000 });
+    else await sleep(settleMs);
+  }
+}
+
+/** Interactive roles worth trying, most-specific first — a checkbox's accessible name and a button's
+ *  often collide (e.g. a labelled tile), so a narrower role tried first wins over a generic one. */
+const CLICKABLE_ROLES = ['checkbox', 'switch', 'radio', 'menuitem', 'tab', 'link', 'button'];
+
+/**
+ * Run a scenario's scripted interactions against the ALREADY-MOUNTED island — real Playwright
+ * locators, scoped to the island's own element (its custom-element tag, or its React-path wrapper),
+ * matched by ACCESSIBLE NAME rather than a CSS selector into the component's internals. See
+ * `Scenario.interactions`'s doc comment (`@motujs/runtime/mock`) for why this is a different claim
+ * than a region flow's `emit`, and therefore not the same "no synthetic clicks" rule.
+ *
+ * Playwright's locators pierce open shadow roots by default, so this works unchanged whether the
+ * island rendered under its own shadow root (`fit=native`, standalone) or light DOM (nested in an
+ * archipelago / the React mount path).
+ */
+async function runInteractions(page, tag, interactions) {
+  // NOT scoped to the island's own element. A dialog/popover/dropdown built on a portal (Radix,
+  // every shadcn component on it) renders as a SIBLING of the island in the DOM, not a descendant —
+  // scoping the search to the island's subtree made every interaction past the one that opens such a
+  // thing unfindable. `differentiateLagoon` mounts exactly one island alone, so page-wide search has
+  // no ambiguity to avoid here; it would need scoping again if this ever drives a multi-island region.
+  for (const step of interactions ?? []) {
+    if (!step.click) continue;
+    let target = null;
+    for (const role of CLICKABLE_ROLES) {
+      const candidate = page.getByRole(role, { name: step.click, exact: false });
+      if ((await candidate.count()) > 0) {
+        target = candidate.first();
+        break;
+      }
+    }
+    if (!target) target = page.getByText(step.click, { exact: false }).first();
+    await target.click({ timeout: 5000 });
+  }
+}
+
+/**
+ * Data-flow differentiation in the real-browser lagoon. Mounts the island once, then drives each
+ * declared scenario's seed into the store via the archipelago's `provide()` seam (the same inbound
+ * boundary the ocean uses) and captures the rendered output after each. Distinct inputs producing
+ * distinct output prove data flows criteria -> contract -> render, not merely that the wiring exists.
+ * Returns { differentiates, scenarioCount, mounted, diagnostics }.
+ */
+export async function differentiateLagoon({ tag, fit = 'native', port = 5199, scenarios = [] }) {
+  const { chromium } = await import('playwright');
+  const diagnostics = [];
+  return onLagoonPage({ target: `island:${tag}`, fit, port, viewport: { width: 900, height: 720 }, diagnostics }, async (page, server) => {
+
+    // Wait for the island to upgrade and paint — or to settle EMPTY. An island whose correct answer
+    // with no input is nothing (a card with no member, a list with no rows) never paints from its
+    // defaults, and waiting for paint used to end this check with `differentiates: null`, which the
+    // caller dropped without a word: the scenarios were never driven and nothing said so. Mounted is
+    // the element existing; an empty default is a state, not a failure, so its seeds are driven too.
+    let mounted = false;
+    let presentSince = null;
+    const deadline = Date.now() + paintTimeout;
+    while (Date.now() < deadline) {
+      try {
+        const r = await page.evaluate((t) => {
+          const el = window.__motuFindIsland(t);
+          return { mounted: !!el, len: window.__motuRendered(el).length };
+        }, tag);
+        if (r.mounted && r.len > 0) {
+          mounted = true;
+          break;
+        }
+        if (r.mounted) {
+          presentSince ??= Date.now();
+          if (Date.now() - presentSince >= EMPTY_DEFAULT_SETTLE_MS) {
+            mounted = true;
+            break;
+          }
+        } else {
+          presentSince = null;
+        }
+      } catch {
+        // context replaced by HMR — retry
+      }
+      await sleep(200);
+    }
+    if (!mounted) return { differentiates: null, scenarioCount: scenarios.length, mounted: false, diagnostics };
+
+    // Drive each scenario's seed through the archipelago boundary and capture rendered output.
+    const outputs = [];
+    const owned = scenarioKeys(scenarios);
+    // Scenarios whose interactions changed NOTHING observable — see `inertInteractions` below.
+    const inertInteractions = [];
+    const requestCount = () =>
+      page.evaluate(() => window.__motuFakeFetchRequestCount).catch(() => undefined);
+
+    // How many body-level nodes each scenario's render included from the island's own portals — so
+    // a pass that rests on a dialog says so, rather than reading like the island's own subtree.
+    const portals = [];
+    for (const [i, scenario] of scenarios.entries()) {
+      await provideScenario(page, scenario.seed, { afterMount: scenario.afterMount, owned });
+      if (!scenario.interactions?.length) {
+        outputs.push(normalizeRender(await waitForStableRender(page, tag, { timeoutMs: 8000 })));
+        portals.push(await portalCount(page, tag));
+        continue;
+      }
+
+      // AN INTERACTION MUST BE LOAD-BEARING, and "did the render change?" is the WRONG test for it.
+      //
+      // The properties interactions exist for are often exactly the ones where nothing visible moves:
+      // "the panel keeps its last-good data when a later refetch fails" asserts that the render is
+      // UNCHANGED. Comparing before/after alone would flag that scenario as decorative — the one case
+      // the primitive was added for. So an interaction counts as load-bearing if it moved the render
+      // OR caused work (a request through the lagoon's fake fetch). Only when it did neither is it a
+      // journey somebody clicked through whose end state a plain seed could have described.
+      const before = normalizeRender(await waitForStableRender(page, tag, { timeoutMs: 8000 }));
+      const requestsBefore = await requestCount();
+      await runInteractions(page, tag, scenario.interactions);
+      const after = normalizeRender(await waitForStableRender(page, tag, { timeoutMs: 8000 }));
+      const requestsAfter = await requestCount();
+
+      const renderMoved = before !== after;
+      const known = requestsBefore !== undefined && requestsAfter !== undefined;
+      const requestsMoved = known && requestsAfter > requestsBefore;
+      if (!renderMoved && !requestsMoved) {
+        inertInteractions.push({ name: scenario.name ?? `#${i + 1}`, requestsObservable: known });
+      }
+      outputs.push(after);
+      portals.push(await portalCount(page, tag));
+    }
+
+    const rejections = await page.evaluate(() => window.__motuRejections || []).catch(() => []);
+    for (const r of rejections) if (!NOISE.test(r)) diagnostics.push(r);
+    const fixtureCoverage = await readUnscopedRequests(page);
+    const networkEscapes = currentNetworkEscapes();
+
+    // TWO FAILURES, REPORTED AS ONE. `differentiates` folds "every scenario rendered" and "at least two
+    // differ" into a boolean, and the caller could only say "rendered identically" — which is a lie
+    // when the truth is that one scenario rendered NOTHING. That message sent someone looking for a
+    // bind gap when the actual answer was an empty state the island renders on purpose.
+    // A scenario may DECLARE that it renders nothing (`blank: 'why'`) — see lib/data-flow.mjs.
+    const judged = judgeRenders(outputs, scenarios);
+    return { ...judged, scenarioCount: scenarios.length, mounted: true, diagnostics, fixtureCoverage, inertInteractions, networkEscapes, portals };
+  });
+}
+
+/**
+ * Record contract calls in the real-browser lagoon. Starts capturing as early as the runtime exposes
+ * the recorder (before the island's mount self-fetch), drives each scenario's seed through the
+ * archipelago's `provide()` seam, and returns every captured call (request + response). With
+ * `transport: 'http'` this records the REAL backend; default (mock) records the mock's own responses
+ * (a self-consistency check of the pipeline). Returns { calls, mounted, diagnostics }.
+ */
+export async function recordLagoon({ tag, fit = 'native', port = 5199, scenarios = [], transport }) {
+  const { chromium } = await import('playwright');
+  const diagnostics = [];
+  return onLagoonPage({ target: `island:${tag}`, fit, port, transport, viewport: { width: 900, height: 720 }, diagnostics }, async (page, server) => {
+    // Turn on recording the instant the runtime module exposes the hook — before the island's mount
+    // self-fetch — so the default (first scenario) request is captured too. Also start the seed
+    // recorder (@motujs/core) to capture host-fed store writes (channels + provide()).
+    await page.addInitScript(() => {
+      const iv = setInterval(() => {
+        if (window.__motuRecorder) {
+          window.__motuRecorder.start();
+          if (window.__motuSeedRecorder) window.__motuSeedRecorder.start();
+          clearInterval(iv);
+        }
+      }, 0);
+    });
+
+    // Wait for the island to upgrade and paint (its mount fetch fires here).
+    let mounted = false;
+    const deadline = Date.now() + paintTimeout;
+    while (Date.now() < deadline) {
+      try {
+        const r = await page.evaluate((t) => {
+          const el = window.__motuFindIsland(t);
+          return { mounted: !!el, len: window.__motuRendered(el).length };
+        }, tag);
+        if (r.mounted && r.len > 0) {
+          mounted = true;
+          break;
+        }
+      } catch {
+        // context replaced by HMR — retry
+      }
+      await sleep(200);
+    }
+
+    // Drive each scenario so its request is issued and captured. To make it DETERMINISTIC (a scenario
+    // equal to the current store — e.g. the empty default — wouldn't re-fetch on its own), first set
+    // the scenario's keys to a unique sentinel, then to the real seed: the change always re-issues the
+    // request. Sentinel calls are filtered out below.
+    let reset = 0;
+    const provide = (seed) =>
+      page.evaluate((s) => {
+        const arch = document.querySelector('motu-archipelago');
+        if (arch && typeof arch.provide === 'function') {
+          for (const [k, v] of Object.entries(s || {})) arch.provide(k, v);
+        }
+      }, seed);
+    for (const scenario of scenarios) {
+      const seed = scenario.seed ?? {};
+      const sentinel = { __motuRecordReset: ++reset };
+      await provide(Object.fromEntries(Object.keys(seed).map((k) => [k, sentinel])));
+      await sleep(300);
+      await provide(seed);
+      await sleep(500);
+      if (scenario.afterMount) {
+        await provide(scenario.afterMount);
+        await sleep(500);
+      }
+    }
+    await sleep(200);
+
+    const raw = await page.evaluate(() => (window.__motuRecorder ? window.__motuRecorder.stop() : []));
+    // Drop the sentinel-priming calls; keep the real scenario requests.
+    const calls = (raw || []).filter((c) => !JSON.stringify(c.args).includes('__motuRecordReset'));
+    // Host-fed store writes (channel + provide) captured as lagoon seed; drop sentinel-primed values.
+    const rawSeed = await page.evaluate(() => (window.__motuSeedRecorder ? window.__motuSeedRecorder.stop() : []));
+    const seedWrites = (rawSeed || []).filter((w) => !JSON.stringify(w.value).includes('__motuRecordReset'));
+
+    const rejections = await page.evaluate(() => window.__motuRejections || []).catch(() => []);
+    for (const r of rejections) if (!NOISE.test(r)) diagnostics.push(r);
+    const fixtureCoverage = await readUnscopedRequests(page);
+    const networkEscapes = currentNetworkEscapes();
+
+    return { calls, seedWrites, mounted, diagnostics, fixtureCoverage, networkEscapes };
+  });
+}
+
+// Direct invocation: screenshot helper for a manual dry-run.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [, , tag, fit = 'native', screenshotPath] = process.argv;
+  runLagoon({ tag, fit, screenshotPath })
+    .then((r) => {
+      process.stdout.write(JSON.stringify(r) + '\n');
+      process.exit(r.ok ? 0 : 1);
+    })
+    .catch((err) => {
+      process.stderr.write(`playwright-lagoon: ${err?.stack || err}\n`);
+      process.exit(3);
+    });
+}
+
+/**
+ * DOES THE APPLICATION'S OWN PAGE RENDER, AND DOES IT REACH EVERY SLOT IT DECLARES?
+ *
+ * EXPERIMENTAL. This is the one question every other check here is structurally unable to ask.
+ * `integrate check` reads the host's SOURCE, so it can see `<X.Island slot="y">` and cannot see
+ * whether the branch containing it ever runs — a slot inside `{isOpen && …}`, a ternary or a `.map()`
+ * is reported as conditionally placed, and nothing proves the page REACHES it. The region view cannot
+ * close that either: it renders every declared slot unconditionally, by construction, because motu
+ * supplies the arrangement there. So a region could pass everything while the page that ships it
+ * crashes on load or never renders half of it.
+ *
+ * What it asks, and nothing more:
+ *
+ *   1. the page mounted without throwing            (a crash is marked, not a blank screen)
+ *   2. every declared slot is present in the DOM    (the page reached the branch that places it)
+ *   3. each of those slots rendered something       (the island mounted, not an empty wrapper)
+ *
+ * It does NOT assert content, drive interactions or replay flows — those are the region's flows, and
+ * duplicating them here would make the same claim twice against a slower page.
+ *
+ * SKIPS, LOUDLY, when the region declares no `page` override — `seen: 0` so the report renders it as
+ * a skip rather than a pass, because a check that looked at nothing has not passed.
+ */
+export async function pageRenderLagoon({ id, port = 5199 }) {
+  const diagnostics = [];
+  return onLagoonPage(
+    { target: `archipelago:${id}`, port, view: 'page', viewport: { width: 1200, height: 900 }, diagnostics },
+    async (page) => {
+      let result = { declared: false, crashed: null, slots: [] };
+      const deadline = Date.now() + paintTimeout;
+      while (Date.now() < deadline) {
+        try {
+          result = await page.evaluate(() => {
+            const absent = document.querySelector('[data-motu-page="absent"]');
+            const crashed = document.querySelector('[data-motu-page="crashed"]');
+            const slots = [...document.querySelectorAll('[data-motu-island]')].map((el) => ({
+              slot: el.getAttribute('data-motu-slot'),
+              tag: el.getAttribute('data-motu-island'),
+              len: (el.innerHTML || '').length,
+            }));
+            return {
+              declared: !absent,
+              crashed: crashed ? (crashed.textContent || '').slice(0, 1200) : null,
+              slots,
+            };
+          });
+          // Settled once the page either failed visibly or put something in every slot it reached.
+          if (!result.declared || result.crashed || (result.slots.length > 0 && result.slots.every((s) => s.len > 0)))
+            break;
+        } catch {
+          // HMR or a full reload tore the context down — re-poll on the fresh one.
+        }
+        await sleep(200);
+      }
+
+      const rejections = await page.evaluate(() => window.__motuRejections || []).catch(() => []);
+      for (const r of rejections) if (!NOISE.test(r)) diagnostics.push(r);
+      return { ...result, diagnostics };
+    },
+  );
+}
+
+/**
+ * Open every declared SCREEN, and replay the screen flows.
+ *
+ * A screen is the application's own layout with a region per slot, and the calls that matter most
+ * come from that layout — Peps' dashboard reads feature grants and two badge counts on every screen,
+ * none of which a region's own flows ever make. So each screen is opened alone, in a fresh page, and
+ * every call it causes is collected; and a screen may declare FLOWS (`src/screens/screens.evidence.ts`)
+ * that click the app's own links, `navigate` to a path, and assert what renders afterwards.
+ *
+ * A fresh page per screen and per flow, not one re-aimed page: a screen's layout stays mounted across
+ * navigation by design, so a re-aimed page would credit one screen's calls to the next.
+ */
+export async function runScreens({ port, screens = [], flows = [] }) {
+  const server = await startLagoon({ target: '', port });
+  const browser = await getBrowser();
+  const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+  const base = `http://localhost:${server.port}/`;
+  const addr = (q) => `${base}?${new URLSearchParams({ ...q, dockInset: 'off', autoPrimary: 'off' })}`;
+  const open = async (page, url) => {
+    await page.goto(url, { waitUntil: 'load' });
+    await page.waitForFunction(() => window.__motuLagoonState !== undefined, null, { timeout: 20000 }).catch(() => {});
+    await sleep(1200);
+  };
+  const calls = (page, after = 0) =>
+    page.evaluate((s) => (window.__motuLagoonControl?.calls?.() ?? []).filter((c) => c.seq > s), after).catch(() => []);
+  const state = (page) => page.evaluate(() => window.__motuLagoonState ?? null).catch(() => null);
+  const failing = (list) => list.filter((c) => !c.ok && !c.declared);
+
+  const opened = [];
+  const ran = [];
+  try {
+    for (const id of screens) {
+      const page = await context.newPage();
+      try {
+        await open(page, addr({ screen: id }));
+        const st = await state(page);
+        const landed = await calls(page);
+        opened.push({ screen: id, ok: !!st?.ok, error: st?.ok ? null : (st?.error ?? 'the screen never reported a state'), calls: landed.length, undeclared: failing(landed) });
+      } finally {
+        await page.close().catch(() => {});
+      }
+    }
+
+    for (const flow of flows) {
+      const page = await context.newPage();
+      try {
+        await open(page, addr({ screen: flow.screen, ...(flow.world ? { world: flow.world } : {}) }));
+        let mark = 0;
+        for (const [index, step] of (flow.steps ?? []).entries()) {
+          const result = await page.evaluate(async (st) => {
+            const ctl = window.__motuLagoonControl;
+            if (st.click) {
+              const name = String(st.click).trim();
+              const CLICKABLE = 'button, [role="button"], a[href], [role="menuitem"], [role="tab"], [role="link"], label, summary';
+              const nameOf = (el) =>
+                `${el.getAttribute('aria-label') ?? el.getAttribute('title') ?? ''} ${el.innerText ?? el.textContent ?? ''}`.replace(/\s+/g, ' ').trim();
+              const candidates = [...document.querySelectorAll(CLICKABLE)].filter((el) => el.getClientRects().length > 0);
+              const el =
+                candidates.find((c) => nameOf(c) === name) ??
+                candidates.filter((c) => nameOf(c).includes(name)).sort((a, b) => nameOf(a).length - nameOf(b).length)[0];
+              if (!el) {
+                const available = [...new Set(candidates.map(nameOf).filter(Boolean))].slice(0, 12);
+                return { error: `nothing clickable is named "${name}" — clickable here: ${available.map((n) => `"${n}"`).join(', ') || '(nothing)'}` };
+              }
+              el.click();
+            } else if (st.navigate) {
+              if (typeof ctl?.openPath !== 'function') return { error: 'this lagoon cannot open a path (no openPath on its control)' };
+              ctl.openPath(String(st.navigate));
+            } else if (!st.expectScreen && !Object.keys(st.expectRender ?? {}).length) {
+              return { error: 'a screen step must `click`, `navigate`, or assert with `expectScreen` / `expectRender`' };
+            }
+            if (!st.expectScreen && !Object.keys(st.expectRender ?? {}).length) {
+              return { error: 'a screen step must assert something — `expectScreen` or `expectRender`' };
+            }
+            const text = (el) => (el?.innerText ?? '').replace(/\s+/g, ' ').trim();
+            const mismatches = () => {
+              const out = [];
+              const onScreen = new URL(location.href).searchParams.get('screen');
+              if (st.expectScreen && onScreen !== st.expectScreen) out.push({ key: 'screen', expected: st.expectScreen, actual: onScreen });
+              for (const [slot, want] of Object.entries(st.expectRender ?? {})) {
+                const els = [...document.querySelectorAll(`[data-motu-slot="${slot}"]`)];
+                const seen = els.map(text).join(' | ');
+                if (!els.length) out.push({ key: `render:${slot}`, expected: `slot "${slot}" on screen`, actual: 'no such slot is mounted' });
+                else if (!seen.includes(String(want))) out.push({ key: `render:${slot}`, expected: `text containing ${JSON.stringify(want)}`, actual: seen.slice(0, 300) });
+              }
+              return out;
+            };
+            const until = Date.now() + 3000;
+            let m = mismatches();
+            while (m.length && Date.now() < until) {
+              await new Promise((r) => setTimeout(r, 80));
+              m = mismatches();
+            }
+            return { mismatches: m };
+          }, step);
+          await sleep(150);
+          const landed = await calls(page, mark);
+          mark = landed.reduce((n, c) => Math.max(n, c.seq), mark);
+          ran.push({
+            flow: flow.name ?? 'screen flow',
+            screen: flow.screen,
+            step: index + 1,
+            ok: !result.error && !(result.mismatches ?? []).length,
+            error: result.error ?? null,
+            mismatches: result.mismatches ?? [],
+            calls: landed.length,
+            undeclared: failing(landed),
+          });
+        }
+      } finally {
+        await page.close().catch(() => {});
+      }
+    }
+  } finally {
+    await context.close().catch(() => {});
+  }
+  return { screens: opened, flows: ran };
+}