@motujs/cli 0.0.0-stage → 0.1.1

package/bundled/packages/adapters/next/lagoon/next-stubs.tsx

@@ -0,0 +1,108 @@
+// Vite aliases point next/* here: the lagoon is a plain SPA with no Next runtime, but an island — or
+// the app's own layout, on a SCREEN — is still allowed to render a link or read the router.
+//
+// INERT BY DEFAULT. Navigation intents belong to the host bridge (@motujs/adapter-next), so outside a
+// screen these render and no-op: a link click is swallowed and logged, never followed (following it
+// left the lagoon for a 404). If an island needs more of Next than this, it is coupling to the host
+// too tightly.
+//
+// ON A SCREEN they follow the screen's declared routes (`@motujs/react` screens, experimental). A
+// screen renders the application's own layout, and a Next layout navigates with <Link> and
+// `useRouter()` rather than with motu intents — the sidebar of an app adopting motu is usually not a
+// region. So a click or `router.push(path)` is handed to the mounted screen, which opens whichever
+// screen serves `path` (or refuses out loud), and `usePathname()` / `useParams()` report the screen's
+// path so the layout lights the right item. They talk through two window events, which keeps this
+// adapter free of any dependency on @motujs/react.
+import { createElement, forwardRef, useSyncExternalStore, type ComponentProps, type MouseEvent } from 'react';
+
+/** Mirrors `window.__motuScreen` (lagoon-screen.tsx): set while a screen is showing. */
+interface ScreenLocation {
+  ok?: boolean;
+  path?: string;
+  params?: Record<string, string>;
+}
+const screenNow = (): ScreenLocation | undefined =>
+  typeof window === 'undefined' ? undefined : (window as unknown as { __motuScreen?: ScreenLocation }).__motuScreen;
+const onScreen = () => screenNow()?.ok === true && typeof screenNow()?.path === 'string';
+
+/** Hand a path to the mounted screen; outside one, stay inert and say so. */
+function go(path: string): void {
+  if (onScreen()) {
+    window.dispatchEvent(new CustomEvent('motu:screen-navigate', { detail: path }));
+    return;
+  }
+  console.log('[next stub] navigate', path, '— inert outside a screen');
+}
+
+const subscribe = (fn: () => void) => {
+  window.addEventListener('motu:screen-location', fn);
+  return () => window.removeEventListener('motu:screen-location', fn);
+};
+const pathSnapshot = () => (onScreen() ? (screenNow()!.path as string) : '/');
+const paramsKey = () => JSON.stringify(onScreen() ? screenNow()!.params ?? {} : {});
+
+const hrefOf = (href: unknown): string => {
+  if (typeof href === 'string') return href;
+  if (href && typeof href === 'object' && 'pathname' in href) return String((href as { pathname?: unknown }).pathname ?? '#');
+  return '#';
+};
+
+export const Link = forwardRef<HTMLAnchorElement, ComponentProps<'a'> & { href?: unknown; prefetch?: unknown; replace?: unknown; scroll?: unknown }>(
+  function Link({ href, children, onClick, prefetch, replace, scroll, ...rest }, ref) {
+    void prefetch;
+    void replace;
+    void scroll;
+    const to = hrefOf(href);
+    return createElement(
+      'a',
+      {
+        ...rest,
+        ref,
+        href: to,
+        onClick: (e: MouseEvent<HTMLAnchorElement>) => {
+          onClick?.(e);
+          if (e.defaultPrevented) return;
+          // A modified click (new tab, download) keeps the browser's own meaning.
+          if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+          if (/^[a-z]+:/i.test(to) || to.startsWith('#')) return; // external, mailto:, in-page anchors
+          e.preventDefault();
+          go(to);
+        },
+      },
+      children,
+    );
+  },
+);
+
+export const Image = forwardRef<HTMLImageElement, ComponentProps<'img'>>(function Image(props, ref) {
+  return createElement('img', { ...props, ref });
+});
+
+const noop = () => {};
+
+export function useRouter() {
+  return { push: (p: string) => go(p), replace: (p: string) => go(p), back: noop, forward: noop, refresh: noop, prefetch: noop };
+}
+
+export function usePathname() {
+  return useSyncExternalStore(subscribe, pathSnapshot, () => '/');
+}
+
+export function useSearchParams() {
+  const path = usePathname();
+  return new URLSearchParams(path.includes('?') ? path.slice(path.indexOf('?') + 1) : '');
+}
+
+export function useParams() {
+  return JSON.parse(useSyncExternalStore(subscribe, paramsKey, () => '{}')) as Record<string, string>;
+}
+
+/** Server-side in Next; a page that calls these is not something the lagoon renders. Fail loudly. */
+export function redirect(path: string): never {
+  throw new Error(`[next stub] redirect("${path}") — a server redirect has no meaning in the lagoon`);
+}
+export function notFound(): never {
+  throw new Error('[next stub] notFound() — a server 404 has no meaning in the lagoon');
+}
+
+export default Link;

