@motujs/cli 0.0.0-stage → 0.1.0

package/src/lib/evidence-json.mjs

@@ -0,0 +1,74 @@
+// The scenario/flow crossing between node processes, and the two things JSON cannot carry.
+//
+// `readScenarios` spawns the harness under tsx, which prints the evidence as JSON, and parses it
+// back. That hop is invisible and was lossy in two different ways:
+//
+//   A DATE came back as an ISO STRING, so an island that formats one threw on mount and rendered
+//   nothing — which `data-flow` then reported as "scenarios rendered NOTHING" and `responsive` as
+//   "renders nothing", neither naming a date. The lagoon a human opens BUNDLES the same evidence,
+//   keeps the Date and renders perfectly, so the two disagreed and only the check lane was wrong.
+//   Found in a project whose whole domain is meetings: every scenario carrying a séance was blank.
+//
+//   A SET, MAP OR FUNCTION came back as `{}` — genuinely untransportable, and `seed-transport`
+//   exists to say so. But by the time that check ran it was looking at the `{}`, not at the Set, so
+//   it could only ever catch one that survived a DIFFERENT loader. The value is marked here, where
+//   the real object still exists, and the check reads the marker.
+//
+// Marker objects, not bare strings, in both cases: `"2026-08-19"` is indistinguishable from a string
+// somebody meant to be a string, and `{}` is indistinguishable from an empty object.
+
+const DATE = '__motuDate';
+const LOST = '__motuLost';
+
+/** What a value is, when JSON cannot carry it. Null for everything JSON handles. */
+function lostKind(v) {
+  if (v instanceof Set) return 'Set';
+  if (v instanceof Map) return 'Map';
+  if (typeof v === 'function') return 'function';
+  return null;
+}
+
+/**
+ * A `JSON.stringify` replacer that marks what the crossing would otherwise destroy.
+ *
+ * MUST be a plain function: `JSON.stringify` calls `Date.prototype.toJSON()` BEFORE handing the value
+ * to a replacer, so for a Date `value` is already a string and only `this[key]` is still the Date.
+ * A Set/Map has no `toJSON`, and a function is dropped entirely unless the replacer returns something
+ * in its place — so those three are read from `value` as usual.
+ */
+export function markEvidence(key, value) {
+  const raw = this?.[key];
+  if (raw instanceof Date) return { [DATE]: raw.toISOString() };
+  const lost = lostKind(value);
+  return lost ? { [LOST]: lost } : value;
+}
+
+/**
+ * The other half. Dates are rebuilt; a LOST marker is left standing on purpose — it is the evidence
+ * `seed-transport` reports, and handing the island a plausible `{}` instead is what made that
+ * failure arrive as three misleading findings somewhere else.
+ */
+export function reviveEvidence(_key, value) {
+  return value && typeof value === 'object' && typeof value[DATE] === 'string'
+    ? new Date(value[DATE])
+    : value;
+}
+
+/** The kind a marked-lost value used to be, or null. */
+export function lostMarker(v) {
+  return v && typeof v === 'object' && typeof v[LOST] === 'string' ? v[LOST] : null;
+}
+
+/** Evidence out. */
+export function stringifyEvidence(value) {
+  return JSON.stringify(value, markEvidence);
+}
+
+/** Evidence in. Returns undefined on malformed input, so callers keep their existing fallbacks. */
+export function parseEvidence(text) {
+  try {
+    return JSON.parse(text, reviveEvidence);
+  } catch {
+    return undefined;
+  }
+}

package/src/lib/expect-calls.mjs

