@motujs/cli 0.0.0-stage → 0.1.1

package/src/lib/scaffold.mjs

@@ -0,0 +1,606 @@
+// Scaffold templates for `motu init`. These exist so a fresh project gets a WORKING loop, not just
+// a layout: `motu island verify` boots the lagoon root through Vite, so a project without one has
+// static checks and no loop at all — which is the half of motu that matters.
+//
+// Templates are plain strings with {{placeholders}} (not JS template literals) so the generated TS —
+// which is full of backticks and ${} of its own — passes through untouched.
+
+/** Substitute {{key}} placeholders. An unknown placeholder is left alone (so it shows up in review). */
+export function render(tpl, vars) {
+  // TO A FIXPOINT, because a var's VALUE may itself be a template: `envShim` expands to
+  // `import '{{envImport}}';`, and `String.replace` never re-scans what it inserted. One pass left
+  // that placeholder verbatim in the generated entry files — valid TypeScript, unresolvable module.
+  let out = tpl;
+  for (let pass = 0; pass < 5; pass++) {
+    const next = out.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in vars ? String(vars[k]) : m));
+    if (next === out) return out;
+    out = next;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Project root files (the layout declaration + the registries islands slot into)
+// ---------------------------------------------------------------------------------------------
+
+export const ISLANDS_REGISTRY = `// GENERATED by \`motu sync\` from the islands on disk — do not edit by hand. \`motu island create\`
+// adds one import + one row here; the framework turns this into custom-element registrations.
+import type { ElementSpec } from '@motujs/react';
+
+export const ELEMENT_REGISTRY: ElementSpec[] = [];
+`;
+
+export const ARCHIPELAGOS_REGISTRY = `// Registry of the project's archipelagos by id, so a composition root (or the lagoon / CLI) can
+// resolve one by name. \`motu archipelago init\` adds one import + one row here.
+import type { ArchipelagoConfig } from '@motujs/core';
+
+export const ARCHIPELAGOS: Record<string, ArchipelagoConfig> = {};
+
+/** Resolve an archipelago config by id (undefined if unknown). */
+export function getArchipelago(id: string): ArchipelagoConfig | undefined {
+  return ARCHIPELAGOS[id];
+}
+`;
+
+export const BARREL = `// Public surface of the project: the element registry and the archipelago configs + resolver.
+// Composition roots (and the motu lagoon / CLI harness) import everything they need from here.
+//
+// NO \`.js\` ON THESE SPECIFIERS. Turbopack has no \`extensionAlias\`, so \`./islands/registry.js\` is
+// simply an unresolved module and \`next build\` stops on this file. motu's own packages had their
+// \`.js\` specifiers dropped for exactly this reason — \`moduleResolution: "Bundler"\` makes the
+// extension optional, which fixes every bundler instead of one mapping per host — and the fix did
+// not reach the files motu GENERATES. It does now.
+export { ELEMENT_REGISTRY } from './islands/registry';
+export { ARCHIPELAGOS, getArchipelago } from './archipelagos/registry';
+`;
+
+/** The app package manifest — the lagoon imports the project by NAME, so the name must resolve. */
+export const APP_PACKAGE_JSON = `{
+  "name": "{{appPackage}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles.css": "./src/shared/styles.css"
+  },
+{{motuDependencies}}  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  }
+}
+`;
+
+/** The one shared island stylesheet. `motu archipelago verify` lints this, so it ships dual-mode. */
+export const SHARED_STYLES = `/* Styles for every motu island. In shadow isolation this sheet is adopted into the shadow root; in
+   light isolation it is injected once globally and the island root carries a \`.motu-root\` marker.
+   That is why every host-scoped rule targets \`:where(:host, .motu-root)\` — a bare \`:host\` is inert
+   in light DOM. One sheet, both modes.
+
+   Colours come from --x-* tokens (host-overridable) with --_* locals holding the fallback, so a host
+   can reskin islands without either side reopening isolation.
+
+   THE LOCALS ARE ALSO DECLARED ON :root, AND THAT IS NOT BELT-AND-BRACES.
+   \`.motu-root\` is added by packages/core/src/island.ts when an island mounts AS A CUSTOM ELEMENT.
+   Two very common surfaces never do that: a React host that renders the component directly inside its
+   region's wrap form, and the lagoon's own view. On both, the whole block below is inert and every
+   --_* resolves to nothing — which silently drops border, background and every colour while leaving
+   padding and font working, so it renders a plausible, WRONG screen that no check can see. It was
+   found by opening the page, which is the only thing that finds it.
+
+   A project styling its islands with Tailwind never notices, because it never asks these locals for
+   anything. One that uses this sheet as written hits it on its first island.
+
+   Splitting the rule is what makes it safe: the LOCALS go global — they are only fallback
+   definitions, and any :host / .motu-root still overrides them — while the presentational rules stay
+   scoped, because \`display: block\` and a font on :root would restyle the whole document. */
+:root,
+:where(:host, .motu-root) {
+  --_text: var(--x-color-text, inherit);
+  --_muted: var(--x-color-muted, #6b7280);
+  --_border: var(--x-border, #e5e7eb);
+  --_radius: var(--x-radius, 6px);
+  --_surface: var(--x-color-surface, #ffffff);
+}
+
+/* SCOPED, unlike the locals above: these would restyle the document from :root. */
+:where(:host, .motu-root) {
+  display: block;
+  color: var(--_text);
+  font-family: var(--x-font, inherit);
+}
+`;
+
+/** Build output + local installs. `.motu/` holds published lagoon artifacts, which are rebuilt on
+ *  demand and can be large; the lagoon's node_modules is its own build toolchain. */
+export const GITIGNORE = `node_modules/
+dist/
+.motu/
+`;
+
+// ---------------------------------------------------------------------------------------------
+// Lagoon root — the part `motu island verify` actually boots
+// ---------------------------------------------------------------------------------------------
+
+/** The lagoon's OWN dependencies only.
+ *
+ *  Deliberately does not list @motujs/* or the app package: vite.config resolves those by path (they
+ *  are unpublished, raw-TS sources), so declaring them here would just be an install that fails.
+ *  React is also absent on purpose — it resolves upward to the host application's copy, and a second
+ *  React installed here would give the host two of them and break hooks the moment an island renders
+ *  a component from the host's own library. */
+export const LAGOON_PACKAGE_JSON = `{
+  "name": "{{appPackage}}-lagoon",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "focus": "vite --open /lagoon.html",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.3",
+    "vite": "^5.4.10"{{lagoonExtraDevDeps}}
+  }
+}
+`;
+
+/**
+ * WHAT A PAGE SAYS WHEN ITS OWN BUNDLE NEVER RAN.
+ *
+ * motu already refuses loudly when a state NAME resolves to nothing: banner, console error, and
+ * `__motuLagoonState.ok: false`, because being handed a page you did not ask for is the failure worth
+ * engineering against. A module-eval crash had none of that. `startLagoon` never runs, so nothing is
+ * left to report it, and the page is WHITE — indistinguishable from a region that renders nothing.
+ *
+ * That cost an afternoon on a real project: a circular import made one archipelago evaluate after the
+ * composition root that used it, the whole single-chunk lagoon died on the ReferenceError, and every
+ * region went blank. Auth, the proxy and the host were all suspected first, because a blank page
+ * accuses nothing. The console had the answer the entire time.
+ *
+ * A CLASSIC SCRIPT IN THE HEAD, before the module. Module scripts are deferred, so this is installed
+ * and listening before the first line of the bundle is evaluated — which is the only way to catch a
+ * crash that happens during evaluation.
+ *
+ * IT ONLY SPEAKS WHEN THE LAGOON NEVER BOOTED. `__motuLagoonStates` is published by `startLagoon`, so
+ * its absence AFTER load is exactly "the bundle did not finish". An error with the catalogue present
+ * is an ordinary runtime error in somebody's component, which is theirs to see in the console and not
+ * something to paint over the page.
+ */
+export const LAGOON_BOOT_GUARD = `<script>
+(function () {
+  var first = null;
+  var note = function (e) { if (first === null && e) first = e; };
+  addEventListener('error', function (e) { note(e.error || e.message); }, true);
+  addEventListener('unhandledrejection', function (e) { note(e.reason); });
+  function verdict() {
+    if (window.__motuLagoonStates || first === null) return;
+    var text = (first && (first.stack || first.message)) || String(first);
+    var line = String(text).split('\\n')[0];
+    window.__motuLagoonState = { ok: false, kind: 'boot', target: 'lagoon', error: line };
+    console.error('motu: the lagoon bundle did not boot - nothing on this page is the application.\\n' + text);
+    var el = document.createElement('div');
+    el.setAttribute('data-motu-boot-error', '');
+    el.style.cssText = 'position:fixed;left:0;right:0;top:0;z-index:2147483647;padding:12px 16px;' +
+      'background:#7f1d1d;color:#fff;font:500 13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;' +
+      'box-shadow:0 2px 12px rgba(0,0,0,.35);white-space:pre-wrap';
+    el.textContent = 'motu: this lagoon did not boot - ' + line +
+      '\\nNothing below is the application. The whole bundle is one module graph, so one module ' +
+      'throwing takes every region with it.';
+    (document.body || document.documentElement).appendChild(el);
+  }
+  addEventListener('load', function () { setTimeout(verdict, 250); });
+})();
+</script>`;
+
+export const LAGOON_INDEX_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>motu lagoon — {{appPackage}}</title>
+${LAGOON_BOOT_GUARD}
+    <style>
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        background: #f6f4f0;
+        color: #22302c;
+        font-family: ui-sans-serif, system-ui, "Segoe UI", Roboto, sans-serif;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="lagoon-root"></div>
+    <script type="module" src="{{galleryEntrySrc}}"></script>
+  </body>
+</html>
+`;
+
+export const LAGOON_FOCUS_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>motu lagoon — single target (isolated)</title>
+${LAGOON_BOOT_GUARD}
+    <style>
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        background: #f6f4f0;
+        color: #22302c;
+        font-family: ui-sans-serif, system-ui, "Segoe UI", Roboto, sans-serif;
+      }
+      #lagoon { max-width: 1440px; margin: 22px auto; padding: 0 20px; }
+    </style>
+  </head>
+  <body>
+    <div id="lagoon"></div>
+    <script type="module" src="{{focusEntrySrc}}"></script>
+  </body>
+</html>
+`;
+
+/**
+ * A `process.env` for the browser, installed before any application module is evaluated.
+ *
+ * Host modules read process.env at IMPORT time — a Supabase client that throws when its keys are
+ * missing takes the whole lagoon down before anything renders, with an error ("process is not
+ * defined") that says nothing about why. Vite's `define` does not reach files served from outside the
+ * lagoon root, which is exactly where the host application's modules live, so the values are installed
+ * at runtime instead. ES modules evaluate in import order, so importing this first is enough.
+ */
+export const ENV_SHIM = `// Installs process.env before any host module reads it. MUST be imported first — see below.
+import config from '{{lagoonConfigImport}}';
+
+const g = globalThis as unknown as { process?: { env: Record<string, string> } };
+g.process = g.process ?? { env: {} };
+// Declared under "env" in lagoon.config.json. The lagoon has no backend, so these only have to EXIST;
+// never put a real secret here — a published lagoon is a static page anyone with the link can read.
+// \`env\` is OPTIONAL in lagoon.config.json and the scaffolded one does not declare it — so with
+// resolveJsonModule TypeScript infers the literal shape and \`config.env\` is a compile error on a
+// freshly generated project. Read it through a widening cast: the key may or may not be there.
+const declared = (config as { env?: Record<string, string> }).env ?? {};
+Object.assign(g.process.env, { NODE_ENV: 'development', ...declared });
+`;
+
+/** Fixture aggregation by glob, so adding an island needs no edit here (the demo app's hand-maintained
+ *  fixtures.ts drifts by construction — its own header admits the manual step). */
+export const LAGOON_FIXTURES = `// Every island's lagoon EVIDENCE, gathered by glob so adding an island is not also an edit here.
+// A \`fixtures.mock.ts\` that exports \`fixtures\` / \`roles\` is picked up automatically.
+//
+// The same modules carry the project's declared STATES, which used to be dropped here: this file read
+// \`fixtures\` and \`roles\` off each evidence module and ignored \`scenarios\`, so every state the project
+// had written down existed in the node-side checks and nowhere a browser could reach. Passing them to
+// the entry is what makes \`?scenario=\` / \`?flow=\` an address (see @motujs/react's lagoon-states).
+import type { Fixture, RegionScenario, Scenario } from '@motujs/runtime/mock';
+
+type FixtureModule = { fixtures?: Fixture[]; roles?: string[]; scenarios?: Scenario[] };
+
+const modules = import.meta.glob<FixtureModule>({{fixturesGlob}}, { eager: true });
+
+export const ALL_FIXTURES: Fixture[] = Object.values(modules).flatMap((m) => m.fixtures ?? []);
+
+export const ALL_ROLES: string[] = [...new Set(Object.values(modules).flatMap((m) => m.roles ?? []))];
+
+const EVIDENCE_SUFFIX = '.evidence.ts';
+
+/** \`…/week-actions.evidence.ts\` -> \`week-actions\`; \`…/week-actions/fixtures.mock.ts\` -> \`week-actions\`.
+ *  Derived from the PATH rather than declared: both evidence layouts are named after the island, and a
+ *  second declaration of which island a file belongs to is a second thing that can be wrong. */
+function ownerOf(path: string): string {
+  const parts = path.split('/');
+  const file = parts[parts.length - 1] ?? '';
+  return file.endsWith(EVIDENCE_SUFFIX) ? file.slice(0, -EVIDENCE_SUFFIX.length) : (parts[parts.length - 2] ?? '');
+}
+
+/** Island scenarios by element tag — the states \`?scenario=\` addresses. */
+export const ALL_SCENARIOS: Record<string, Scenario[]> = Object.fromEntries(
+  Object.entries(modules)
+    .map(([path, m]) => ['{{tagPrefix}}' + ownerOf(path), m.scenarios ?? []] as const)
+    .filter(([, list]) => list.length),
+);
+
+// A REGION's evidence, which is NOT in the fixtures glob above and must not be: its \`fixtures\` would
+// join the mock transport's corpus and change what every existing check replays. Only the flows are
+// read from it.
+const regions = import.meta.glob<{ scenarios?: RegionScenario[] }>({{flowsGlob}}, { eager: true });
+
+/** Region flows by archipelago id — the states \`?flow=\` addresses. */
+export const ALL_FLOWS: Record<string, RegionScenario[]> = Object.fromEntries(
+  Object.entries(regions)
+    .map(([path, m]) => [ownerOf(path), m.scenarios ?? []] as const)
+    .filter(([, list]) => list.length),
+);
+`;
+
+/** The focused entry — this is what `motu island verify` drives via MOTU_TARGET. */
+export const LAGOON_FOCUS_ENTRY = `{{envShim}}// Thin lagoon entry: reads the vite-injected target/fit and hands the generic lagoon harness
+// (@motujs/react -> bootstrapLagoon) the project's element registry, fixtures and archipelago resolver.
+// All harness logic is framework-side; this file only supplies app-specific inputs.
+import { bootstrapLagoon } from '@motujs/react';
+import { setDefaultIsolation } from '@motujs/core';
+import { ELEMENT_REGISTRY, ARCHIPELAGOS, getArchipelago } from '{{appPackage}}';
+import css from '{{appPackage}}/styles.css?inline';
+import { ALL_FIXTURES, ALL_ROLES, ALL_SCENARIOS, ALL_FLOWS } from '{{fixturesImport}}';
+import config from '{{lagoonConfigImport}}';
+// The SAME overrides the gallery entry uses. Without them the focused lagoon — the one
+// \`motu island verify\` drives — ran with no region seed, so the checks asserted against defaults
+// while the gallery showed seeded state.
+import * as overrides from '{{overridesImport}}';
+{{hostImport}}{{hostGlobalCss}}
+// Injected by vite.config from the MOTU_* env (see vite.config.ts).
+declare const __MOTU_TARGET__: string; // "island:{{tagPrefix}}some-tag" | "archipelago:some-id"
+declare const __MOTU_FIT__: string; //    "native" | "legacy"
+declare const __MOTU_FORCE_ERROR__: string; // "" | "500" | "403" — verify's error-resilience mount
+declare const __MOTU_ISOLATION__: 'shadow' | 'light';
+declare const __MOTU_LEGACY_FIT__: boolean;
+
+// Set BEFORE bootstrapLagoon so single-target verify exercises the project's real isolation posture.
+setDefaultIsolation(__MOTU_ISOLATION__);
+
+// The target can come from the URL (\`?target=island:x-thing\`), from the build (\`MOTU_TARGET\`), or
+// from nowhere at all. The URL wins because it is what lets ONE dev server answer for every island:
+// the checks navigate instead of booting a server each. Opening lagoon.html by hand passes neither,
+// so fall back to the project's first archipelago rather than to a name the framework guessed.
+const params = typeof location !== 'undefined' ? new URLSearchParams(location.search) : new URLSearchParams();
+const targetFromUrl = params.get('target');
+const target =
+  targetFromUrl ||
+  (typeof __MOTU_TARGET__ === 'string' && __MOTU_TARGET__) ||
+  (Object.keys(ARCHIPELAGOS)[0] ? 'archipelago:' + Object.keys(ARCHIPELAGOS)[0] : '');
+
+bootstrapLagoon({
+  elements: ELEMENT_REGISTRY,
+  css,
+  fixtures: ALL_FIXTURES,
+  roles: ALL_ROLES,
+  resolveArchipelago: getArchipelago,
+  // The project's declared states, so this entry can be opened ON one (\`?scenario=\` / \`?flow=\`).
+  evidence: { scenarios: ALL_SCENARIOS, flows: ALL_FLOWS },
+  // Region seeds/channels, resolved from the target — including an \`island:\` target, whose seed
+  // belongs to the region that declares it.
+  overrides,
+  archipelagos: ARCHIPELAGOS,
+  // motu's chrome wears this application's colours. Shared with the gallery through
+  // lagoon.config.json so the two entries cannot disagree — override it right here when you want a
+  // value the JSON should not carry, e.g. a deliberately darker shade of the brand:
+  //   chrome: { ...config.chrome, primary: 'color-mix(in srgb, hsl(var(--primary)) 70%, #000)' },
+  chrome: config.chrome,
+  // Must match how the host application mounts islands, or this verifies a path you do not ship.
+  mount: config.mount,
+{{hostOption}}  target,
+  fit: params.get('fit') || (typeof __MOTU_FIT__ === 'string' ? __MOTU_FIT__ : ''),
+  // From the URL, like the target: the wiring/flow checks ask for 'mountpoints' so every declared
+  // slot mounts regardless of where the page's own arrangement would put it.
+  view: params.get('view') === 'mountpoints' ? 'mountpoints' : undefined,
+  // Also from the URL, and for the same reason as the target: the error-resilience check wants ONE
+  // island mounted against a failing transport, not a second dev server that differs by an env var.
+  forceErrorStatus: (() => {
+    const forced = params.get('forceError') || (typeof __MOTU_FORCE_ERROR__ === 'string' ? __MOTU_FORCE_ERROR__ : '');
+    return forced ? Number(forced) : undefined;
+  })(),
+});
+`;
+
+/** `lagoon.config.json` — the project's lagoon, declared. Behaviour lives in @motujs/react. */
+export const LAGOON_CONFIG = `{
+  "about": "The {{appPackage}} lagoon: this project's islands rendered against fixtures, with no backend, no session and no host application around them.",
+  "transport": "mock",
+  "defaultTheme": "motu",
+{{lagoonMount}}{{lagoonChrome}}  "stations": {}
+}
+`;
+
+/** For a host with shadcn-style tokens, point motu's chrome at the app's own primary by REFERENCE —
+ *  no value copied here, so a rebrand in the app moves the tooling with it. */
+export const LAGOON_CHROME_SHADCN = `  "chrome": {
+    "primary": "hsl(var(--primary))",
+    "onPrimary": "hsl(var(--primary-foreground))"
+  },
+`;
+
+/** `src/lagoon.ts` — the escape hatch, empty by default. */
+export const LAGOON_OVERRIDES = `// Lagoon overrides: what a JSON declaration cannot hold.
+//
+// Everything the lagoon DOES lives in @motujs/react (\`startLagoon\`), and everything it can be TOLD is in
+// ../lagoon.config.json. This file is for the rest — functions and objects — and staying empty is the
+// normal case. Each export below is optional; delete what you do not use.
+import type { LagoonOverrides } from '@motujs/react';
+
+// A host bridge for outward intents. The default logs them, which is usually what you want here:
+// seeing "[host] navigate /x" in the console is the proof that an island emitted an intent instead of
+// navigating by itself.
+// export const host: LagoonOverrides['host'] = { navigate: (p) => {}, action: (n, d) => {} };
+
+// Everything about one region, in ONE entry: its seed, its arrangement, its inbound channels, the
+// providers its islands cannot render without, and the props the page passes on an island element.
+// Keep each region's own seed and frame in a module beside it and reference them here, so adding a
+// region touches this file on one line.
+// export const regions: LagoonOverrides['regions'] = {
+//   someArchipelago: { seed: { criteria: {} }, layout: (island) => <SomePageFrame island={island} /> },
+// };
+
+// The same fields may also be given kind-first, keyed by archipelago id — the older shape, still
+// honoured. Where both name a field for one region, \`regions\` wins.
+// export const seed: LagoonOverrides['seed'] = { someArchipelago: { criteria: {} } };
+
+// Runs before anything mounts — e.g. standing up a fake host for a foreign-framework island.
+// export const setup: LagoonOverrides['setup'] = () => {};
+
+export {};
+`;
+
+/** The gallery shim. Deliberately tiny and stable: it is wiring Vite requires in the app, nothing more. */
+export const LAGOON_GALLERY_ENTRY = `{{envShim}}// The lagoon gallery entry.
+//
+// There is no logic here on purpose. The gallery — tide line, seam lens, archipelago switching, the
+// recorded callsite frames — lives in @motujs/react (\`startLagoon\`), so improvements to it arrive with
+// the framework instead of needing this file regenerated. Declare the lagoon in ../lagoon.config.json;
+// override behaviour in ./lagoon.ts.
+//
+// What stays here is only what Vite requires in the app: the build-time defines, \`import.meta.glob\`,
+// the project's own registry, and the debug overlay — which @motujs/react must not depend on, so the app
+// hands it in.
+import { startLagoon } from '@motujs/react';
+import { mountDebugOverlay, toggleDebugOverlay, isDebugOverlayOpen, subscribeDebugOverlay, mountFindings, currentFindings, currentSheet, currentSeams, currentIslands, currentCoupling, currentCoverage, watchSeams, toggleRecording, recordingState, setPicking, setCoupling, couplingOn, onIslandPicked } from '@motujs/debug-overlay';
+import { ELEMENT_REGISTRY, ARCHIPELAGOS } from '{{appPackage}}';
+import css from '{{appPackage}}/styles.css?inline';
+import { ALL_FIXTURES, ALL_ROLES, ALL_SCENARIOS, ALL_FLOWS } from '{{fixturesImport}}';
+import config from '{{lagoonConfigImport}}';
+import * as overrides from '{{overridesImport}}';
+{{hostImport}}{{hostGlobalCss}}
+declare const __MOTU_ISOLATION__: 'shadow' | 'light';
+declare const __MOTU_LEGACY_FIT__: boolean;
+declare const __MOTU_TRANSPORT__: string;
+// "archipelago:<id>" when the artifact was built for one region; '' for the whole gallery.
+declare const __MOTU_TARGET__: string;
+// Present in the lagoon by default (this is the sandbox); MOTU_DEBUG=0 strips the lens entirely.
+declare const __MOTU_DEBUG__: boolean;
+
+startLagoon({
+  elements: ELEMENT_REGISTRY,
+  archipelagos: ARCHIPELAGOS,
+  fixtures: ALL_FIXTURES,
+  roles: ALL_ROLES,
+  css,
+  config,
+  overrides,
+  isolation: __MOTU_ISOLATION__,
+  // Whether this host HAS a legacy skin — the fit chip is a choice with one option without it.
+  legacyFit: __MOTU_LEGACY_FIT__,
+  transport: __MOTU_TRANSPORT__,
+  target: __MOTU_TARGET__,
+  debug: __MOTU_DEBUG__,
+  // Must match the host application (and the focused entry), or the lagoon shows a mount path the
+  // project does not ship.
+  mount: config.mount,
+  lens: {
+    mount: mountDebugOverlay,
+    toggle: toggleDebugOverlay,
+    isOpen: isDebugOverlayOpen,
+    subscribe: subscribeDebugOverlay,
+  mountFindings,
+  findings: currentFindings,
+  sheet: currentSheet,
+  seams: currentSeams,
+  islands: currentIslands,
+  coupling: currentCoupling,
+  coverage: currentCoverage,
+  toggleRecording,
+  recordingState,
+  setPicking,
+  // What the crosshair chose, so the dock can scope the lagoon to it.
+  onPicked: onIslandPicked,
+  setCoupling,
+  couplingOn,
+  watch: watchSeams,
+  },
+  // Callsite frame stylesheets (\`roots/lagoon/src/frames/*.css\`). The glob has to be written here:
+  // Vite resolves it statically, at this file's location.
+  // BOTH, and the scenarios are not optional here. This is the entry \`lagoon serve\` and
+  // \`lagoon publish\` build, so an address it cannot resolve is an address that works nowhere a human
+  // looks — which is what \`?target=island:…&scenario=…\` was until this line carried scenarios too.
+  evidence: { scenarios: ALL_SCENARIOS, flows: ALL_FLOWS },
+  frames: import.meta.glob('{{framesGlob}}', { query: '?inline', import: 'default', eager: true }),
+});
+`;
+
+/** The lagoon's Tailwind config: the host's, re-anchored so it works from a different directory. */
+export const NEXT_TAILWIND_CONFIG = `// The lagoon's Tailwind setup — the HOST's config, with one thing changed.
+//
+// Tailwind resolves \`content\` globs against the current working directory, and here that is the lagoon
+// rather than the app. The host's own './components/**' globs would therefore match nothing, Tailwind
+// would emit no utilities at all, and every island would render unstyled — a preview that quietly lies
+// about how the component looks in the app. Re-anchoring the globs on the host root fixes that, and the
+// island sources are added so a class used ONLY inside an island still gets generated.
+//
+// Everything else (theme, plugins, dark mode, breakpoints) is inherited, so the lagoon and the app
+// cannot drift apart on design tokens.
+import { resolve } from 'node:path';
+import hostConfig from '{{hostRootFromLagoon}}/tailwind.config';
+
+const HOST_ROOT = resolve(__dirname, '{{hostRootFromLagoon}}');
+
+const hostContent = Array.isArray(hostConfig.content) ? hostConfig.content : (hostConfig.content?.files ?? []);
+
+export default {
+  ...hostConfig,
+  content: [
+    ...hostContent.map((glob) => (typeof glob === 'string' ? resolve(HOST_ROOT, glob) : glob)),
+    resolve(__dirname, '../../src/**/*.{ts,tsx}'),
+  ],
+};
+`;
+
+// --- host: next -------------------------------------------------------------------------------
+
+/** Next's own modules have no meaning in a plain Vite SPA — the lagoon stubs them so a client
+ *  component that links or routes still mounts. Kept deliberately small: anything an island needs
+ *  beyond this is a sign it is reaching for the host instead of emitting an intent. */
+export const NEXT_STUBS = `// Vite aliases point next/* here: the lagoon is a plain SPA with no Next runtime, but an island is
+// still allowed to render a link or read the router. Navigation intents belong to the host bridge
+// (@motujs/adapter-next), so these stubs are inert on purpose — they render and no-op, they never
+// navigate. If an island needs more of Next than this, it is coupling to the host too tightly.
+import { createElement, forwardRef, type ComponentProps } from 'react';
+
+export const Link = forwardRef<HTMLAnchorElement, ComponentProps<'a'> & { href?: unknown }>(
+  function Link({ href, children, ...rest }, ref) {
+    return createElement('a', { ...rest, ref, href: typeof href === 'string' ? href : '#' }, children);
+  },
+);
+
+export const Image = forwardRef<HTMLImageElement, ComponentProps<'img'>>(function Image(props, ref) {
+  return createElement('img', { ...props, ref });
+});
+
+const noop = () => {};
+
+export function useRouter() {
+  return { push: noop, replace: noop, back: noop, forward: noop, refresh: noop, prefetch: noop };
+}
+
+export function usePathname() {
+  return '/';
+}
+
+export function useSearchParams() {
+  return new URLSearchParams();
+}
+
+export function useParams() {
+  return {} as Record<string, string>;
+}
+
+export default Link;
+`;
+
+export const NEXT_VITE_IMPORTS = `import tailwindcss from 'tailwindcss';
+import autoprefixer from 'autoprefixer';
+`;
+
+/** Alias fragment for a Next host: the app's own '@/…' alias plus inert next/* stubs, so the lagoon
+ *  can mount components written against the host's conventions. */
+export const NEXT_VITE_ALIASES = `      // The lagoon mounts components written for the Next app, so it speaks the same module language:
+      // the host's '@/…' alias, and next/* mapped to inert stubs (see src/next-stubs.tsx).
+      { find: /^@\\//, replacement: resolve(__dirname, '{{hostRootFromLagoon}}') + '/' },
+      { find: /^next\\/link$/, replacement: resolve(__dirname, 'src/next-stubs.tsx') },
+      { find: /^next\\/image$/, replacement: resolve(__dirname, 'src/next-stubs.tsx') },
+      { find: /^next\\/navigation$/, replacement: resolve(__dirname, 'src/next-stubs.tsx') },
+`;
+
+/** Tailwind is the HOST's, not motu's: point postcss at the host config so an island's utility
+ *  classes render in the lagoon exactly as they do in the app. */
+export const NEXT_VITE_CSS = `  // Tailwind is the HOST's. It is loaded through the lagoon's own tailwind.config.ts (which extends the
+  // app's) rather than imported here, because Tailwind's loader handles a config that \`require()\`s CJS
+  // plugins and vite's ESM config bundling does not.
+  css: {
+    postcss: {
+      plugins: [tailwindcss({ config: resolve(__dirname, 'tailwind.config.ts') }), autoprefixer()],
+    },
+  },
+`;