package/bundled/packages/adapters/next/vite.mjs

@@ -0,0 +1,121 @@
+// The Next host's contribution to the lagoon's Vite config.
+//
+// This is host-adapter knowledge, not project configuration, which is why it lives here rather than in
+// every adopting project's vite.config.ts: mapping `next/*` to inert stubs, speaking the host's `@/…`
+// alias, and loading the host's own Tailwind are true of EVERY Next project motu is dropped into.
+// A project declares only what is genuinely its own — module stand-ins and browser env — in
+// lagoon.config.json.
+import { resolve, dirname } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The lagoon's Tailwind setup — the HOST's config, with one thing changed, GENERATED into `.motu/cache`
+ * rather than committed.
+ *
+ * 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.
+ *
+ * It is written to disk rather than passed as an object because Tailwind's own loader is what handles a
+ * host config that `require()`s CJS plugins — hand it a path and that keeps working; hand it an
+ * imported object and the ESM bundling that breaks on is back.
+ */
+/**
+ * The host's own Tailwind config, if it has one.
+ *
+ * A Next app does not necessarily use Tailwind, and this adapter used to assume it did: the postcss
+ * plugin was installed unconditionally and pointed at `<hostRoot>/tailwind.config`, so a Next host
+ * without one got a lagoon that 500s on the first CSS request with "Cannot find module" naming a
+ * generated file the project never wrote. Found by motu's own lagoon host, which is deliberately
+ * Tailwind-free — acme, the adapter's only other consumer, has Tailwind, so nothing had ever asked.
+ */
+function hostTailwindConfig(paths) {
+  for (const name of ['tailwind.config.ts', 'tailwind.config.js', 'tailwind.config.mjs', 'tailwind.config.cjs']) {
+    const candidate = resolve(paths.hostRoot, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * `writeIfChanged` comes from the CLI's contribute context, and using it is not housekeeping: this file
+ * lands in `.motu/cache`, which Vite WATCHES, and it is regenerated on every lagoon build. Writing the
+ * same bytes still bumps mtime, which still full-reloads every open lagoon tab — so a check running in
+ * another terminal used to reload the page a person was looking at. See the CLI's write-if-changed.mjs.
+ */
+function generateTailwindConfig(paths, writeIfChanged) {
+  mkdirSync(paths.cacheDir, { recursive: true });
+  const out = resolve(paths.cacheDir, 'tailwind.lagoon.config.ts');
+  writeIfChanged(
+    out,
+    `// GENERATED by motu (@motujs/adapter-next). Do not edit; do not commit.
+import { resolve } from 'node:path';
+import hostConfig from ${JSON.stringify(resolve(paths.hostRoot, 'tailwind.config'))};
+
+const HOST_ROOT = ${JSON.stringify(paths.hostRoot)};
+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)),
+    ${JSON.stringify(resolve(paths.appRoot, 'src/**/*.{ts,tsx}'))},
+  ],
+};
+`,
+  );
+  return out;
+}
+
+export async function contribute({ paths, lagoonJson, resolveBuildDep, writeIfChanged }) {
+  // Only when the HOST has one. See hostTailwindConfig: assuming it did is what made this adapter
+  // unusable on a Next app that styles itself any other way.
+  const usesTailwind = hostTailwindConfig(paths) !== null;
+  const tailwindcss = usesTailwind ? await resolveBuildDep('tailwindcss') : null;
+  const autoprefixer = await resolveBuildDep('autoprefixer');
+  const stubs = resolve(HERE, 'lagoon/next-stubs.tsx');
+
+  return {
+    define: {
+      // The host application's modules read process.env AT IMPORT TIME — a Supabase client that throws
+      // when its keys are missing is enough to take the whole lagoon down before anything renders, and
+      // the error ("process is not defined") says nothing about why. There is no backend here, so the
+      // values only have to exist: declare them under "env" in lagoon.config.json. Never put a real
+      // secret there — the lagoon gets published as a static page.
+      'process.env': JSON.stringify({ NODE_ENV: 'development', ...(lagoonJson.env ?? {}) }),
+    },
+    alias: [
+      // (the framework's own @motujs/* aliases are added unconditionally by buildLagoonViteConfig)
+      // Project aliases from lagoon.config.json "alias" — BEFORE the host's own '@/…' rule, because the
+      // first matching entry wins and '^@/' would otherwise rewrite the specifier to the real module
+      // before this ever sees it. This is the seam for standing a host module down inside the lagoon —
+      // a React context whose real provider talks to a backend, a service module that fetches on import
+      // — without touching the component that consumes it. Paths are relative to the lagoon root.
+      ...Object.entries(lagoonJson.alias ?? {}).map(([find, replacement]) => ({
+        find,
+        replacement: resolve(paths.lagoonDir, replacement),
+      })),
+      // 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.
+      { find: /^@\//, replacement: paths.hostRoot + '/' },
+      { find: /^next\/link$/, replacement: stubs },
+      { find: /^next\/image$/, replacement: stubs },
+      { find: /^next\/navigation$/, replacement: stubs },
+    ],
+    css: {
+      postcss: {
+        plugins: [
+          ...(usesTailwind ? [tailwindcss({ config: generateTailwindConfig(paths, writeIfChanged) })] : []),
+          autoprefixer(),
+        ],
+      },
+    },
+  };
+}

package/bundled/packages/adapters/vite/vite.mjs

@@ -0,0 +1,179 @@
+// The generic Vite host's contribution to the lagoon's Vite config.
+//
+// Every other adapter here RESTATES its framework: the Next one knows about `next/*` stubs, the app's
+// `@/…` alias and Tailwind, because a Next project's build is conventional enough to describe once.
+// A Vite application is not conventional — it IS its vite.config.ts — and any list motu wrote of what
+// such a project might need (linaria? lingui? svgr? a tsconfig-paths plugin? which aliases?) would be
+// a restatement that drifts the day the app adds a plugin.
+//
+// So this adapter states nothing. It LOADS the host's own config with Vite's own loader and borrows
+// two things from it: the plugins that transform the host's source, and the aliases that resolve it.
+// Same principle as the transport seam — consume the application's artifact rather than reproduce it —
+// and the reason it is worth the file is that it is what lets the lagoon render the host's REAL
+// components instead of stand-ins.
+//
+// Two classes of plugin are dropped, both because the lagoon is a different application than the one
+// the config was written for:
+//   - BUILD REPORTERS (visualizer, bundle-size guards) assert on an output the lagoon does not produce
+//   - the host's REACT plugin is kept, and motu's is then skipped: two React transforms in one
+//     pipeline is a duplicated JSX runtime, which surfaces as hooks failing in ways nothing explains
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * Plugins the lagoon does not borrow, because they describe a build it is not doing.
+ *
+ * Reporters and size guards assert on an output that does not exist here. SERVICE-WORKER plugins are
+ * the addition, and they are the sharpest case: `vite-plugin-pwa` contributes five plugins, and they
+ * do not merely go unused — `dev-sw` adds an `options` hook and `build` a `generateBundle`, which
+ * between them build the SERVICE WORKER from `srcDir` resolved into the lagoon's copied root, where
+ * nothing is. The whole build dies before anything renders:
+ *
+ *     [UNRESOLVED_ENTRY] Cannot resolve entry module .motu/cache/lagoon/src/service-worker.ts
+ *
+ * GUARDING THEM IS NOT ENOUGH, and that was tried first: the guard below drops a plugin whose hook
+ * THROWS, and this one does not throw. It succeeds and asks the build for an entry that cannot exist,
+ * so the failure lands in rolldown's entry resolution where no plugin hook can catch it.
+ *
+ * A service worker means nothing in a preview — it is offline caching for a deployed app — so this
+ * costs the lagoon nothing and is not a workaround.
+ *
+ * Measured on shlink (Vite + npm): the lagoon was unbootable, `motu lagoon serve` failed three times
+ * identically, and the adopter's fix was to fork the app's Vite config into their own repository —
+ * motu-only code in the host, which adopting motu exists to avoid.
+ */
+const DROP = /visualizer|bundle|size-?limit|checker|legacy|pwa|service-?worker|workbox/i;
+/** A React transform, whatever the flavour (plugin-react, plugin-react-swc, plugin-react-oxc). */
+const IS_REACT = /^vite:react|react-swc|react-oxc|react-babel|react-refresh/i;
+
+export async function contribute({ paths, lagoonJson }) {
+  const configFile = lagoonJson.hostViteConfig
+    ? resolve(paths.hostRoot, lagoonJson.hostViteConfig)
+    : ['vite.config.ts', 'vite.config.js', 'vite.config.mts'].map((f) => resolve(paths.hostRoot, f)).find(existsSync);
+
+  if (!configFile || !existsSync(configFile)) {
+    // Not an error: a Vite host with no config is a Vite host with nothing to borrow.
+    return {};
+  }
+
+  const vite = await import('vite');
+  // `serve`, not `build` — a config often branches on the command, and what the lagoon runs is a dev
+  // server. The host's `mode` env (loadEnv) is read by the config itself; nothing here supplies one.
+  const loaded = await vite.loadConfigFromFile({ command: 'serve', mode: 'development' }, configFile, paths.hostRoot);
+  if (!loaded?.config) return {};
+
+  const hostPlugins = (loaded.config.plugins ?? []).flat(Infinity).filter(Boolean);
+  const named = hostPlugins.filter((p) => typeof p?.name === 'string');
+  const kept = named.filter((p) => !DROP.test(p.name));
+
+  // A HOST PLUGIN THAT CANNOT RUN HERE IS DROPPED BY NAME, NOT ALLOWED TO KILL THE LAGOON.
+  //
+  // These are ALREADY-INSTANTIATED plugin objects, whose hooks closed over the config they were built
+  // for. The lagoon's root and envDir are not the host's, so a plugin whose `config`/`configResolved`
+  // hook asserts on them throws — and the throw propagates out of Vite before anything renders.
+  // Measured twice, on unrelated plugins: Mastodon's theme plugin
+  // (`if (!userConfig.root || !userConfig.envDir) throw new Error('Unknown project directory')`) and
+  // shlink's `vite-plugin-pwa` (resolving `srcDir` against the lagoon's copied root). Both times the
+  // whole lagoon was unbootable and the adopter's fix was to fork the app's Vite config into their own
+  // repository — motu-only code in the host, which adopting motu is supposed to avoid.
+  //
+  // So each borrowed plugin's config-time hooks are guarded. One that throws is removed and SAID, and
+  // the rest of the host's pipeline still transforms the host's real components. A dropped transform
+  // may of course mean a component that no longer compiles — which is a legible failure naming the
+  // plugin, instead of an assertion from a file the adopter did not write.
+  const dropped = [];
+  // EVERY HOOK THAT CAN FAIL, AND ASYNCHRONOUSLY. The first version wrapped four CONFIG-TIME hooks
+  // with a synchronous try/catch, which missed the case its own comment above names.
+  //
+  // `vite-plugin-pwa` does not throw while configuring. It succeeds, and then launches its OWN build
+  // for the service worker from `closeBundle` — against `srcDir` resolved into the lagoon's copied
+  // root, where nothing is:
+  //
+  //     [UNRESOLVED_ENTRY] Cannot resolve entry module .motu/cache/lagoon/src/service-worker.ts
+  //
+  // Two reasons the guard could not see it: `closeBundle` was not in the list, and that child build is
+  // ASYNC — it rejects a promise rather than throwing, so a synchronous `catch` never runs. Measured
+  // on shlink: the lagoon was unbootable, `lagoon serve` failed three times identically, and the
+  // adopter forked the app's Vite config into their own repo to get past it — motu-only code in the
+  // host, which adopting motu exists to avoid.
+  //
+  // A build-time hook that fails is dropped for the REST of the run too: a service worker half-built
+  // once is not worth attempting again on the next rebuild.
+  const HOOKS = [
+    'config',
+    'configResolved',
+    'configureServer',
+    'options',
+    'buildStart',
+    'transformIndexHtml',
+    'renderStart',
+    'generateBundle',
+    'writeBundle',
+    'buildEnd',
+    'closeBundle',
+  ];
+  const guard = (plugin) => {
+    const wrapped = { ...plugin };
+    const record = (hook, err) => {
+      if (!dropped.some((d) => d.name === plugin.name)) {
+        dropped.push({ name: plugin.name, hook, message: String(err?.message ?? err).split('\n')[0] });
+      }
+    };
+    for (const hook of HOOKS) {
+      const original = plugin[hook];
+      if (typeof original !== 'function') continue;
+      wrapped[hook] = function (...args) {
+        // Already failed once in this run: do not call it again.
+        if (dropped.some((d) => d.name === plugin.name)) return undefined;
+        try {
+          const out = original.apply(this, args);
+          // A REJECTED PROMISE IS A FAILURE TOO, and it is the one that mattered here.
+          return out && typeof out.then === 'function'
+            ? out.then(undefined, (err) => {
+                record(hook, err);
+                return undefined;
+              })
+            : out;
+        } catch (err) {
+          record(hook, err);
+          return undefined;
+        }
+      };
+    }
+    return wrapped;
+  };
+  const plugins = kept.map(guard);
+  // Reported through the returned contribution so the CLI can print it beside its other notices; the
+  // array is filled as the hooks run, which is after this function returns.
+  const droppedHostPlugins = dropped;
+  const hasReact = kept.some((p) => IS_REACT.test(p.name));
+
+  // The host's aliases, ABSOLUTE against the host root. A config that wrote them relative meant them
+  // relative to itself, and the lagoon's root is elsewhere.
+  //
+  // BOTH SHAPES. Vite accepts `resolve.alias` as an array of {find, replacement} OR as a plain object
+  // of find -> replacement, and this assumed the array — so a host using the object form (the shape
+  // Vite's own docs lead with) died on `.map is not a function` before the lagoon could build. Found
+  // by the first greenfield project on a vite host, whose config was written the documented way.
+  const declared = loaded.config.resolve?.alias ?? [];
+  const entries = Array.isArray(declared)
+    ? declared
+    : Object.entries(declared).map(([find, replacement]) => ({ find, replacement }));
+  const alias = entries.map((a) =>
+    typeof a?.replacement === 'string' && !a.replacement.startsWith('/') && /^[./]/.test(a.replacement)
+      ? { ...a, replacement: resolve(paths.hostRoot, a.replacement) }
+      : a,
+  );
+
+  return {
+    plugins,
+    /** Filled while the host's plugins run: those whose config-time hooks threw in this pipeline. */
+    droppedHostPlugins,
+    // Told to the lagoon builder, which owns the decision to add its own React plugin or not.
+    ownsReactTransform: hasReact,
+    alias,
+    // `tsconfigPaths: true` is a Vite 6+ resolve option; pass it through when the host uses it, since
+    // that is often the ONLY thing mapping the app's `@/…` imports.
+    ...(loaded.config.resolve?.tsconfigPaths ? { resolveExtra: { tsconfigPaths: true } } : {}),
+  };
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@motujs/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "The motu command line: scaffold islands, check that a page region still matches what it declares, and serve, snapshot or publish the lagoon preview.",
+  "keywords": [
+    "motu",
+    "react",
+    "islands",
+    "ui-architecture",
+    "state-management",
+    "cli",
+    "ui-testing",
+    "visual-regression",
+    "component-preview",
+    "storybook-alternative"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Scorbutics/motu.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Scorbutics/motu#readme",
+  "type": "module",
+  "bin": {
+    "motu": "src/cli.mjs"
+  },
+  "dependencies": {
+    "@happy-dom/global-registrator": "^20.11.2",
+    "@vitejs/plugin-basic-ssl": "^1.1.0",
+    "@vitejs/plugin-react": "^4.3.3",
+    "autoprefixer": "^10.4.20",
+    "axe-core": "^4.13.0",
+    "happy-dom": "^20.11.2",
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.62.1",
+    "pngjs": "^7.0.0",
+    "tailwindcss": "^3.4.0",
+    "ts-morph": "^28.0.0",
+    "tsx": "^4.23.12",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.10",
+    "@motujs/adapter-angularjs": "0.1.1",
+    "@motujs/chrome": "0.1.1",
+    "@motujs/adapter-next": "0.1.1",
+    "@motujs/core": "0.1.1",
+    "@motujs/debug-overlay": "0.1.1",
+    "@motujs/react": "0.1.1",
+    "@motujs/runtime": "0.1.1",
+    "@motujs/coverage": "0.1.1",
+    "@motujs/types": "0.1.1"
+  },
+  "devDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "files": [
+    "src",
+    "bundled"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
 }

package/src/alias-loader.mjs

@@ -0,0 +1,63 @@
+// A node ESM resolve hook that speaks the LAGOON's aliases.
+//
+// The happy-dom path (`--fast`) is plain node, which knows nothing about `@/…`, `motu-islands` or the
+// raw-TypeScript `@motujs/*` checkout — so it could not load an island that imports anything from its
+// own app, which is every island in a real project.
+//
+// NOT tsconfig `paths`, which is the obvious answer and the wrong one: those are a TYPE resolution
+// map, and a project may legitimately point one at a `.d.ts`. acme maps `react` to
+// `@types/react/index.d.ts` on purpose, to force one React type definition across a checkout boundary
+// — follow that at runtime and node tries to execute a declaration file.
+//
+// The aliases here are the ones motu already gives Vite, so the browser path and the node path resolve
+// the same specifier to the same file by construction rather than by two lists someone keeps in sync.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ASSET, ASSET_STUB, aliasEntries, mapSpecifier } from './lib/alias-core.mjs';
+
+const entries = aliasEntries();
+
+export async function resolve(specifier, context, nextResolve) {
+  // A stylesheet is not a module. Answering with an inert one keeps the component's own code running,
+  // which is the thing being checked; refusing would fail an island for importing its own CSS.
+  if (ASSET.test(specifier)) return { url: pathToFileURL(ASSET_STUB).href, shortCircuit: true };
+
+  const file = mapSpecifier(specifier, entries);
+  if (file) {
+    try {
+      return asModuleSource(await nextResolve(pathToFileURL(file).href, context));
+    } catch {
+      // An alias that resolves to nothing loadable is not fatal — fall through, so one stale entry
+      // cannot make every import fail, and node reports the original specifier honestly.
+    }
+  }
+  return asModuleSource(await nextResolve(specifier, context));
+}
+
+const SOURCE = /\.(ts|tsx|jsx)$/;
+const ESM_SYNTAX = /^\s*(import|export)\b/m;
+
+/**
+ * An application's own TypeScript is ESM, whatever its `package.json` says.
+ *
+ * A Next or Vite app is written in `import`/`export` and compiled by a bundler, so its package.json
+ * routinely has no `"type": "module"`. Plain node then classifies every `.tsx` in it as CommonJS, tsx
+ * compiles it that way, and the island's named import of it fails — "does not provide an export
+ * named 'ActionsGuide'" — because node cannot see esbuild's CJS exports. The registry imports every
+ * island, so ONE such file made `--fast` die for every island in the project, under an error naming
+ * an unrelated one. Bundlers never ask this question; this lane has to answer it the way they do.
+ *
+ * Narrow on purpose: only a TS/JSX source outside node_modules that node would load as CommonJS and
+ * that is written in ESM syntax. A genuinely CommonJS file keeps its format.
+ */
+function asModuleSource(result) {
+  if (!result?.url?.startsWith('file:') || result.format === 'module') return result;
+  if (!SOURCE.test(result.url) || result.url.includes('/node_modules/')) return result;
+  if (result.format && result.format !== 'commonjs') return result;
+  try {
+    if (!ESM_SYNTAX.test(readFileSync(fileURLToPath(result.url), 'utf8'))) return result;
+  } catch {
+    return result;
+  }
+  return { ...result, format: 'module' };
+}

package/src/alias-register.mjs

@@ -0,0 +1,28 @@
+// `--import` RUNS a module; it does not install resolver hooks. Only `module.register` does, and
+// forgetting that is silent: the hook file loads, exports `resolve`, and node never calls it.
+//
+// Both module systems need teaching, and only one of them is served by a hook. An island's `import`
+// goes through the ESM resolver; a `require` deeper in the graph does not, and acme died on exactly
+// that — past `@/app` through the hook, then `Cannot find module '@/lib/utils'` from CJS.
+import { createRequire, register } from 'node:module';
+import { ASSET, ASSET_STUB_CJS, aliasEntries, mapSpecifier } from './lib/alias-core.mjs';
+
+register('./alias-loader.mjs', import.meta.url);
+
+const require = createRequire(import.meta.url);
+const Module = require('node:module');
+const entries = aliasEntries();
+const original = Module._resolveFilename;
+
+Module._resolveFilename = function (request, ...rest) {
+  if (ASSET.test(request)) return ASSET_STUB_CJS;
+  const mapped = mapSpecifier(request, entries);
+  if (mapped) {
+    try {
+      return original.call(this, mapped, ...rest);
+    } catch {
+      // fall through to the original request, so a bad alias reports the real name
+    }
+  }
+  return original.call(this, request, ...rest);
+};

package/src/asset-stub.cjs

@@ -0,0 +1,3 @@
+// The CJS twin of asset-stub.mjs — a `require('./x.css')` deep in a dependency needs an answer too.
+module.exports = '';
+module.exports.__motuAssetStub = true;

package/src/asset-stub.mjs

@@ -0,0 +1,5 @@
+// What a stylesheet or an image becomes under the node harness. A bundler turns these into a class
+// map or a URL; node cannot parse them at all, and refusing to load one would fail an island for
+// importing its own CSS — which says nothing about whether the island works.
+export default '';
+export const __motuAssetStub = true;

package/src/cli.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// The `motu` entry point — a preflight, then the real CLI.
+//
+// WHY THIS FILE EXISTS. Everything below `run.mjs` is static ESM, so its imports are hoisted and
+// resolved before a single line of ours runs. A missing dependency therefore cannot be caught in
+// there: node prints `ERR_MODULE_NOT_FOUND: Cannot find package 'ts-morph'` with a stack, and exits.
+//
+// Measured on a clean machine, following the README exactly: clone, `./install.sh`, and then EVERY
+// command — including `motu --help` — died that way in about two seconds, because the documented
+// install path never installs the framework's own dependencies. That is the whole first impression a
+// stranger gets, so this checks first and says what to do.
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Node built-ins only, so it is safe above the dependency check.
+import { INSTALLED } from './lib/framework.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const CHECKOUT = resolve(here, '../../..');
+
+/** Packages the CLI needs to do anything at all, in the order a missing one would be hit. */
+const REQUIRED = ['ts-morph', 'tsx'];
+
+const require = createRequire(import.meta.url);
+const missing = REQUIRED.filter((name) => {
+  try {
+    require.resolve(name);
+    return false;
+  } catch {
+    return true;
+  }
+});
+
+if (missing.length && INSTALLED) {
+  // INSTALLED FROM NPM, the checkout advice below is wrong twice over: there is no checkout to `cd`
+  // into, and `./install.sh` does not exist. These are @motujs/cli's own dependencies, so a missing
+  // one is an interrupted or pruned install of it — the fix is in the app, not anywhere else.
+  console.error(`\x1b[31m✗ motu cannot start: ${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} not installed\x1b[0m`);
+  console.error(`\x1b[2m  ${missing.length > 1 ? 'They are dependencies' : 'It is a dependency'} of @motujs/cli, so its install is incomplete. Reinstall it:\x1b[0m`);
+  console.error('');
+  console.error('      npm i -D @motujs/cli');
+  console.error('');
+  process.exit(2);
+}
+
+if (missing.length) {
+  // A pnpm workspace: `npm install` cannot resolve `workspace:*`, so never suggest it. corepack ships
+  // with node and honours the declared `packageManager`, which is the one instruction that works
+  // whether or not pnpm is already on PATH.
+  const pm = existsSync(resolve(CHECKOUT, 'pnpm-lock.yaml')) ? 'corepack pnpm install' : 'npm install';
+  console.error(`\x1b[31m✗ motu cannot start: ${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} not installed\x1b[0m`);
+  console.error(`\x1b[2m  The framework resolves its own build tools from its checkout, so that checkout needs its\x1b[0m`);
+  console.error(`\x1b[2m  dependencies once — your project still needs none:\x1b[0m`);
+  console.error('');
+  console.error(`      cd ${CHECKOUT} && ${pm}`);
+  console.error('');
+  console.error(`\x1b[2m  Then re-run this command. (\`./install.sh\` does it for you.)\x1b[0m`);
+  process.exit(2);
+}
+
+// THE PACKAGES HAVE TO BE BUILT, and only in a checkout. `@motujs/*` publish compiled output — that is
+// what puts them inside a host's node_modules, where `react` resolves to the HOST's copy instead of
+// whatever sits next to motu. Their `exports` therefore point at `dist/`, which is gitignored, so a
+// fresh clone has none: the no-install links land on a package whose entry point does not exist, and
+// the host's bundler says `@motujs/core could not be resolved` — pointing at the consumer, not here.
+// Same failure mode the dependency check above exists for, one layer down.
+if (!INSTALLED && existsSync(resolve(CHECKOUT, 'packages/core/src/index.ts')) && !existsSync(resolve(CHECKOUT, 'packages/core/dist/index.js'))) {
+  console.error(`\x1b[31m✗ motu cannot start: the framework packages are not built\x1b[0m`);
+  console.error(`\x1b[2m  They ship compiled, so their entry points live in dist/ — which a fresh clone does not have:\x1b[0m`);
+  console.error('');
+  console.error(`      cd ${CHECKOUT} && node scripts/build-packages.mjs`);
+  console.error('');
+  console.error(`\x1b[2m  (\`./install.sh\` does it for you.)\x1b[0m`);
+  process.exit(2);
+}
+
+await import('./run.mjs');