@@ -0,0 +1,53 @@
+// `expectCalls` on a flow step: the backend calls that step is allowed to make — and only those.
+//
+// WHY: the call ledger already recorded every ask (`flow-calls` fails one nothing ANSWERED), but no
+// flow could say what a state should ask for. So a change that made a state ask for MORE went unseen
+// as long as the extra call was answered: bench/evidence's blind mistake B9 dropped "only fetch the
+// remote servers when the store starts empty", every harness default-answered `/servers.json`, and the
+// only trace was "1 answered" in the lagoon's calls strip where there had been nothing.
+//
+//   { expectRender: { list: 'Main shlink' }, expectCalls: [] }                 // asks for nothing
+//   { emit: …, expectCalls: ['GET /servers.json'] }                              // exactly this
+//
+// An entry names a call as `METHOD /path` (query ignored), as `/path` (any method), or by its
+// declaration's label (`shots.list`, `table:shots(select)`). Compared as SETS of distinct calls: how
+// many times a call repeated is a render detail (StrictMode doubles effects) and not the claim. Every
+// call the step made must be named, and every name must have been called.
+
+/** A recorded call, as the lagoon's ledger hands it over. */
+const pathOf = (url) => String(url ?? '').split('?')[0];
+
+/** Does this declared entry name this call? */
+export function namesCall(entry, call) {
+  const e = String(entry).trim();
+  const m = e.match(/^([A-Z]+)\s+(\/\S*)$/);
+  if (m) return call.method?.toUpperCase() === m[1] && pathOf(call.url) === m[2];
+  if (e.startsWith('/')) return pathOf(call.url) === e;
+  return call.label === e;
+}
+
+/** A call as a person reads it, for messages. */
+export const describeCall = (c) => `${c.method} ${pathOf(c.url)}${c.label && c.label !== pathOf(c.url) ? ` (${c.label})` : ''}`;
+
+/**
+ * The mismatches between what a step declared and what it called, in the shape flow mismatches take
+ * (`{ key, expected, actual }`), or `[]` when it holds. `undefined` declares nothing — no check.
+ */
+export function expectCallsMismatches(expected, calls) {
+  if (expected === undefined) return [];
+  const list = Array.isArray(expected) ? expected : [expected];
+  const unnamed = [...new Map(calls.filter((c) => !list.some((e) => namesCall(e, c))).map((c) => [describeCall(c), c])).keys()];
+  const missing = list.filter((e) => !calls.some((c) => namesCall(e, c)));
+  const out = [];
+  if (unnamed.length) {
+    out.push({
+      key: 'calls',
+      expected: list.length ? `only ${list.map((e) => JSON.stringify(e)).join(', ')}` : 'no backend call',
+      actual: `also called ${unnamed.join(', ')}`,
+    });
+  }
+  if (missing.length) {
+    out.push({ key: 'calls', expected: `a call to ${missing.map((e) => JSON.stringify(e)).join(', ')}`, actual: 'never called' });
+  }
+  return out;
+}

package/src/lib/flow-calls.mjs

@@ -0,0 +1,53 @@
+// `flow-calls`: a flow step (or a screen) that made a backend call NOTHING declared fails.
+//
+// WHY. On 2026-11-11 Peps' screens made four calls nothing answered — `member_feature_grants`,
+// `notifications`, `ticket_replies`, `business_services`. The app swallowed each error and rendered a
+// plausible page, every check passed, and only the dock's call signals showed them: a signal is
+// something an agent never reads. So a call that no fixture, table or route answered is now a
+// finding, attributed to the step that caused it.
+//
+// A DECLARED failure is not one: a fixture's `status: 500` is the state "a failing search" working,
+// and the live feed marks it `declared` (core's `LiveCall`).
+
+/** What to declare so this call is answered — in the declaration's own spelling. */
+export function callFix(call) {
+  const label = String(call.label ?? '');
+  if (!call.status) return `the call never got an answer${call.error ? ` (${String(call.error).slice(0, 120)})` : ''}`;
+  let m;
+  if ((m = /^table:([^(]+)/.exec(label))) return `declare the table \`${m[1]}\` in the wire's tables, or a fixture for it`;
+  if ((m = /^rpc:(.+)$/.exec(label))) return `declare a fixture for the rpc \`${m[1]}\``;
+  if ((m = /^fn:(.+)$/.exec(label))) return `declare a fixture for the edge function \`${m[1]}\``;
+  if ((m = /^route:(\S+) (.+)$/.exec(label))) return `declare a fixture for ${m[1]} ${m[2]} (an appRoutes route)`;
+  if ((m = /^([\w$]+)\.([\w$]+)$/.exec(label))) return `declare a fixture for ${m[1]}/${m[2]}`;
+  return `declare an answer for ${label || call.url}`;
+}
+
+/** One line per undeclared call: what was asked, what came back, and what to declare. */
+export function describeCall(call) {
+  const answer = call.status ? `${call.status}${call.error ? ` ${String(call.error).replace(/\s+/g, ' ').slice(0, 90)}` : ''}` : 'no answer';
+  return `${call.method} ${call.label || call.url} → ${answer} (by ${call.owner}) — ${callFix(call)}`;
+}
+
+/**
+ * Report the calls a run's steps made that nothing declared.
+ *
+ * `steps` carry `{ where, undeclared, calls }`. Same call made twice in one step is said once with a
+ * count: a refetch loop is one finding, not a wall.
+ */
+export function reportFlowCalls(report, steps, what = 'flow step(s)') {
+  let total = 0;
+  let bad = 0;
+  for (const s of steps) {
+    total += s.calls ?? 0;
+    const seen = new Map();
+    for (const c of s.undeclared ?? []) {
+      const k = `${c.method} ${c.label || c.url} ${c.status}`;
+      seen.set(k, { call: c, n: (seen.get(k)?.n ?? 0) + 1 });
+    }
+    for (const { call, n } of seen.values()) {
+      bad++;
+      report.error('flow-calls', `${s.where}: ${describeCall(call)}${n > 1 ? ` (×${n})` : ''}`);
+    }
+  }
+  if (!bad) report.ok('flow-calls', `every call the ${what} made was answered by a declaration`, { n: total, of: 'call(s)' });
+}

package/src/lib/framework.mjs

@@ -0,0 +1,98 @@
+// WHERE THE FRAMEWORK IS, and therefore HOW it is reached: a checkout, or an install.
+//
+// motu grew up run FROM ITS OWN CHECKOUT: the CLI found vite and the build plugins in the checkout's
+// devDependencies, aliased `@motujs/*` straight to `packages/*/src/*.ts`, symlinked them into each
+// project's node_modules on every run, and read its skills and adapters from `.github/` and
+// `packages/adapters/` beside it. Every one of those is a path that does not exist once the CLI is
+// `npm i -D @motujs/cli` in somebody's app — there is no `packages/`, no `.github/`, and the code
+// that looked for them fell back to the PROJECT root, so the lagoon aliased `@motujs/react` to
+// `<app>/packages/react/src/index.ts` and died on a file the adopter had never heard of.
+//
+// Two modes, chosen by what is on disk, never by a flag a person has to remember:
+//
+//   checkout   the CLI sits at `<checkout>/packages/cli`, beside `packages/core/src/index.ts`
+//              (or `$MOTU_ROOT` names a checkout). Everything stays exactly as it was: source
+//              aliases, no-install links, build tools from the checkout root.
+//   installed  anything else — in practice `node_modules/@motujs/cli`. The `@motujs/*` packages
+//              resolve the ordinary way, from the app's node_modules to their compiled `dist/`;
+//              build tools resolve from THIS package's own dependencies; and the few files that
+//              live outside `packages/cli` in a checkout ship inside it, under `bundled/`.
+//
+// This module imports nothing of the CLI's, so `config.mjs` (which everything else imports) can.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** `packages/cli` in a checkout, `node_modules/@motujs/cli` in an install. */
+export const CLI_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+const OWN_CHECKOUT = resolve(CLI_PACKAGE_ROOT, '../..');
+const isCheckout = (dir) => existsSync(resolve(dir, 'packages/core/src/index.ts'));
+
+/**
+ * The motu checkout this CLI runs from, or null when it was installed.
+ *
+ * `$MOTU_ROOT` still wins, as it always has — it is how a CI image points an installed binary at a
+ * checkout on purpose, and an override that only worked from inside a checkout would not be one.
+ */
+export const CHECKOUT_ROOT = process.env.MOTU_ROOT
+  ? resolve(process.env.MOTU_ROOT)
+  : isCheckout(OWN_CHECKOUT)
+    ? OWN_CHECKOUT
+    : null;
+
+/**
+ * Where vite, the build plugins and Tailwind are resolved from FIRST.
+ *
+ * The checkout root when this CLI is the checkout's own (they are the root's devDependencies there),
+ * otherwise this package — where an install puts them, as `@motujs/cli`'s own dependencies. Keyed on
+ * the CLI's real location rather than on `$MOTU_ROOT`: that variable says where the framework SOURCE
+ * is, and an installed CLI pointed at a checkout still has its build tools where npm put them.
+ */
+export const BUILD_DEPS_ROOT = isCheckout(OWN_CHECKOUT) ? OWN_CHECKOUT : CLI_PACKAGE_ROOT;
+
+/** 'checkout' | 'installed' — see the top of this file. */
+export const FRAMEWORK_MODE = CHECKOUT_ROOT ? 'checkout' : 'installed';
+export const INSTALLED = FRAMEWORK_MODE === 'installed';
+
+/**
+ * The CLI's own version — the range `motu init` writes for every `@motujs/*` it records.
+ *
+ * Lockstep (scripts/release.mjs sets one version on every package), so the CLI's version IS the
+ * version of the set. `^` of it rather than an exact pin: a patch release of one package must not
+ * need the adopter to edit five lines of package.json.
+ */
+export const CLI_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(resolve(CLI_PACKAGE_ROOT, 'package.json'), 'utf8')).version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+})();
+
+/**
+ * A framework file that lives OUTSIDE `packages/cli` in a checkout, wherever it actually is.
+ *
+ * `checkoutRel` is its path in the checkout (`.github/agents`, `packages/adapters/next/vite.mjs`).
+ * Installed, the same file ships inside this package under `bundled/` — copied there by
+ * `scripts/build-packages.mjs`, with `.github/` spelled `github/` because a dot-directory in a
+ * tarball is one more thing a packer is entitled to drop.
+ *
+ * A checkout reads the ORIGINAL, never the bundled copy: `bundled/` is a build output, and reading it
+ * there would make every edit to a skill or an adapter invisible until somebody re-ran the build.
+ */
+export function frameworkFile(checkoutRel) {
+  if (CHECKOUT_ROOT) return resolve(CHECKOUT_ROOT, checkoutRel);
+  return resolve(CLI_PACKAGE_ROOT, 'bundled', checkoutRel.replace(/^\.github\//, 'github/'));
+}
+
+/**
+ * How to install the browser the runtime checks drive.
+ *
+ * "(in packages/cli)" is right in a checkout — that is where playwright is installed, and `npx` must
+ * find THAT copy so the browser revision matches — and a path that does not exist for an adopter who
+ * installed from npm, where the app's own `npx playwright` is the CLI's copy already.
+ */
+export const CHROMIUM_INSTALL = INSTALLED
+  ? '`npx playwright install chromium`'
+  : '`npx playwright install chromium` (in packages/cli)';

package/src/lib/host-rules.mjs

@@ -0,0 +1,55 @@
+// The rules a HOST's coding agent has to follow for motu to keep its guarantees.
+//
+// They used to live nowhere: every adopting repo re-typed them into its own CLAUDE.md from memory, or
+// (more often) did not, and the framework enforced a shape nobody had told the agent about. They ship
+// with motu now, from one source, and land in the host's instruction files — the same reasoning as
+// `motu skills install`, which already refuses to let the judgement half drift from the CLI half.
+//
+// Written between markers and rewritten in place, so a `motu init` on an existing repo updates the
+// block instead of appending a second copy, and anything the project added around it survives.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { frameworkFile } from './framework.mjs';
+
+/**
+ * The checkout's `.github/host-rules.md`, or the copy shipped inside @motujs/cli when installed —
+ * `<cli>/../../.github` from node_modules is nowhere, and `hostRulesText()` returning null makes
+ * `motu init` skip the rules SILENTLY (see lib/framework.mjs).
+ */
+const SOURCE = frameworkFile('.github/host-rules.md');
+
+const BEGIN = '<!-- motu:rules -->';
+const END = '<!-- /motu:rules -->';
+
+/** The instruction files a coding agent reads, in the order motu writes them. */
+const TARGETS = ['CLAUDE.md', 'AGENTS.md', '.github/copilot-instructions.md'];
+
+/** The shipped rules text, or null when this checkout has none (an older motu). */
+export function hostRulesText() {
+  return existsSync(SOURCE) ? readFileSync(SOURCE, 'utf8').trim() : null;
+}
+
+/**
+ * Write the rules into every instruction file the repo already has (and CLAUDE.md if it has none).
+ *
+ * Returns the paths written, relative to `dir`. Idempotent: a repo that already carries the block gets
+ * it replaced, so upgrading motu upgrades the rules.
+ */
+export function applyHostRules(dir) {
+  const text = hostRulesText();
+  if (!text) return [];
+  const block = `${BEGIN}\n${text}\n${END}`;
+  const existing = TARGETS.filter((t) => existsSync(resolve(dir, t)));
+  const written = [];
+  for (const target of existing.length ? existing : ['CLAUDE.md']) {
+    const path = resolve(dir, target);
+    const before = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const next = before.includes(BEGIN)
+      ? before.replace(new RegExp(`${BEGIN}[\\s\\S]*?${END}`), block)
+      : `${before.trimEnd()}${before.trim() ? '\n\n' : ''}${block}\n`;
+    if (next === before) continue;
+    writeFileSync(path, next);
+    written.push(target);
+  }
+  return written;
+}

package/src/lib/host-sources.mjs

@@ -0,0 +1,121 @@
+// WHERE THE HOST KEEPS ITS CODE — asked once, for every check that needs the answer.
+//
+// Two checks walk the host application: `removal-check` (delete motu, does it still compile?) and
+// `integrate check` (does the page compose, place and read the region?). Both used to hardcode
+// `['app', 'components', 'lib', 'src', 'pages']` — Next's layout, and the only host motu had ever been
+// integrated into. Pointed at Twenty, whose source is all under `src/`, that found nothing and printed
+// "no motu references in the host application" over a fully integrated app. A green result from an
+// empty search is the worst failure mode either tool has.
+//
+// THE APPLICATION ALREADY DECLARED THIS, and it is not a guess: `tsconfig.json` says which files the
+// project compiles, via `include`/`exclude` and its `extends` chain. `removal-check` was already
+// trusting it for the half that decides the verdict — it runs `tsc --noEmit -p tsconfig.json` — while
+// its file walk used the five-directory guess, so ONE CHECK CARRIED TWO DEFINITIONS of "the
+// application" and they were free to disagree. Measured on this repo's own Next host, the guess misses
+// `middleware.ts` and everything under `test/`: files `tsc` compiles and the surgery never unwraps,
+// which is how a dangling import lands on a line that looks fine.
+//
+// Precedence, widest trust last:
+//
+//   1. `hostSources` in motu.config.json  — an explicit answer for a layout neither of the below gets
+//                                           right. Still supported; it just stopped being the only way.
+//   2. the host's tsconfig/jsconfig       — the application's own declaration.
+//   3. the five-directory guess           — a host with no tsconfig at all (a JS host, or the review
+//                                           console, which has none).
+//
+// It returns FILES, not roots, because that is what a tsconfig knows: reducing its file set back to
+// top-level directories would throw away the `exclude` that made it precise. Callers apply their own
+// skip rule (motu's own source, for one; the directories motu writes into, for the other) and the
+// ORIGIN travels with the answer so a report can say what it trusted.
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { ts } from 'ts-morph';
+
+/** Source files, as both walks have always defined them: `.ts`/`.tsx`, no `node_modules`, no dotdirs. */
+const isSource = (p) => /\.tsx?$/.test(p);
+
+/** A path is out if any segment is `node_modules` or starts with a dot — `.next/types` is generated. */
+function inHiddenOrVendored(rel) {
+  return rel.split(sep).some((seg) => seg === 'node_modules' || (seg.startsWith('.') && seg !== '.' && seg !== '..'));
+}
+
+/** The recursive walk both checks used, kept for the config and guess paths. */
+function walkRoots(hostRoot, roots) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = resolve(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+        walk(full);
+      } else if (isSource(e.name)) {
+        out.push(full);
+      }
+    }
+  };
+  for (const top of roots) walk(resolve(hostRoot, top));
+  return out;
+}
+
+/**
+ * The file list the host's own TypeScript config declares, or `null` when there is no config to read.
+ *
+ * `getParsedCommandLineOfConfigFile` is the API that follows `extends` — `parseJsonConfigFileContent`
+ * alone does not, and a host whose `include` lives in a base config would silently resolve to nothing.
+ * A config that parses but matches no file returns `null` too, so the caller falls through to the
+ * guess rather than inheriting an empty answer: that is the original bug, arriving by a new door.
+ */
+function fromTsconfig(hostRoot) {
+  const file = ['tsconfig.json', 'jsconfig.json'].map((n) => resolve(hostRoot, n)).find((p) => existsSync(p));
+  if (!file) return null;
+  let parsed;
+  try {
+    parsed = ts.getParsedCommandLineOfConfigFile(file, {}, { ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => {} });
+  } catch {
+    return null;
+  }
+  if (!parsed?.fileNames?.length) return null;
+  const files = parsed.fileNames
+    .map((p) => resolve(p))
+    .filter((p) => isSource(p) && p.startsWith(hostRoot + sep) && !inHiddenOrVendored(p.slice(hostRoot.length + 1)));
+  return files.length ? { files, origin: 'tsconfig', detail: file } : null;
+}
+
+/**
+ * Every host source file, and where the answer came from.
+ *
+ * `{ files, origin, detail }` — `origin` is `'config' | 'tsconfig' | 'guess'`, and `detail` names the
+ * tsconfig or the roots, so a check that examined nothing can say what it trusted before it found
+ * nothing. Callers still have to treat an empty result as "could not run": nothing here decides that.
+ */
+export function hostSourceFiles(hostRoot, cfg) {
+  const configured = Array.isArray(cfg?.hostSources) ? cfg.hostSources : null;
+  if (configured?.length) {
+    return { files: walkRoots(hostRoot, configured), origin: 'config', detail: configured.join(', ') };
+  }
+
+  const declared = fromTsconfig(hostRoot);
+  if (declared) return declared;
+
+  const guessed = ['app', 'components', 'lib', 'src', 'pages'].filter((d) => existsSync(resolve(hostRoot, d)));
+  const roots = guessed.length ? guessed : ['.'];
+  return { files: walkRoots(hostRoot, roots), origin: 'guess', detail: roots.join(', ') };
+}
+
+/**
+ * How to say, in a report, where the scan looked — because "scanned 0 files" alone cannot be acted on.
+ *
+ * `rel` is the caller's path shortener (`paths.rel`), kept out of here so this module stays free of
+ * the CLI's own config object.
+ */
+export function describeSources({ origin, detail }, rel = (p) => p) {
+  if (origin === 'tsconfig') return `declared by ${rel(detail)}`;
+  if (origin === 'config') return `hostSources: ${detail}`;
+  return detail === '.' ? 'guessed: the whole host root' : `guessed: ${detail}`;
+}

package/src/lib/island-placement.mjs

@@ -0,0 +1,64 @@
+// WHICH SLOTS A PIECE OF HOST SOURCE PLACES — one answer, for the two checks that ask.
+//
+// `integrate check` reads placements from the host's files with ts-morph; `island-composition` in
+// `verify` asked the SAME question with `matchAll(/<[A-Z][A-Za-z0-9]*\.Island\s[^>]*?slot=…/)`. Two
+// implementations of one question drift by construction: the regex could not see a multi-line
+// element, a slot written with a template literal, or the difference between `slot="x"` and
+// `slot={x}` — and it counted matches inside comments, which is how a commented-out example became a
+// declared slot elsewhere in this file.
+//
+// The RULE is the interesting part and it belongs in one place: a STRING LITERAL names a slot
+// statically, and anything else — `slot={expr}` — is a placement motu cannot attribute. Saying so
+// beats guessing, and both callers now say the same thing.
+import { Project, SyntaxKind } from 'ts-morph';
+
+/** A fresh in-memory project per call: these are one-shot reads, and a shared cache would go stale. */
+function parse(code, name = 'host.tsx') {
+  const project = new Project({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true });
+  return project.createSourceFile(name, code);
+}
+
+/**
+ * The slot each `<X.Island slot="…">` in this source names.
+ *
+ * Returns `{ named, computed }` — `named` is the statically readable slots, `computed` counts the
+ * placements whose slot is an expression, which a caller may want to report rather than ignore.
+ * `tags` filters to the region's own island components when given; omit it to take every `*.Island`.
+ */
+export function placementsIn(code, tags = null) {
+  const named = new Set();
+  let computed = 0;
+  let sf;
+  try {
+    sf = parse(code);
+  } catch {
+    // A syntax this project's own build accepts and ts-morph does not: read nothing rather than
+    // guess. The caller reports "could not be read", which is the honest outcome.
+    return { named, computed, parsed: false };
+  }
+  const elements = [
+    ...sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
+    ...sf.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+  ];
+  for (const el of elements) {
+    const tag = el.getTagNameNode().getText();
+    if (tags ? !tags.includes(tag) : !/^[A-Z][A-Za-z0-9]*\.Island$/.test(tag)) continue;
+    const init = el.getAttribute?.('slot')?.getInitializer?.();
+    if (init?.getKind?.() === SyntaxKind.StringLiteral) named.add(init.getLiteralText());
+    else if (init) computed++;
+  }
+  return { named, computed, parsed: true };
+}
+
+/**
+ * The slot an element's `slot` attribute names: the string, `null` for a computed one, `undefined`
+ * where there is no attribute at all.
+ *
+ * Three answers rather than two, because the caller treats them differently: a computed slot is
+ * REPORTED (motu cannot attribute it), and a missing one is simply not a placement.
+ */
+export function slotNameOfElement(init, attr) {
+  if (init?.getKind?.() === SyntaxKind.StringLiteral) return init.getLiteralText();
+  if (init?.getKind?.() === SyntaxKind.JsxExpression) return null;
+  return attr ? null : undefined;
+}

package/src/lib/island-render.mjs

@@ -0,0 +1,105 @@
+/**
+ * WHAT AN ISLAND RENDERED — its own subtree, plus what its own mount PORTALED out of it.
+ *
+ * Every check that compares or measures an island's render read the island root's innerHTML. A
+ * dialog, sheet, popover or drawer built on a React portal (Radix Dialog, vaul Drawer — every shadcn
+ * overlay) renders as a child of `document.body`, not of the island, so an island whose whole visible
+ * output is such a dialog was reported as "rendered NOTHING" by `data-flow` — while the region flow
+ * asserting that very dialog's text passed, because `expectRender` searches the whole document. Two
+ * checks of one framework disagreeing about what is on the screen.
+ *
+ * The fix is NOT a document-wide snapshot. That would count the lagoon's own chrome (dock, toolbar,
+ * call toasts, the debug overlay), anything that existed before the island mounted, and any other
+ * mount's output as this island's — and a genuinely empty island would then pass on the strength of
+ * the furniture around it. Output is counted only when it is ATTRIBUTABLE to this island:
+ *
+ *   - a direct child of `document.body` (where portals land by default),
+ *   - that is not the island, nor an ancestor of it, nor lagoon chrome (`data-motu-chrome`),
+ *   - whose React fiber — or, for a library that creates its own portal container, the first
+ *     descendant's fiber — walks UP (`fiber.return`, which crosses a portal back to the component
+ *     that opened it) to a fiber that lives INSIDE the island: its wrapper element, a host element
+ *     in its subtree, or the root container of a React root mounted inside it.
+ *
+ * That ancestry is what makes it attributable rather than temporal: a node that existed before the
+ * mount, a node the chrome drew in vanilla DOM, and a portal opened by a DIFFERENT island (or a
+ * previous mount of this one, whose wrapper element is not this one) all fail the walk. React's
+ * internal `__reactFiber$` key is the only coupling to React internals; it has been stable since 17.
+ *
+ * This function is INSTALLED, not imported: Playwright serialises it into the page with
+ * `addInitScript`, and the happy-dom harness and the tests call it on their own window. So it must
+ * not close over anything — every helper lives inside it.
+ */
+export function installIslandRender(win) {
+  const w = win || window;
+  const doc = w.document;
+
+  // A composed walk: through shadow roots to their hosts, so an island rendered inside a
+  // `<motu-archipelago>` shadow (or a React root inside a custom element's shadow) is still "inside".
+  const within = (outer, node) => {
+    for (let n = node; n; n = n.parentNode || n.host) if (n === outer) return true;
+    return false;
+  };
+
+  const fiberKey = (node) => {
+    for (const k of Object.keys(node)) if (k.startsWith('__reactFiber$')) return k;
+    return null;
+  };
+
+  const fiberOf = (node) => {
+    const k = fiberKey(node);
+    if (k) return node[k];
+    // A library that creates its own container (`document.createElement('div')` + `createPortal`
+    // into it) leaves the container fiber-less; its first rendered descendant carries the fiber.
+    const walker = doc.createTreeWalker(node, 1 /* SHOW_ELEMENT */);
+    for (let i = 0, n = walker.nextNode(); n && i < 200; i++, n = walker.nextNode()) {
+      const nk = fiberKey(n);
+      if (nk) return n[nk];
+    }
+    return null;
+  };
+
+  const ownedBy = (node, island) => {
+    for (let f = fiberOf(node), hops = 0; f && hops < 5000; f = f.return, hops++) {
+      const s = f.stateNode;
+      if (!s) continue;
+      // A host element (div, span, the island's own `data-motu-island` wrapper) inside the island.
+      if (s.nodeType === 1 && within(island, s)) return true;
+      // A HostRoot (tag 3): a React root whose container is inside the island — the custom-element
+      // path mounts one root per island, in the island's own shadow/light DOM.
+      if (f.tag === 3 && s.containerInfo && within(island, s.containerInfo)) return true;
+    }
+    return false;
+  };
+
+  const SKIP = /^(SCRIPT|STYLE|LINK|TEMPLATE|NOSCRIPT|META)$/;
+
+  /** The body-level nodes this island's own mount portaled out of itself, in document order. */
+  const portals = (island) => {
+    if (!island || !doc.body) return [];
+    const out = [];
+    for (const n of doc.body.children) {
+      if (SKIP.test(n.tagName)) continue;
+      if (n === island || within(n, island)) continue; // the island itself, or what contains it
+      // Lagoon chrome marks itself. Its nodes are vanilla DOM and would fail the fiber walk anyway;
+      // the mark makes the exclusion a declared rule rather than an accident of how chrome is drawn.
+      if (n.hasAttribute('data-motu-chrome') || n.querySelector('[data-motu-chrome]')) continue;
+      if (ownedBy(n, island)) out.push(n);
+    }
+    return out;
+  };
+
+  const own = (el) => (el ? (el.shadowRoot ? el.shadowRoot.innerHTML : el.innerHTML) : '');
+
+  /**
+   * `{ own, portals }` — the island's own HTML and the outerHTML of each node it portaled. The HTML
+   * comparison string (`__motuRendered`) is the two joined, so a check that compares renders compares
+   * what a person sees, and an island with no own DOM and no portal still reads as ''.
+   */
+  w.__motuRenderedParts = (el) => ({ own: own(el), portals: portals(el).map((n) => n.outerHTML) });
+  w.__motuRendered = (el) => {
+    const p = w.__motuRenderedParts(el);
+    return p.own + p.portals.map((h) => '\n<!--motu:portal-->' + h).join('');
+  };
+  /** The portaled ELEMENTS — for checks that measure (axe context, layout boxes) rather than compare. */
+  w.__motuPortals = portals;
+}