@atolljs/cli 0.0.0-stage → 0.1.4

package/dist/cli.js

@@ -0,0 +1,2261 @@
+#!/usr/bin/env node
+
+// src/io.ts
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout, stderr } from "node:process";
+import { styleText } from "node:util";
+var PLAIN_FMT = { strong: (s) => s, dim: (s) => s, accent: (s) => s };
+function consoleIo(interactive) {
+  const color = process.env.NO_COLOR === void 0 && (process.env.FORCE_COLOR !== void 0 || stdout.isTTY === true);
+  const style = (f) => (s) => color ? styleText(f, s) : s;
+  const fmt = color ? { strong: style("bold"), dim: style("dim"), accent: style("cyan") } : PLAIN_FMT;
+  const okMark = style("green")(" \u2713 ");
+  const warnMark = style("yellow")(" ! ");
+  const errorMark = style("red")(" \u2717 ");
+  const rl = interactive ? createInterface({ input: stdin, output: stdout }) : null;
+  return {
+    interactive,
+    fmt,
+    print: (msg = "") => stdout.write(msg + "\n"),
+    ok: (msg) => stdout.write(`${okMark} ${msg}
+`),
+    warn: (msg) => stdout.write(`${warnMark} ${msg}
+`),
+    error: (msg) => stderr.write(`${errorMark} ${msg}
+`),
+    async ask(question, fallback = "") {
+      if (!rl) return fallback;
+      const answer = (await rl.question(`${fmt.strong(question)} `)).trim();
+      return answer || fallback;
+    },
+    async confirm(question, def = false) {
+      if (!rl) return def;
+      const hint = fmt.dim(`[${def ? "Y/n" : "y/N"}]`);
+      const answer = (await rl.question(`${fmt.strong(question)} ${hint} `)).trim().toLowerCase();
+      return answer === "" ? def : answer === "y" || answer === "yes";
+    },
+    async select(question, choices, def) {
+      if (!rl) return def;
+      stdout.write(fmt.strong(question) + "\n");
+      choices.forEach(
+        (c, i) => stdout.write(
+          `  ${fmt.accent(String(i + 1))}) ${c}${c === def ? fmt.dim(" (default)") : ""}
+`
+        )
+      );
+      const answer = (await rl.question(`${fmt.dim(`choose [1-${choices.length}]:`)} `)).trim();
+      if (answer === "") return def;
+      const pick = choices[Number(answer) - 1] ?? choices.find((c) => c === answer);
+      return pick ?? def;
+    },
+    close: () => rl?.close()
+  };
+}
+
+// src/parse.ts
+function parseArgs(argv) {
+  const _ = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      _.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+        flags[a.slice(2)] = argv[++i];
+      } else {
+        flags[a.slice(2)] = true;
+      }
+    } else if (a.startsWith("-") && a.length > 1) {
+      for (const ch of a.slice(1)) flags[ch] = true;
+    } else {
+      _.push(a);
+    }
+  }
+  return { _, flags };
+}
+var flag = (args, name) => typeof args.flags[name] === "string" ? args.flags[name] : void 0;
+var hasFlag = (args, ...names) => names.some((n) => args.flags[n] === true || typeof args.flags[n] === "string");
+var camel = (name) => name.replace(/[-_](.)/g, (_m, c) => c.toUpperCase());
+var pascal = (name) => {
+  const c = camel(name);
+  return c.charAt(0).toUpperCase() + c.slice(1);
+};
+var validName = (name) => /^[a-z][a-z0-9]*([-_][a-z0-9]+)*$/.test(name);
+
+// src/commands.ts
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join3, relative } from "node:path";
+
+// src/project.ts
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+function findRoot(cwd) {
+  let dir = cwd;
+  for (; ; ) {
+    if (existsSync(join(dir, "package.json"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function readPkg(dir) {
+  try {
+    return JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+var DEPS_OF = (pkg) => ({
+  ...pkg?.dependencies ?? {},
+  ...pkg?.devDependencies ?? {}
+});
+var DETECT = [
+  ["nestjs", ["@nestjs/core", "@nestjs/common"]],
+  ["nextjs", ["next"]],
+  ["angular", ["@angular/core"]],
+  ["svelte", ["svelte"]],
+  ["solid", ["solid-js"]],
+  ["vue", ["vue"]],
+  ["react", ["react", "react-dom"]],
+  ["node", ["@atolljs/node", "express", "fastify", "hono", "koa", "@nestjs/core"]]
+];
+function detectFramework(pkg) {
+  const deps = DEPS_OF(pkg);
+  for (const [fw, names] of DETECT) {
+    if (names.some((n) => deps[n] !== void 0)) return fw;
+  }
+  return "vanilla";
+}
+function detectPm(root) {
+  if (existsSync(join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(root, "yarn.lock"))) return "yarn";
+  if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock"))) return "bun";
+  return "npm";
+}
+function detectProject(cwd) {
+  const root = findRoot(cwd);
+  if (!root) {
+    return { root: null, pkg: null, framework: "vanilla", pm: "npm", srcDir: cwd };
+  }
+  const pkg = readPkg(root);
+  return {
+    root,
+    pkg,
+    framework: detectFramework(pkg),
+    pm: detectPm(root),
+    srcDir: existsSync(join(root, "src")) ? join(root, "src") : root
+  };
+}
+var ATOLL_DEPS = {
+  react: ["@atolljs/core", "@atolljs/react", "@atolljs/react-island", "zod"],
+  vue: ["@atolljs/core", "@atolljs/vue", "@atolljs/vue-island", "zod"],
+  solid: ["@atolljs/core", "@atolljs/solidjs", "@atolljs/solid-island", "zod"],
+  svelte: ["@atolljs/core", "@atolljs/svelte", "@atolljs/svelte-island", "zod"],
+  angular: ["@atolljs/core", "@atolljs/angular", "@atolljs/angular-island", "zod"],
+  nextjs: ["@atolljs/core", "@atolljs/nextjs", "zod"],
+  nestjs: ["@atolljs/core", "@atolljs/nestjs", "@atolljs/node", "zod"],
+  node: ["@atolljs/core", "@atolljs/node", "zod"],
+  vanilla: ["@atolljs/core", "zod"]
+};
+var ISLAND_FRAMEWORKS = [
+  "react",
+  "vue",
+  "solid",
+  "svelte",
+  "angular"
+];
+var pmInstallCmd = (pm, pkgs) => `${pm} ${pm === "npm" ? "install" : "add"} ${pkgs.join(" ")}`;
+function missingDeps(pkg, want) {
+  const deps = DEPS_OF(pkg);
+  return want.filter((d) => deps[d] === void 0);
+}
+
+// src/files.ts
+import { existsSync as existsSync2, mkdirSync, writeFileSync } from "node:fs";
+import { dirname as dirname2, join as join2, normalize } from "node:path";
+async function writeTree(io, cwd, files, opts = {}) {
+  for (const f of files) {
+    const abs = normalize(join2(cwd, f.path));
+    if (!abs.startsWith(normalize(cwd))) {
+      io.error(`refusing to write outside the project: ${io.fmt.accent(f.path)}`);
+      continue;
+    }
+    if (existsSync2(abs) && !opts.force) {
+      const overwrite = io.interactive ? await io.confirm(`${io.fmt.accent(f.path)} exists \u2014 overwrite?`, false) : false;
+      if (!overwrite) {
+        io.warn(
+          `skipped ${io.fmt.accent(f.path)} (exists \u2014 pass ${io.fmt.accent("--force")} to overwrite)`
+        );
+        continue;
+      }
+    }
+    mkdirSync(dirname2(abs), { recursive: true });
+    writeFileSync(abs, f.content);
+    io.ok(`created ${io.fmt.accent(f.path)}`);
+  }
+}
+
+// src/templates.ts
+var NPMRC = `# Supply-chain hardening \u2014 read by every npm command run in this directory.
+#
+# Newly published versions must age 7 days before they can enter the
+# lockfile (requires npm >= 11.10 \u2014 shipped with Node 26; older npm
+# silently ignores this key).
+min-release-age=7
+# Install lifecycle scripts are the dominant malware vector \u2014 none run
+# during install/ci. If a native dep ever legitimately needs one:
+#   npm rebuild <pkg> --ignore-scripts=false
+ignore-scripts=true
+# \`npm install <pkg>\` writes exact pins, not ^ ranges.
+save-exact=true
+fund=false
+`;
+var GITIGNORE = `node_modules/
+dist/
+`;
+function memoryContract(name) {
+  const c = camel(name);
+  return `import { defineSharedMemory, field, mz } from '@atolljs/core';
+
+/**
+ * ${c} shared memory \u2014 the single source of truth for state both threads
+ * touch. The spec compiles to one deterministic fixed-width layout; main
+ * thread and workers bind the same declaration, so the two sides can never
+ * disagree on byte offsets.
+ */
+export const ${c}Memory = defineSharedMemory({
+  // Versioned scalars \u2014 observe()/watch() park on Atomics; zero postMessage.
+  signals: {
+    progress: field.number(),
+  },
+  // Structured snapshots \u2014 one inline record, rewritten wholesale.
+  state: {
+    summary: field.object({
+      schema: mz.object({
+        total: mz.f64(),
+        errors: mz.f64(),
+        updatedAt: mz.u32(),
+      }),
+    }),
+  },
+});
+export type ${pascal(name)}Memory = typeof ${c}Memory;
+`;
+}
+function workerEntry(name, opts) {
+  const c = camel(name);
+  const memImport = opts.memoryImport ? `import { ${opts.memoryName} } from '${opts.memoryImport}';
+` : "";
+  const memLine = opts.memoryName ? `  sharedMemory: ${opts.memoryName},
+` : "";
+  const shim = opts.host === "node" ? `// Node worker entry \u2014 the shim binds self = parentPort BEFORE
+// defineWorker's bootstrap evaluates; import order is the contract.
+import '@atolljs/node/shim';
+` : "";
+  return `${shim}import { defineWorker, serviceMethod } from '@atolljs/core';
+import { z } from 'zod';
+${memImport}
+const echo = serviceMethod({
+  def: { argsSchema: z.tuple([z.string()]), resultSchema: z.string() },
+  run: (message) => {${opts.demoMemoryWrite && opts.memoryName ? `
+    // Shared memory crosses the boundary without a message \u2014 the main
+    // thread can read these the moment the task resolves.
+    ${opts.memoryName}.signals.progress.write(100);
+    ${opts.memoryName}.state.summary.write({
+      total: 1,
+      errors: 0,
+      updatedAt: Math.floor(Date.now() / 1000),
+    });` : ""}
+    return \`worker heard: \${message}\`;
+  },
+});
+
+/**
+ * ${c} worker entry \u2014 defineWorker installs the message loop and registers
+ * every method. The main thread imports only the TYPE (typeof ${c}Worker)
+ * and drives calls through the pool client.
+ */
+export const ${c}Worker = defineWorker({
+${memLine}  methods: { echo },
+});
+export type ${pascal(name)}Worker = typeof ${c}Worker;
+`;
+}
+function workerClientFile(name, opts) {
+  const c = camel(name);
+  const P = pascal(name);
+  const memImport = opts.memoryImport ? `import { ${opts.memoryName} } from '${opts.memoryImport}';
+` : "";
+  const memLine = opts.memoryName ? `  sharedMemory: ${opts.memoryName},
+` : "";
+  if (opts.host === "node") {
+    return `import { Worker } from 'node:worker_threads';
+import { workerClient, defineTask } from '@atolljs/core';
+import { createNodePool } from '@atolljs/node';
+${memImport}import type { ${P}Worker } from './${name}.worker';
+
+/**
+ * ${c} pool \u2014 node:worker_threads workers adapted to the pool surface.
+ * The worker entry must be bundled before spawning (Node workers run
+ * outside tsx's loader):
+ *
+ *   esbuild src/atoll/${name}.worker.ts --bundle --platform=node \\
+ *     --format=esm --packages=external --outfile=dist/${name}.worker.js
+ */
+export const ${c}Pool = createNodePool({
+  worker: () => new Worker(new URL('${opts.distUrl ?? `./dist/${name}.worker.js`}', import.meta.url)),
+${memLine}  poolSize: 'auto',
+});
+
+/** Typed client \u2014 calls read like the worker's own method names. */
+export const ${c} = workerClient<${P}Worker>(${c}Pool);
+
+/** Latest-wins task over a call \u2014 { data, pending, settled, elapsedMs }. */
+export const ${c}EchoTask = defineTask((message: string) => ${c}.echo(message));
+`;
+  }
+  return `import { connectWorker, defineTask } from '@atolljs/core';
+${memImport}import type { ${P}Worker } from './${name}.worker';
+
+/**
+ * ${c} \u2014 typed client over the worker pool. Spawning is lazy, so importing
+ * this module never touches Worker (SSR-safe); the first method call (or
+ * ${c}.start()) brings the pool up. Keep the new Worker(new URL(...)) call
+ * inline \u2014 bundlers detect worker entries by that exact shape.
+ */
+export const ${c} = connectWorker<${P}Worker>({
+  worker: () =>
+    new Worker(new URL('./${name}.worker.ts', import.meta.url), { type: 'module' }),
+${memLine}  poolSize: 'auto',
+});
+export type ${P}Client = typeof ${c};
+
+/** Latest-wins task over a call \u2014 { data, pending, settled, elapsedMs }. */
+export const ${c}EchoTask = defineTask((message: string) => ${c}.echo(message));
+`;
+}
+var ISLAND_EXT = {
+  react: "tsx",
+  vue: "ts",
+  solid: "tsx",
+  svelte: "ts",
+  angular: "ts"
+};
+function islandFiles(name, fw, dir = "src/islands") {
+  const P = pascal(name);
+  switch (fw) {
+    case "react":
+      return [
+        {
+          path: `${dir}/${name}.worker.tsx`,
+          content: `import { useState } from 'react';
+import { defineReactMonoWorker } from '@atolljs/react-island/worker';
+import { emit } from '@atolljs/islands/worker';
+
+/**
+ * ${P} \u2014 a real React component rendered INSIDE the worker. Mutations
+ * serialize to ops; the shell driver replays them into real DOM.
+ * Handlers receive the plain wire payload, not a SyntheticEvent.
+ */
+function ${P}({ label = '${name}' }: { label?: string }) {
+  const [count, setCount] = useState(0);
+  return (
+    <div>
+      <span>
+        {label}: {count}
+      </span>
+      <button
+        onClick={() => {
+          const n = count + 1;
+          setCount(n);
+          emit('incremented', { count: n });
+        }}
+      >
+        increment
+      </button>
+    </div>
+  );
+}
+
+export const worker = defineReactMonoWorker(${P});
+`
+        }
+      ];
+    case "vue":
+      return [
+        {
+          path: `${dir}/${P}.vue`,
+          content: `<script setup lang="ts">
+import { ref } from 'vue';
+import { emit } from '@atolljs/islands/worker';
+
+// Rendered inside the worker \u2014 DOM ops stream to the shell; emit()
+// sends app events back to it.
+defineProps<{ label?: string }>();
+const count = ref(0);
+function increment() {
+  count.value += 1;
+  emit('incremented', { count: count.value });
+}
+</script>
+
+<template>
+  <div>
+    <span>{{ label ?? '${name}' }}: {{ count }}</span>
+    <button @click="increment">increment</button>
+  </div>
+</template>
+`
+        },
+        {
+          path: `${dir}/${name}.worker.ts`,
+          content: `import { defineVueMonoWorker } from '@atolljs/vue-island/worker';
+import ${P} from './${P}.vue';
+
+export const worker = defineVueMonoWorker(${P});
+`
+        }
+      ];
+    case "solid":
+      return [
+        {
+          path: `${dir}/${name}.worker.tsx`,
+          content: `import { createSignal } from 'solid-js';
+import { defineSolidMonoWorker } from '@atolljs/solid-island/worker';
+import { emit } from '@atolljs/islands/worker';
+
+/** ${P} \u2014 Solid rendering inside the worker; ops stream to the shell. */
+function ${P}(props: { label?: string }) {
+  const [count, setCount] = createSignal(0);
+  return (
+    <div>
+      <span>
+        {props.label ?? '${name}'}: {count()}
+      </span>
+      <button
+        onClick={() => {
+          const n = count() + 1;
+          setCount(n);
+          emit('incremented', { count: n });
+        }}
+      >
+        increment
+      </button>
+    </div>
+  );
+}
+
+export const worker = defineSolidMonoWorker(${P});
+`
+        }
+      ];
+    case "svelte":
+      return [
+        {
+          path: `${dir}/${P}.svelte`,
+          content: `<script lang="ts">
+  import { emit } from '@atolljs/islands/worker';
+
+  // Rendered inside the worker \u2014 DOM ops stream to the shell.
+  let { label = '${name}' }: { label?: string } = $props();
+  let count = $state(0);
+  function increment() {
+    count += 1;
+    emit('incremented', { count });
+  }
+</script>
+
+<div>
+  <span>{label}: {count}</span>
+  <button onclick={increment}>increment</button>
+</div>
+`
+        },
+        {
+          path: `${dir}/${name}.worker.ts`,
+          content: `import { defineSvelteMonoWorker } from '@atolljs/svelte-island/worker';
+import ${P} from './${P}.svelte';
+
+export const worker = defineSvelteMonoWorker(${P});
+`
+        }
+      ];
+    case "angular":
+      return [
+        {
+          path: `${dir}/${name}.worker.ts`,
+          content: `import { Component } from '@angular/core';
+import { defineMonoWorker } from '@atolljs/islands/worker';
+import { angularIslandApp } from '@atolljs/angular-island/worker';
+
+/**
+ * ${P}Component \u2014 rendered inside the worker by Angular's own engine;
+ * ops stream to the shell driver on the main thread.
+ */
+@Component({
+  template: \`
+    <div>
+      <span>{{ label }}: {{ count }}</span>
+      <button (click)="increment()">increment</button>
+    </div>
+  \`,
+})
+export class ${P}Component {
+  label = '${name}';
+  count = 0;
+  increment() {
+    this.count += 1;
+  }
+}
+
+export const worker = defineMonoWorker(angularIslandApp(${P}Component));
+`
+        }
+      ];
+    default:
+      return [];
+  }
+}
+function islandUsage(name, fw) {
+  const P = pascal(name);
+  const ext = ISLAND_EXT[fw] ?? "ts";
+  const factory = `() => new Worker(new URL('./islands/${name}.worker.${ext}', import.meta.url), { type: 'module' })`;
+  switch (fw) {
+    case "react":
+      return `// mount it in your shell \u2014 worker factory stays inline so the bundler sees it
+import { Island } from '@atolljs/react-island';
+
+<Island app="${name}" worker={${factory}} onEvent={(n, p) => console.log(n, p)} />`;
+    case "vue":
+      return `<script setup>
+import { AtollIsland } from '@atolljs/vue-island';
+const worker = ${factory};
+</script>
+
+<template>
+  <AtollIsland app="${name}" :worker="worker" />
+</template>`;
+    case "solid":
+      return `import { Island } from '@atolljs/solid-island';
+
+<Island app="${name}" worker={${factory}} />`;
+    case "svelte":
+      return `<script lang="ts">
+  import { island } from '@atolljs/svelte-island';
+  const worker = ${factory};
+</script>
+
+<div use:island={{ app: '${name}', worker }} />`;
+    case "angular":
+      return `import { islandComponent } from '@atolljs/angular-island';
+import type { ${P}Component } from './islands/${name}.worker';
+
+export const ${P}Island = islandComponent<${P}Component>({
+  app: '${name}',
+  worker: ${factory},
+});
+// then use the generated component in a template \u2014 see docs/consumer Angular islands`;
+    default:
+      return "";
+  }
+}
+var HEADERS = `  // SharedArrayBuffer is gated behind cross-origin isolation \u2014 these
+  // headers unlock it; islands/pools degrade gracefully without them.
+  server: {
+    headers: {
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    },
+  },`;
+var SCAFFOLDS = {
+  react: {
+    deps: { react: "^19.3.0", "react-dom": "^19.3.0", "react-reconciler": "^0.34.0", "@atolljs/core": "^0.1.0", "@atolljs/react": "^0.1.0", "@atolljs/react-island": "^0.1.0", zod: "^4.6.5" },
+    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "@vitejs/plugin-react": "^6.1.1", "@types/react": "^19.3.0", "@types/react-dom": "^19.3.0" },
+    vitePlugin: { pkg: "@vitejs/plugin-react", import_: `import react from '@vitejs/plugin-react';`, call: "react()" }
+  },
+  vue: {
+    deps: { vue: "^3.5.43", "@atolljs/core": "^0.1.0", "@atolljs/vue": "^0.1.0", "@atolljs/vue-island": "^0.1.0", zod: "^4.6.5" },
+    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "@vitejs/plugin-vue": "^6.0.9" },
+    vitePlugin: { pkg: "@vitejs/plugin-vue", import_: `import vue from '@vitejs/plugin-vue';`, call: "vue()" }
+  },
+  solid: {
+    deps: { "solid-js": "^1.9.15", "@atolljs/core": "^0.1.0", "@atolljs/solidjs": "^0.1.0", "@atolljs/solid-island": "^0.1.0", zod: "^4.6.5" },
+    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "vite-plugin-solid": "^2.11.14" },
+    vitePlugin: { pkg: "vite-plugin-solid", import_: `import solid from 'vite-plugin-solid';`, call: "solid()" }
+  },
+  svelte: {
+    deps: { svelte: "^5.57.1", "@atolljs/core": "^0.1.0", "@atolljs/svelte": "^0.1.0", "@atolljs/svelte-island": "^0.1.0", zod: "^4.6.5" },
+    devDeps: { vite: "^8.3.1", typescript: "^7.0.2", "@sveltejs/vite-plugin-svelte": "^7.3.1" },
+    vitePlugin: { pkg: "@sveltejs/vite-plugin-svelte", import_: `import { svelte } from '@sveltejs/vite-plugin-svelte';`, call: "svelte()" }
+  }
+};
+var SCAFFOLD_FRAMEWORKS = Object.keys(SCAFFOLDS);
+function pkgJson(appName, spec) {
+  return JSON.stringify(
+    {
+      name: appName,
+      private: true,
+      type: "module",
+      scripts: { dev: "vite", build: "vite build", preview: "vite preview" },
+      dependencies: spec.deps,
+      devDependencies: spec.devDeps
+    },
+    null,
+    2
+  ) + "\n";
+}
+var TSCONFIGS = {
+  react: {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      lib: ["ESNext", "DOM", "DOM.Iterable"],
+      jsx: "react-jsx",
+      strict: true,
+      noEmit: true,
+      isolatedModules: true,
+      skipLibCheck: true,
+      allowImportingTsExtensions: true
+    },
+    include: ["src"]
+  },
+  vue: {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      lib: ["ESNext", "DOM", "DOM.Iterable"],
+      strict: true,
+      noEmit: true,
+      isolatedModules: true,
+      skipLibCheck: true,
+      allowImportingTsExtensions: true
+    },
+    include: ["src"]
+  },
+  solid: {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      lib: ["ESNext", "DOM", "DOM.Iterable"],
+      jsx: "preserve",
+      jsxImportSource: "solid-js",
+      strict: true,
+      noEmit: true,
+      isolatedModules: true,
+      skipLibCheck: true,
+      allowImportingTsExtensions: true
+    },
+    include: ["src"]
+  },
+  svelte: {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      lib: ["ESNext", "DOM", "DOM.Iterable"],
+      strict: true,
+      noEmit: true,
+      isolatedModules: true,
+      skipLibCheck: true,
+      allowImportingTsExtensions: true,
+      types: ["vite/client"]
+    },
+    include: ["src"]
+  },
+  node: {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      // DOM+WebWorker libs — @atolljs/node types pool workers against the
+      // DOM Worker surface; without them its shipped source won't typecheck.
+      lib: ["ESNext", "DOM", "WebWorker"],
+      types: ["node"],
+      strict: true,
+      noEmit: true,
+      isolatedModules: true,
+      skipLibCheck: true,
+      allowImportingTsExtensions: true
+    },
+    include: ["src"]
+  }
+};
+function viteConfig(fw) {
+  const spec = SCAFFOLDS[fw];
+  const plugin = spec.vitePlugin;
+  return `import { defineConfig } from 'vite';
+${plugin?.import_ ?? ""}
+
+export default defineConfig({
+  plugins: [${plugin?.call ?? ""}],
+${plugin ? `  // Worker bundles run their own rolldown pass \u2014 fresh plugin instances
+  // let the worker entry compile framework files too (worker-island apps).
+  worker: { plugins: () => [${plugin.call}] },
+` : ""}${HEADERS}
+});
+`;
+}
+var INDEX_HTML = (title, entry) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${title}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/${entry}"></script>
+  </body>
+</html>
+`;
+function scaffoldFiles(appName, fw) {
+  const spec = SCAFFOLDS[fw];
+  if (!spec) return [];
+  const files = [
+    { path: "package.json", content: pkgJson(appName, spec) },
+    { path: "tsconfig.json", content: JSON.stringify(TSCONFIGS[fw], null, 2) + "\n" },
+    { path: "vite.config.ts", content: viteConfig(fw) },
+    { path: ".npmrc", content: NPMRC },
+    { path: ".gitignore", content: GITIGNORE },
+    { path: "index.html", content: INDEX_HTML(appName, `src/main.${ISLAND_EXT[fw]}`) }
+  ];
+  const counter = islandFiles("counter", fw);
+  switch (fw) {
+    case "react":
+      files.push(
+        ...counter,
+        {
+          path: "src/main.tsx",
+          content: `import { createRoot } from 'react-dom/client';
+import { App } from './App';
+
+createRoot(document.getElementById('root')!).render(<App />);
+`
+        },
+        {
+          path: "src/App.tsx",
+          content: `import { Island } from '@atolljs/react-island';
+
+/**
+ * The counter island renders inside a worker \u2014 the main thread only replays
+ * its DOM ops. New islands: \`npx atoll add island <name>\`.
+ */
+export function App() {
+  return (
+    <main style={{ fontFamily: 'system-ui', padding: '2rem' }}>
+      <h1>${appName}</h1>
+      <p>This counter renders in a worker thread.</p>
+      <Island
+        app="counter"
+        worker={() =>
+          new Worker(new URL('./islands/counter.worker.tsx', import.meta.url), { type: 'module' })
+        }
+        onEvent={(name, payload) => console.log('island event:', name, payload)}
+      />
+    </main>
+  );
+}
+`
+        }
+      );
+      break;
+    case "vue":
+      files.push(
+        ...counter,
+        { path: "src/env.d.ts", content: `declare module '*.vue';
+` },
+        {
+          path: "src/main.ts",
+          content: `import { createApp } from 'vue';
+import App from './App.vue';
+
+createApp(App).mount('#root');
+`
+        },
+        {
+          path: "src/App.vue",
+          content: `<script setup lang="ts">
+import { AtollIsland } from '@atolljs/vue-island';
+
+// The counter island renders inside a worker \u2014 the main thread replays ops.
+const worker = () =>
+  new Worker(new URL('./islands/counter.worker.ts', import.meta.url), { type: 'module' });
+</script>
+
+<template>
+  <main style="font-family: system-ui; padding: 2rem">
+    <h1>${appName}</h1>
+    <p>This counter renders in a worker thread.</p>
+    <AtollIsland app="counter" :worker="worker" />
+  </main>
+</template>
+`
+        }
+      );
+      break;
+    case "solid":
+      files.push(
+        ...counter,
+        {
+          path: "src/main.tsx",
+          content: `import { render } from 'solid-js/web';
+import { App } from './App';
+
+render(() => <App />, document.getElementById('root')!);
+`
+        },
+        {
+          path: "src/App.tsx",
+          content: `import { Island } from '@atolljs/solid-island';
+
+/** The counter island renders inside a worker \u2014 the main thread replays ops. */
+export function App() {
+  return (
+    <main style={{ 'font-family': 'system-ui', padding: '2rem' }}>
+      <h1>${appName}</h1>
+      <p>This counter renders in a worker thread.</p>
+      <Island
+        app="counter"
+        worker={() =>
+          new Worker(new URL('./islands/counter.worker.tsx', import.meta.url), { type: 'module' })
+        }
+      />
+    </main>
+  );
+}
+`
+        }
+      );
+      break;
+    case "svelte":
+      files.push(
+        ...counter,
+        {
+          path: "src/main.ts",
+          content: `import { mount } from 'svelte';
+import App from './App.svelte';
+
+mount(App, { target: document.getElementById('root')! });
+`
+        },
+        {
+          path: "src/App.svelte",
+          content: `<script lang="ts">
+  import { island } from '@atolljs/svelte-island';
+
+  // The counter island renders inside a worker \u2014 the main thread replays ops.
+  const worker = () =>
+    new Worker(new URL('./islands/counter.worker.ts', import.meta.url), { type: 'module' });
+</script>
+
+<main style="font-family: system-ui; padding: 2rem">
+  <h1>${appName}</h1>
+  <p>This counter renders in a worker thread.</p>
+  <div use:island={{ app: 'counter', worker }} />
+</main>
+`
+        }
+      );
+      break;
+  }
+  return files;
+}
+function nodeScaffoldFiles(appName) {
+  return [
+    {
+      path: "package.json",
+      content: JSON.stringify(
+        {
+          name: appName,
+          private: true,
+          type: "module",
+          scripts: {
+            dev: "tsx watch src/main.ts",
+            start: "tsx src/main.ts",
+            bundle: "esbuild src/atoll/tasks.worker.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/tasks.worker.js"
+          },
+          dependencies: { "@atolljs/core": "^0.1.0", "@atolljs/node": "^0.1.0", zod: "^4.6.5" },
+          devDependencies: { esbuild: "^0.28.2", tsx: "^4.23.15", typescript: "^7.0.2", "@types/node": "^26.6.3" }
+        },
+        null,
+        2
+      ) + "\n"
+    },
+    { path: "tsconfig.json", content: JSON.stringify(TSCONFIGS.node, null, 2) + "\n" },
+    { path: ".npmrc", content: NPMRC },
+    { path: ".gitignore", content: GITIGNORE },
+    {
+      path: "src/atoll/tasks.memory.ts",
+      content: memoryContract("tasks")
+    },
+    {
+      path: "src/atoll/tasks.worker.ts",
+      content: workerEntry("tasks", {
+        host: "node",
+        memoryImport: "./tasks.memory",
+        memoryName: "tasksMemory",
+        demoMemoryWrite: true
+      })
+    },
+    {
+      path: "src/atoll/tasks.ts",
+      content: workerClientFile("tasks", {
+        host: "node",
+        memoryImport: "./tasks.memory",
+        memoryName: "tasksMemory",
+        distUrl: "../../dist/tasks.worker.js"
+      })
+    },
+    {
+      path: "src/main.ts",
+      content: `import { tasks, tasksPool } from './atoll/tasks';
+import { tasksMemory } from './atoll/tasks.memory';
+
+/**
+ * ${appName} \u2014 a worker pool behind a typed client. The echo task runs off
+ * the main thread; shared memory is readable here with zero dispatch.
+ */
+const heard = await tasks.echo('hello from main');
+console.log(heard);
+console.log('summary (shared memory):', tasksMemory.state.summary.read());
+
+await tasksPool.close();
+`
+    }
+  ];
+}
+function workerBindingsFile(name, fw, dir, mem) {
+  const c = camel(name);
+  const P = pascal(name);
+  const memImport = mem ? `import { ${mem.export_} } from '${mem.import_}';
+` : "";
+  const watchLine = (hook, decl = "const") => mem ? `
+  // ${decl} progress = ${hook}(${mem.export_}, 'signals.progress');` : "";
+  switch (fw) {
+    case "react":
+      return {
+        path: `${dir}/use${P}.ts`,
+        content: `import { useTask${mem ? ", useSharedValue" : ""} } from '@atolljs/react';
+import { ${c} } from './${name}';
+${memImport}
+/**
+ * React bindings for the ${name} pool \u2014 call inside components. useTask
+ * wraps a call in { data, pending, settled, elapsedMs, error } with
+ * latest-wins run()/runOnce(); useSharedValue parks on Atomics.
+ */
+export function use${P}() {
+  const echo = useTask(${c}.echo);${watchLine("useSharedValue")}
+  return { echo };
+}
+`
+      };
+    case "nextjs":
+      return {
+        path: `${dir}/${name}.tsx`,
+        content: `'use client';
+import { useTask${mem ? ", useSharedValue" : ""} } from '@atolljs/nextjs';
+import { ${c} } from './${name}';
+${memImport}
+/**
+ * Client component over the ${name} pool \u2014 'use client' keeps the hooks
+ * browser-side; SSR-safe because the pool spawns lazily on first call.
+ */
+export function ${P}() {
+  const echo = useTask(${c}.echo);${watchLine("useSharedValue")}
+  return (
+    <button onClick={() => echo.run('ping')}>
+      {echo.data ?? (echo.pending ? 'working\\u2026' : '${name}')}
+    </button>
+  );
+}
+`
+      };
+    case "vue":
+      return {
+        path: `${dir}/use${P}.ts`,
+        content: `import { useTask${mem ? ", useSharedValue" : ""} } from '@atolljs/vue';
+import { ${c} } from './${name}';
+${memImport}
+/** Vue composable over the ${name} pool \u2014 refs, ready for <script setup>. */
+export function use${P}() {
+  const echo = useTask(${c}.echo);${watchLine("useSharedValue")}
+  return { echo };
+}
+`
+      };
+    case "solid":
+      return {
+        path: `${dir}/use${P}.ts`,
+        content: `import { createTask${mem ? ", createSharedValue" : ""} } from '@atolljs/solidjs';
+import { ${c} } from './${name}';
+${memImport}
+/** Solid bindings over the ${name} pool \u2014 accessors, call inside setup. */
+export function create${P}() {
+  const echo = createTask(${c}.echo);${watchLine("createSharedValue")}
+  return { echo };
+}
+`
+      };
+    case "svelte":
+      return {
+        path: `${dir}/${name}.svelte.ts`,
+        content: `import { taskState${mem ? ", sharedValue" : ""} } from '@atolljs/svelte';
+import { ${c} } from './${name}';
+${memImport}
+/** Svelte bindings over the ${name} pool \u2014 call inside components. */
+export function ${c}State() {
+  const echo = taskState(${c}.echo);${watchLine("sharedValue")}
+  return { echo };
+}
+`
+      };
+    case "angular":
+      return {
+        path: `${dir}/${name}.facade.ts`,
+        content: `import { Injectable } from '@angular/core';
+import { taskState${mem ? ", sharedValue" : ""} } from '@atolljs/angular';
+import { ${c} } from './${name}';
+${memImport}
+/**
+ * Angular facade over the ${name} pool \u2014 field initializers run in the
+ * injection context, so the signal subscription unbinds on destroy.
+ */
+@Injectable({ providedIn: 'root' })
+export class ${P}Facade {
+  readonly echo = taskState(${c}.echo);${watchLine("sharedValue", "readonly")}
+  readonly run = (message: string) => this.echo.run(message);
+}
+`
+      };
+    default:
+      return null;
+  }
+}
+function islandFacadeFiles(name, fw, dir = "src/islands") {
+  const P = pascal(name);
+  const ext = ISLAND_EXT[fw] ?? "ts";
+  const contract = (appLine) => `/**
+ * ${name} island contract \u2014 shell-safe: the app reference + the worker
+ * factory. Never import ./${name}.worker.${ext} here \u2014 definePolyWorker
+ * installs worker-side globals on evaluation.
+ */
+${appLine}
+export const worker = () =>
+  new Worker(new URL('./${name}.worker.${ext}', import.meta.url), { type: 'module' });
+`;
+  switch (fw) {
+    case "react":
+    case "solid": {
+      const isReact = fw === "react";
+      const sig = isReact ? "useState" : "createSignal";
+      const poly = isReact ? "defineReactPolyWorker" : "defineSolidPolyWorker";
+      const pkg = `@atolljs/${fw}-island/worker`;
+      return [
+        {
+          path: `${dir}/${name}.app.tsx`,
+          content: `import { ${sig} } from '${isReact ? "react" : "solid-js"}';
+import { islandApp } from '@atolljs/islands/worker';
+import { emit } from '${pkg}';
+
+/**
+ * ${P}App \u2014 a real ${isReact ? "React" : "Solid"} component rendered INSIDE
+ * the worker. islandApp stamps the registry key (minification-proof); state
+ * never leaves the worker, DOM ops stream to the shell driver.
+ */
+export const ${P}App = islandApp('${name}', function ${P}(${isReact ? `{ label = '${name}' }: { label?: string }` : `props: { label?: string }`}) {
+  ${isReact ? "const [count, setCount] = useState(0);" : "const [count, setCount] = createSignal(0);"}
+  return (
+    <button
+      onClick={() => {
+        const n = ${isReact ? "count" : "count()"} + 1;
+        setCount(n);
+        emit('incremented', { count: n });
+      }}
+    >
+      ${isReact ? `{label}: {count}` : `{props.label ?? '${name}'}: {count()}`}
+    </button>
+  );
+});
+`
+        },
+        {
+          path: `${dir}/${name}.worker.${ext}`,
+          content: `import { ${poly} } from '${pkg}';
+import { ${P}App } from './${name}.app';
+
+/** One worker, many islands \u2014 add apps to the registry. */
+export const worker = ${poly}({ apps: { ${name}: ${P}App } });
+`
+        },
+        {
+          path: `${dir}/${name}.island.ts`,
+          content: contract(`export { ${P}App as app } from './${name}.app';`)
+        }
+      ];
+    }
+    case "vue": {
+      const [component] = islandFiles(name, "vue", dir);
+      return [
+        component,
+        {
+          path: `${dir}/${name}.worker.ts`,
+          content: `import { defineVuePolyWorker } from '@atolljs/vue-island/worker';
+import ${P} from './${P}.vue';
+
+/** One worker, many islands \u2014 add apps to the registry. */
+export const worker = defineVuePolyWorker({ apps: { ${name}: ${P} } });
+`
+        },
+        {
+          path: `${dir}/${name}.island.ts`,
+          content: contract(`export const app = '${name}';`)
+        }
+      ];
+    }
+    case "svelte": {
+      const [component] = islandFiles(name, "svelte", dir);
+      return [
+        component,
+        {
+          path: `${dir}/${name}.worker.ts`,
+          content: `import { defineSveltePolyWorker } from '@atolljs/svelte-island/worker';
+import ${P} from './${P}.svelte';
+
+/** One worker, many islands \u2014 add apps to the registry. */
+export const worker = defineSveltePolyWorker({ apps: { ${name}: ${P} } });
+`
+        },
+        {
+          path: `${dir}/${name}.island.ts`,
+          content: contract(`export const app = '${name}';`)
+        },
+        {
+          path: `${dir}/${P}Island.svelte`,
+          content: `<script lang="ts">
+  import { island } from '@atolljs/svelte-island';
+  import { app, worker } from './${name}.island';
+
+  // The facade component \u2014 attrs serialize to worker props on mount.
+  let { label = '${name}' }: { label?: string } = $props();
+</script>
+
+<div use:island={{ app, worker, props: { label } }} />
+`
+        }
+      ];
+    }
+    case "angular":
+      return [
+        {
+          path: `${dir}/${name}.component.ts`,
+          content: `import { Component, input, output } from '@angular/core';
+import { AngularIsland } from '@atolljs/angular-island/worker';
+
+/**
+ * ${P}Component \u2014 rendered inside the worker by Angular's own engine.
+ * @AngularIsland stamps the registry key and registers the component, so
+ * defineAngularPolyWorker() collects it with no hand-kept apps map.
+ */
+@AngularIsland('${name}')
+@Component({
+  standalone: true,
+  template: \`
+    <button (click)="increment()">{{ label() }}: {{ count }}</button>
+  \`,
+})
+export class ${P}Component {
+  label = input('${name}');
+  /** Root output() fields bridge to the shell's island event channel. */
+  incremented = output<{ count: number }>();
+  count = 0;
+  increment() {
+    this.count += 1;
+    this.incremented.emit({ count: this.count });
+  }
+}
+`
+        },
+        {
+          path: `${dir}/${name}.worker.ts`,
+          content: `import { defineAngularPolyWorker } from '@atolljs/angular-island/worker';
+import './${name}.component'; // registers via @AngularIsland
+
+/** One worker, many islands \u2014 decorated components self-register. */
+export const worker = defineAngularPolyWorker();
+`
+        },
+        {
+          path: `${dir}/${name}.island.ts`,
+          content: `import { islandComponent } from '@atolljs/angular-island';
+import type { ${P}Component } from './${name}.component';
+
+/**
+ * ${name} island facade \u2014 a standalone component typed off the worker
+ * component's input()/output() contract. Use <${name}-island> in templates.
+ */
+export const ${P}Island = islandComponent<${P}Component>({
+  app: '${name}',
+  selector: '${name}-island',
+  worker: () =>
+    new Worker(new URL('./${name}.worker.ts', import.meta.url), { type: 'module' }),
+});
+`
+        }
+      ];
+    default:
+      return [];
+  }
+}
+function islandFacadeUsage(name, fw) {
+  const P = pascal(name);
+  switch (fw) {
+    case "react":
+      return `import { Suspense } from 'react';
+import { lazyIsland } from '@atolljs/react-island';
+
+const ${P}Island = lazyIsland(() => import('./islands/${name}.island'));
+
+<Suspense fallback={null}>
+  <${P}Island label="${name}" onEvent={(n, p) => console.log(n, p)} />
+</Suspense>`;
+    case "vue":
+      return `<script setup>
+import { lazyIsland } from '@atolljs/vue-island';
+const ${P}Island = lazyIsland(() => import('./islands/${name}.island'));
+</script>
+
+<template>
+  <${P}Island label="${name}" />
+</template>`;
+    case "solid":
+      return `import { lazyIsland } from '@atolljs/solid-island';
+
+const ${P}Island = lazyIsland(() => import('./islands/${name}.island'));
+
+<${P}Island label="${name}" />`;
+    case "svelte":
+      return `<script lang="ts">
+  import ${P}Island from './islands/${P}Island.svelte';
+</script>
+
+<${P}Island label="${name}" />`;
+    case "angular":
+      return `import { ${P}Island } from './islands/${name}.island';
+// add ${P}Island to the host component's imports, then:
+// <${name}-island [props]="{ label: '${name}' }" (incremented)="onIncremented($event)" />`;
+    default:
+      return "";
+  }
+}
+function nestjsModuleFiles(name, dir, opts) {
+  const P = pascal(name);
+  const memImport = opts.mem ? `import { ${opts.mem.export_} } from '${opts.mem.import_}';
+` : "";
+  const serviceImport = opts.service ? `import { ${opts.service} } from './${name}.service';
+` : "";
+  const memLine = opts.mem ? `      sharedMemory: ${opts.mem.export_},
+` : `      // message-only \u2014 add sharedMemory: <contract> to give the pool a buffer
+`;
+  const providers = opts.service ? `  providers: [${opts.service}],
+  exports: [${opts.service}, AtollModule],
+` : "";
+  return [
+    {
+      path: `${dir}/${name}.module.ts`,
+      content: `import { Module } from '@nestjs/common';
+import { Worker } from 'node:worker_threads';
+import { AtollModule } from '@atolljs/nestjs';
+${serviceImport}${memImport}
+/**
+ * ${name} pool boundary \u2014 the feature module owns its worker domain.
+ * Imported by AppModule for the API thread (registerPool spawns workers)
+ * and by the worker entry (runAtollWorker boots the same module in-thread).
+ */
+@Module({
+  imports: [
+    AtollModule.registerPool({
+      name: '${name}',
+      // webpack emits the worker entry as its own chunk \u2014 keep the URL inline
+      worker: () => new Worker(new URL('./${name}.worker.ts', import.meta.url)),
+${memLine}      poolSize: 'auto',
+    }),
+  ],
+${providers}})
+export class ${P}Module {}
+`
+    },
+    {
+      path: `${dir}/${name}.worker.ts`,
+      content: `// Worker entry \u2014 boots a Nest application context inside the worker and
+// binds every @AtollService/@AtollTask provider in ${P}Module.
+import { runAtollWorker } from '@atolljs/nestjs/worker';
+import { ${P}Module } from './${name}.module';
+
+void runAtollWorker(${P}Module);
+`
+    }
+  ];
+}
+function nestjsServiceFiles(name, dir, mem) {
+  const P = pascal(name);
+  const memImport = mem ? `import { ${mem.export_} } from '${mem.import_}';
+` : "";
+  const memWrite = mem ? `
+    // shared memory crosses without a message \u2014 pick a real field:
+    // ${mem.export_}.signals.progress.write(100);` : "";
+  return [
+    {
+      path: `${dir}/${name}.service.ts`,
+      content: `import { Injectable } from '@nestjs/common';
+import { threadId } from 'node:worker_threads';
+import { AtollService } from '@atolljs/nestjs/decorators';
+${memImport}
+/**
+ * Service-level facade \u2014 the class IS the interop surface. Consumers inject
+ * it like any provider; every call dispatches to the '${name}' pool as a
+ * ${P}Service.method task and the body runs on the worker's DI'd instance.
+ */
+@Injectable()
+@AtollService({ pool: '${name}' })
+export class ${P}Service {
+  /** Runs inside the worker \u2014 the return value crosses postMessage. */
+  async echo(input: string) {${memWrite}
+    return { heard: input, worker: threadId };
+  }
+}
+`
+    },
+    ...nestjsModuleFiles(name, dir, { service: `${P}Service`, mem })
+  ];
+}
+function nestjsMethodFiles(name, dir) {
+  const P = pascal(name);
+  return [
+    {
+      path: `${dir}/${name}.service.ts`,
+      content: `import { Injectable } from '@nestjs/common';
+import { threadId } from 'node:worker_threads';
+import { AtollTask } from '@atolljs/nestjs/decorators';
+
+/**
+ * Method-level offload \u2014 only decorated methods dispatch to the pool; the
+ * rest of the class stays on the API thread. The body executes inside the
+ * worker's own Nest context on the DI-resolved instance.
+ */
+@Injectable()
+export class ${P}Service {
+  @AtollTask({ pool: '${name}' })
+  async run(input: string) {
+    return { heard: input, worker: threadId };
+  }
+
+  /** Not decorated \u2014 plain main-thread method. */
+  describe() {
+    return '${name} service, partial offload';
+  }
+}
+`
+    }
+  ];
+}
+function nestjsHousedFiles(name, dir) {
+  const P = pascal(name);
+  return [
+    {
+      path: `${dir}/${name}-atoll.module.ts`,
+      content: `// Main-side boundary \u2014 registers the '${name}' pool the housed API
+// runs in. Message-only by default; to share another pool's buffer, wrap
+// the factory:
+//   worker: withSharedBuffer(
+//     () => new Worker(new URL('./${name}.worker.ts', import.meta.url)),
+//     () => getAtollPool('<other-pool>')?.sharedBuffer,
+//   )
+import { Module } from '@nestjs/common';
+import { Worker } from 'node:worker_threads';
+import { AtollModule } from '@atolljs/nestjs';
+
+@Module({
+  imports: [
+    AtollModule.registerPool({
+      name: '${name}',
+      worker: () => new Worker(new URL('./${name}.worker.ts', import.meta.url)),
+      poolSize: 2,
+    }),
+  ],
+})
+export class ${P}AtollModule {}
+`
+    },
+    {
+      path: `${dir}/${name}.worker.ts`,
+      content: `// Dedicated HTTP worker \u2014 NOT a task worker: it serves requests, so no
+// runAtollWorker. serveHttp binds an internal 127.0.0.1 port and announces
+// it via the HTTP_PORT handshake; a respawned worker re-announces.
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import { serveHttp } from '@atolljs/node/http';
+import { ${P}ApiModule } from './${name}-api.module';
+
+void (async () => {
+  const app = await NestFactory.create(${P}ApiModule, { logger: ['warn', 'error'] });
+  await app.init();
+  serveHttp(app.getHttpServer(), { listen: 0 });
+})();
+`
+    },
+    {
+      path: `${dir}/${name}-api.module.ts`,
+      content: `// Worker-side module \u2014 pure HTTP surface (controllers/providers only).
+// No registerPool import: pools only exist on the main thread.
+import { Module } from '@nestjs/common';
+import { ${P}Controller } from './${name}.controller';
+
+@Module({ controllers: [${P}Controller] })
+export class ${P}ApiModule {}
+`
+    },
+    {
+      path: `${dir}/${name}.controller.ts`,
+      content: `import { Controller, Get } from '@nestjs/common';
+import { threadId } from 'node:worker_threads';
+
+/**
+ * Housed controller \u2014 exists ONLY inside '${name}' pool workers. The main
+ * app never sees these routes: it proxies /api/${name}/* into the workers'
+ * internal listeners, so decorators, DI, and guards execute off-thread.
+ */
+@Controller('api/${name}')
+export class ${P}Controller {
+  /** Which pool worker owns this request. */
+  @Get('whoami')
+  whoami() {
+    return { worker: threadId };
+  }
+}
+`
+    }
+  ];
+}
+function nestjsHousedWiring(name) {
+  return `main.ts \u2014 proxy the prefix into the pool:
+
+  import { getAtollPool } from '@atolljs/nestjs';
+  import { proxyToWorker, workerHttpPorts } from '@atolljs/node/http';
+
+  const pool = getAtollPool('${name}');
+  if (pool) {
+    const tracker = workerHttpPorts(pool);
+    app.use('/api/${name}', proxyToWorker({
+      pool,
+      tracker,
+      to: '/api/${name}',   // express strips the mount \u2014 restore it in-worker
+    }));
+  }`;
+}
+function nextjsRouteFiles(name, dir, variant) {
+  const c = camel(name);
+  const P = pascal(name);
+  const workerFactory = `createNodeWorker(
+        new Worker(new URL('./${name}.worker.ts', import.meta.url)),
+      )`;
+  if (variant === "task") {
+    return [
+      {
+        path: `${dir}/${name}.contract.ts`,
+        content: `import { z } from 'zod';
+import { defineSharedMemory, field, type TaskContract } from '@atolljs/core';
+
+/** Pool-owned shared state \u2014 the route handler reads it with zero dispatch. */
+export const ${c}Memory = defineSharedMemory({
+  jobsDone: field.number(),
+});
+
+const result = z.object({
+  echo: z.string(),
+  ms: z.number(),
+  jobsDone: z.number(),
+});
+
+/** Executed inside a worker via TaskRegistry. */
+export const ${P}Job: TaskContract<[input?: string], z.infer<typeof result>> = {
+  taskId: '${name}.run',
+  resultSchema: result,
+};
+`
+      },
+      {
+        path: `${dir}/${name}.worker.ts`,
+        content: `// Worker entry \u2014 the shim MUST be first: it binds self = parentPort
+// before workerBootstrap wires INIT_MEMORY / EXECUTE_TASK.
+import '@atolljs/node/shim';
+import '@atolljs/core/worker/workerBootstrap';
+import { TaskRegistry } from '@atolljs/core';
+import { ${c}Memory, ${P}Job } from './${name}.contract';
+
+TaskRegistry.register(${P}Job, (input = '${name}') => {
+  const t0 = performance.now();
+  const jobs = ${c}Memory.jobsDone.read() + 1;
+  ${c}Memory.jobsDone.write(jobs);
+  return { echo: \`worker heard: \${input}\`, ms: performance.now() - t0, jobsDone: jobs };
+});
+`
+      },
+      {
+        path: `${dir}/pool.ts`,
+        content: `import { Worker } from 'node:worker_threads';
+import { createNodePool, createNodeWorker } from '@atolljs/node';
+import { ${c}Memory, ${P}Job } from './${name}.contract';
+
+const create = () => {
+  const pool = createNodePool({
+    sharedMemory: ${c}Memory,
+    poolSize: 'auto',
+    tasks: { run: ${P}Job },
+    createWorker: () =>
+      ${workerFactory},
+  });
+  // Read memory via this getter \u2014 Next compiles module graphs per route
+  // layer, so a fresh contract import can be a second, unbound instance.
+  return { pool, memory: ${c}Memory };
+};
+
+// Module scope = process scope; globalThis survives dev-mode HMR reloads.
+export const get${P} = (): ReturnType<typeof create> => {
+  const g = globalThis as { __atoll${P}?: ReturnType<typeof create> };
+  return (g.__atoll${P} ??= create());
+};
+`
+      },
+      {
+        path: `${dir}/route.ts`,
+        content: `import { NextResponse } from 'next/server';
+import { get${P} } from './pool';
+
+// worker_threads need the Node.js runtime \u2014 Edge cannot spawn them.
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+/** POST /api/${name} {"input": "..."} \u2014 dispatch the task into the pool. */
+export async function POST(req: Request) {
+  const body = await req.json().catch(() => ({}));
+  return NextResponse.json(await get${P}().pool.run(body?.input));
+}
+
+/** GET /api/${name} \u2014 read shared state on this thread, no dispatch. */
+export async function GET() {
+  return NextResponse.json({ jobsDone: get${P}().memory.jobsDone.read() });
+}
+`
+      }
+    ];
+  }
+  return [
+    {
+      path: `${dir}/${name}.contract.ts`,
+      content: `import { defineSharedMemory, field } from '@atolljs/core';
+
+/** Pool-owned shared state \u2014 the route handler reads it with zero dispatch. */
+export const ${c}Memory = defineSharedMemory({
+  jobsDone: field.number(),
+});
+`
+    },
+    {
+      path: `${dir}/${name}.worker.ts`,
+      content: `// Worker entry \u2014 shim first, then defineWorker installs the message loop.
+import '@atolljs/node/shim';
+import { defineWorker, serviceMethod } from '@atolljs/core';
+import { z } from 'zod';
+import { ${c}Memory } from './${name}.contract';
+
+const echo = serviceMethod({
+  def: { argsSchema: z.tuple([z.string()]), resultSchema: z.string() },
+  run: (message) => {
+    ${c}Memory.jobsDone.write(${c}Memory.jobsDone.read() + 1);
+    return \`worker heard: \${message}\`;
+  },
+});
+
+export const ${c}Worker = defineWorker({
+  sharedMemory: ${c}Memory,
+  methods: { echo },
+});
+export type ${P}Worker = typeof ${c}Worker;
+`
+    },
+    {
+      path: `${dir}/pool.ts`,
+      content: `import { Worker } from 'node:worker_threads';
+import { workerClient } from '@atolljs/core';
+import { createNodePool, createNodeWorker } from '@atolljs/node';
+import { ${c}Memory } from './${name}.contract';
+// Type-only \u2014 worker code must not leak into the server bundle.
+import type { ${P}Worker } from './${name}.worker';
+
+const create = () => {
+  const pool = createNodePool({
+    sharedMemory: ${c}Memory,
+    poolSize: 'auto',
+    createWorker: () =>
+      ${workerFactory},
+  });
+  // Read memory via this getter \u2014 Next compiles module graphs per route
+  // layer, so a fresh contract import can be a second, unbound instance.
+  return { pool, client: workerClient<${P}Worker>(pool), memory: ${c}Memory };
+};
+
+// Module scope = process scope; globalThis survives dev-mode HMR reloads.
+export const get${P} = (): ReturnType<typeof create> => {
+  const g = globalThis as { __atoll${P}?: ReturnType<typeof create> };
+  return (g.__atoll${P} ??= create());
+};
+`
+    },
+    {
+      path: `${dir}/route.ts`,
+      content: `import { NextResponse } from 'next/server';
+import { get${P} } from './pool';
+
+// worker_threads need the Node.js runtime \u2014 Edge cannot spawn them.
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+/** POST /api/${name} {"input": "..."} \u2014 a typed client call into the pool. */
+export async function POST(req: Request) {
+  const body = await req.json().catch(() => ({}));
+  return NextResponse.json({
+    echo: await get${P}().client.echo(String(body?.input ?? '${name}')),
+  });
+}
+
+/** GET /api/${name} \u2014 read shared state on this thread, no dispatch. */
+export async function GET() {
+  return NextResponse.json({ jobsDone: get${P}().memory.jobsDone.read() });
+}
+`
+    }
+  ];
+}
+function nextjsComponentFiles(name, dir, mem) {
+  const c = camel(name);
+  const P = pascal(name);
+  return [
+    {
+      path: `${dir}/${name}.tsx`,
+      content: `'use client';
+import { useTask${mem ? ", useSharedValue" : ""} } from '@atolljs/nextjs';
+import { ${c} } from './${name}';
+${mem ? `import { ${mem.export_} } from '${mem.import_}';
+` : ""}
+/**
+ * ${P} \u2014 a client component over the ${name} pool. Field reads return
+ * undefined until the contract binds on the client (SSR-safe).
+ */
+export function ${P}() {
+  const echo = useTask(${c}.echo);${mem ? `
+  const progress = useSharedValue(${mem.export_}, 'signals.progress');` : ""}
+  return (
+    <button onClick={() => echo.run('ping')}>
+      {echo.data ?? (echo.pending ? 'working\\u2026' : '${name}')}
+    </button>
+  );
+}
+`
+    }
+  ];
+}
+function nextjsInstrumentationFile(name, dir = "src") {
+  const P = pascal(name);
+  return {
+    path: `${dir}/instrumentation.ts`,
+    content: `/**
+ * Next.js server bootstrap \u2014 runs once when the Node.js runtime boots.
+ * Dynamic imports keep node:worker_threads out of the edge/browser bundles.
+ */
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
+  const { get${P} } = await import('./app/api/${name}/pool');
+  get${P}(); // spawn workers + bind the buffer during startup, not per request
+}
+`
+  };
+}
+
+// src/commands.ts
+var NODE_HOSTS = ["node", "nestjs"];
+var hostOf = (fw) => NODE_HOSTS.includes(fw) ? "node" : "browser";
+async function offerInstall(ctx, project, pkgs, installAll = false) {
+  if (hasFlag(ctx.args, "no-install")) {
+    ctx.io.warn("--no-install \u2014 skipping dependency install");
+    return;
+  }
+  const missing = missingDeps(project.pkg, pkgs);
+  if (missing.length === 0 && !installAll) return;
+  const cmd = pmInstallCmd(project.pm, installAll ? [] : missing);
+  const yes = await ctx.io.confirm(`install dependencies? (${ctx.io.fmt.accent(cmd)})`, true);
+  if (!yes) {
+    ctx.io.warn(`skipped \u2014 run ${ctx.io.fmt.accent(cmd)} when ready`);
+    return;
+  }
+  ctx.io.print(
+    ctx.io.fmt.dim(
+      "note: bootstrap install runs with --min-release-age=0 \u2014 the new .npmrc policy applies from the next install on"
+    )
+  );
+  const [bin, ...rest] = cmd.split(" ").filter(Boolean);
+  const r = spawnSync(bin, [...rest, "--min-release-age=0"], {
+    cwd: project.root ?? ctx.cwd,
+    stdio: "inherit"
+  });
+  if (r.status !== 0) throw new Error(`install failed \u2014 run \`${cmd}\` manually`);
+}
+async function runInit(ctx) {
+  const project = detectProject(ctx.cwd);
+  if (!project.root || !project.pkg) {
+    ctx.io.error("no package.json found \u2014 run `atoll new <dir>` to scaffold, or cd into a project");
+    return 1;
+  }
+  const rel = (abs) => relative(ctx.cwd, abs).replaceAll("\\", "/");
+  ctx.io.print(
+    ctx.io.fmt.dim(
+      `detected: ${project.framework} \xB7 ${project.pm} \xB7 root ${project.root}`
+    )
+  );
+  await writeTree(ctx.io, ctx.cwd, [{ path: rel(join3(project.root, ".npmrc")), content: NPMRC }], {
+    force: hasFlag(ctx.args, "force")
+  });
+  await offerInstall(ctx, project, ATOLL_DEPS[project.framework]);
+  const atollDir = join3(project.srcDir, "atoll");
+  const host = hostOf(project.framework);
+  const name = flag(ctx.args, "name") ?? "app";
+  const files = [
+    { path: `${rel(atollDir)}/${name}.memory.ts`, content: memoryContract(name) },
+    {
+      path: `${rel(atollDir)}/${name}.worker.ts`,
+      content: workerEntry(name, {
+        host,
+        memoryImport: `./${name}.memory`,
+        memoryName: `${camel(name)}Memory`,
+        demoMemoryWrite: true
+      })
+    },
+    {
+      path: `${rel(atollDir)}/${name}.ts`,
+      content: workerClientFile(name, {
+        host,
+        memoryImport: `./${name}.memory`,
+        memoryName: `${camel(name)}Memory`,
+        // src/atoll/x.ts → <root>/dist/x.worker.js
+        distUrl: `${relative(atollDir, join3(project.root, "dist")).replaceAll("\\", "/")}/${name}.worker.js`
+      })
+    }
+  ];
+  await writeTree(ctx.io, ctx.cwd, files, { force: hasFlag(ctx.args, "force") });
+  ctx.io.print("");
+  ctx.io.print(ctx.io.fmt.strong("next steps:"));
+  if (host === "node") {
+    ctx.io.print(
+      `  bundle the worker entry (see the comment in ${name}.ts), then call ${ctx.io.fmt.accent(`${camel(name)}.echo('hi')`)}`
+    );
+  } else {
+    ctx.io.print(
+      `  call ${ctx.io.fmt.accent(`${camel(name)}.echo('hi')`)} \u2014 the pool spawns lazily on first call`
+    );
+  }
+  ctx.io.print(
+    `  ${ctx.io.fmt.accent("atoll add worker|memory|island <name>")} grows it \xB7 ${ctx.io.fmt.accent("atoll doctor")} checks the setup`
+  );
+  return 0;
+}
+var ADD_KINDS = [
+  "worker",
+  "memory",
+  "island",
+  "service",
+  "method",
+  "module",
+  "housed",
+  "route",
+  "component",
+  "instrumentation"
+];
+var KIND_SCOPE = {
+  worker: null,
+  memory: null,
+  island: ISLAND_FRAMEWORKS,
+  service: ["nestjs"],
+  method: ["nestjs"],
+  module: ["nestjs"],
+  housed: ["nestjs"],
+  route: ["nextjs"],
+  component: ["nextjs"],
+  instrumentation: ["nextjs"]
+};
+var KIND_VARIANTS = {
+  island: ["facade", "mono"],
+  route: ["task", "client"]
+};
+var FRAMEWORK_WORDS = [
+  "angular",
+  "nestjs",
+  "nextjs",
+  "node",
+  "react",
+  "solid",
+  "svelte",
+  "vanilla",
+  "vue"
+];
+async function pickName(ctx, kind, given) {
+  const name = given ?? flag(ctx.args, "name") ?? await ctx.io.ask(`${kind} name (kebab-case):`, "");
+  if (!name || !validName(name)) {
+    ctx.io.error(
+      `invalid ${kind} name ${ctx.io.fmt.accent(name)} \u2014 lowercase kebab-case, e.g. incidents-report`
+    );
+    return null;
+  }
+  return name;
+}
+function resolveMemory(ctx, dir, name) {
+  if (hasFlag(ctx.args, "no-memory")) return null;
+  const want = flag(ctx.args, "memory") ?? name;
+  const direct = join3(dir, `${want}.memory.ts`);
+  if (existsSync3(direct)) {
+    return { import_: `./${want}.memory`, export_: `${camel(want)}Memory` };
+  }
+  const candidates = readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".memory.ts")).map((e) => e.name.slice(0, -".memory.ts".length));
+  const only = candidates.length === 1 ? candidates[0] : null;
+  return only ? { import_: `./${only}.memory`, export_: `${camel(only)}Memory` } : null;
+}
+async function runAdd(ctx) {
+  const project = detectProject(ctx.cwd);
+  if (!project.root) {
+    ctx.io.error("no package.json found \u2014 cd into a project or run `atoll new`");
+    return 1;
+  }
+  const rel = (abs) => relative(ctx.cwd, abs).replaceAll("\\", "/");
+  let rest = ctx.args._.slice(1);
+  let framework = flag(ctx.args, "framework");
+  if (rest[0] && FRAMEWORK_WORDS.includes(rest[0])) {
+    framework ??= rest[0];
+    rest = rest.slice(1);
+  }
+  framework ??= project.framework;
+  let kind = rest[0];
+  if (!kind) {
+    const available = ADD_KINDS.filter(
+      (k) => !KIND_SCOPE[k] || KIND_SCOPE[k].includes(framework)
+    );
+    kind = ctx.io.interactive ? await ctx.io.select("add what?", available, available[0]) : void 0;
+    if (!kind) {
+      ctx.io.error(`expected a kind \u2014 ${ADD_KINDS.join(" | ")}`);
+      return 1;
+    }
+    rest = [kind, ...rest.slice(1)];
+  }
+  if (!ADD_KINDS.includes(kind)) {
+    ctx.io.error(`unknown add target ${ctx.io.fmt.accent(kind)} \u2014 expected ${ADD_KINDS.join(" | ")}`);
+    return 1;
+  }
+  const scope = KIND_SCOPE[kind];
+  if (scope && !scope.includes(framework)) {
+    ctx.io.error(
+      `${kind} is for ${scope.join("/")} projects \u2014 detected "${framework}". Pass a framework word (e.g. \`atoll add nestjs ${kind} \u2026\`) to override.`
+    );
+    return 1;
+  }
+  const variants = KIND_VARIANTS[kind];
+  let variant;
+  let nameArg;
+  if (variants) {
+    if (rest[1] && variants.includes(rest[1])) {
+      variant = rest[1];
+      nameArg = rest[2];
+    } else {
+      nameArg = rest[1];
+    }
+    variant = flag(ctx.args, "variant") ?? variant;
+    if (variant && !variants.includes(variant)) {
+      ctx.io.error(`unknown ${kind} variant ${ctx.io.fmt.accent(variant)} \u2014 pick ${variants.join(" | ")}`);
+      return 1;
+    }
+    variant ??= ctx.io.interactive ? await ctx.io.select(`${kind} variant:`, variants, variants[0]) : variants[0];
+  } else {
+    nameArg = rest[1];
+  }
+  const name = await pickName(ctx, kind, nameArg);
+  if (!name) return 1;
+  const force = { force: hasFlag(ctx.args, "force") };
+  const atollDir = flag(ctx.args, "dir") ?? rel(join3(project.srcDir, "atoll"));
+  const c = camel(name);
+  const P = pascal(name);
+  switch (kind) {
+    case "memory": {
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        [{ path: `${atollDir}/${name}.memory.ts`, content: memoryContract(name) }],
+        force
+      );
+      ctx.io.print(
+        `
+bind it: pass ${ctx.io.fmt.accent(`${c}Memory`)} as ${ctx.io.fmt.accent("sharedMemory")} to defineWorker/connectWorker,`
+      );
+      ctx.io.print(
+        `or ${ctx.io.fmt.accent(`atoll add worker ${name}`)} in the same directory wires it automatically.`
+      );
+      return 0;
+    }
+    case "worker": {
+      const dir = atollDir;
+      mkdirSync2(join3(ctx.cwd, dir), { recursive: true });
+      const host = hostOf(framework);
+      const mem = resolveMemory(ctx, join3(ctx.cwd, dir), name);
+      const opts = {
+        host,
+        memoryImport: mem?.import_ ?? null,
+        memoryName: mem?.export_,
+        distUrl: `${relative(join3(ctx.cwd, dir), join3(project.root, "dist")).replaceAll("\\", "/")}/${name}.worker.js`
+      };
+      const bindings = workerBindingsFile(name, framework, dir, mem);
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        [
+          { path: `${dir}/${name}.worker.ts`, content: workerEntry(name, opts) },
+          { path: `${dir}/${name}.ts`, content: workerClientFile(name, opts) },
+          ...bindings ? [bindings] : []
+        ],
+        force
+      );
+      ctx.io.print("");
+      if (host === "node") {
+        ctx.io.print(`bundle before spawning \u2014 add to package.json scripts:`);
+        ctx.io.print(
+          ctx.io.fmt.accent(
+            `  "bundle:${name}": "esbuild ${dir}/${name}.worker.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/${name}.worker.js"`
+          )
+        );
+      } else {
+        ctx.io.print(
+          `call ${ctx.io.fmt.accent(`${c}.echo('hi')`)} \u2014 the pool spawns lazily on first call`
+        );
+        if (bindings) ctx.io.print(`framework bindings: ${ctx.io.fmt.accent(bindings.path)}`);
+      }
+      return 0;
+    }
+    case "island": {
+      const dir = flag(ctx.args, "dir") ?? rel(join3(project.srcDir, "islands"));
+      const files = variant === "facade" ? islandFacadeFiles(name, framework, dir) : islandFiles(name, framework, dir);
+      await writeTree(ctx.io, ctx.cwd, files, force);
+      const usage = variant === "facade" ? islandFacadeUsage(name, framework) : islandUsage(name, framework);
+      if (usage) {
+        ctx.io.print(ctx.io.fmt.strong("\nshell side:"));
+        ctx.io.print(usage);
+      }
+      return 0;
+    }
+    case "service": {
+      const dir = atollDir;
+      mkdirSync2(join3(ctx.cwd, dir), { recursive: true });
+      const mem = resolveMemory(ctx, join3(ctx.cwd, dir), name);
+      await writeTree(ctx.io, ctx.cwd, nestjsServiceFiles(name, dir, mem), force);
+      ctx.io.print("");
+      ctx.io.print(
+        `inject ${ctx.io.fmt.accent(`${P}Service`)} anywhere \u2014 every method dispatches to the ${ctx.io.fmt.accent(`'${name}'`)} pool.`
+      );
+      return 0;
+    }
+    case "method": {
+      const dir = atollDir;
+      mkdirSync2(join3(ctx.cwd, dir), { recursive: true });
+      await writeTree(ctx.io, ctx.cwd, nestjsMethodFiles(name, dir), force);
+      ctx.io.print("");
+      ctx.io.print(
+        `needs a '${name}' pool \u2014 ${ctx.io.fmt.accent(`atoll add nestjs module ${name}`)} registers one,`
+      );
+      ctx.io.print(`and the worker entry must runAtollWorker a module providing ${P}Service.`);
+      return 0;
+    }
+    case "module": {
+      const dir = atollDir;
+      mkdirSync2(join3(ctx.cwd, dir), { recursive: true });
+      const mem = resolveMemory(ctx, join3(ctx.cwd, dir), name);
+      await writeTree(ctx.io, ctx.cwd, nestjsModuleFiles(name, dir, { mem }), force);
+      ctx.io.print("");
+      ctx.io.print(
+        `import ${ctx.io.fmt.accent(`${P}Module`)} into AppModule \u2014 then ${ctx.io.fmt.accent(`atoll add nestjs service ${name}`)} adds the facade.`
+      );
+      return 0;
+    }
+    case "housed": {
+      const dir = atollDir;
+      mkdirSync2(join3(ctx.cwd, dir), { recursive: true });
+      await writeTree(ctx.io, ctx.cwd, nestjsHousedFiles(name, dir), force);
+      ctx.io.print("");
+      ctx.io.print(ctx.io.fmt.strong("wire the gateway:"));
+      ctx.io.print(nestjsHousedWiring(name));
+      ctx.io.print(ctx.io.fmt.dim(`routes live only in workers \u2014 GET /api/${name}/whoami`));
+      return 0;
+    }
+    case "route": {
+      const dir = flag(ctx.args, "dir") ?? rel(join3(project.srcDir, "app/api", name));
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        nextjsRouteFiles(name, dir, variant),
+        force
+      );
+      ctx.io.print("");
+      ctx.io.print(
+        `${ctx.io.fmt.accent(`POST /api/${name}`)} dispatches into the pool \xB7 ${ctx.io.fmt.accent(`GET /api/${name}`)} reads shared memory.`
+      );
+      ctx.io.print(
+        ctx.io.fmt.dim(`warm it at boot: atoll add nextjs instrumentation ${name}`)
+      );
+      return 0;
+    }
+    case "component": {
+      const dir = atollDir;
+      mkdirSync2(join3(ctx.cwd, dir), { recursive: true });
+      const mem = resolveMemory(ctx, join3(ctx.cwd, dir), name);
+      await writeTree(ctx.io, ctx.cwd, nextjsComponentFiles(name, dir, mem), force);
+      ctx.io.print("");
+      ctx.io.print(
+        `expects the ${ctx.io.fmt.accent(`./${name}`)} client + contract beside it \u2014 ${ctx.io.fmt.accent(`atoll add nextjs worker ${name}`)} first.`
+      );
+      return 0;
+    }
+    case "instrumentation": {
+      await writeTree(
+        ctx.io,
+        ctx.cwd,
+        [nextjsInstrumentationFile(name, rel(project.srcDir))],
+        force
+      );
+      ctx.io.print(
+        `
+pools warm at boot \u2014 extend register() as more routes appear.`
+      );
+      return 0;
+    }
+    default:
+      ctx.io.error(`unhandled add kind ${kind}`);
+      return 1;
+  }
+}
+var NEW_FRAMEWORKS = ["react", "vue", "solid", "svelte", "node"];
+async function runCreate(ctx) {
+  let dirName = ctx.args._[1] ?? flag(ctx.args, "dir");
+  if (!dirName) dirName = await ctx.io.ask("project directory:", "my-atoll-app");
+  if (!validName(dirName)) {
+    ctx.io.error(`invalid directory name ${ctx.io.fmt.accent(dirName)}`);
+    return 1;
+  }
+  const fwFlag = flag(ctx.args, "framework");
+  const fw = fwFlag ?? await ctx.io.select("framework:", NEW_FRAMEWORKS, "react");
+  if (fw === "angular") {
+    ctx.io.error("angular apps scaffold through the CLI: `ng new <name>`, then `atoll init` + `atoll add island`");
+    return 1;
+  }
+  if (!NEW_FRAMEWORKS.includes(fw)) {
+    ctx.io.error(`unknown framework "${fw}" \u2014 pick from ${NEW_FRAMEWORKS.join(", ")}`);
+    return 1;
+  }
+  const target = join3(ctx.cwd, dirName);
+  if (existsSync3(target) && readdirSync(target).length > 0) {
+    ctx.io.error(`${dirName}/ exists and is not empty`);
+    return 1;
+  }
+  mkdirSync2(target, { recursive: true });
+  const files = fw === "node" ? nodeScaffoldFiles(dirName) : scaffoldFiles(dirName, fw);
+  await writeTree(ctx.io, target, files, { force: true });
+  const written = JSON.parse(readFileSync2(join3(target, "package.json"), "utf8"));
+  const allDeps = [
+    ...Object.keys(written.dependencies ?? {}),
+    ...Object.keys(written.devDependencies ?? {})
+  ];
+  const pm = flag(ctx.args, "pm") ?? "npm";
+  await offerInstall(
+    { ...ctx, cwd: target },
+    { root: target, pkg: {}, framework: "vanilla", pm, srcDir: target },
+    allDeps,
+    true
+    // fresh scaffold — the deps are declared, nothing is installed yet
+  );
+  ctx.io.print("");
+  ctx.io.print(`done \u2014 ${ctx.io.fmt.accent(`cd ${dirName} && ${pm} run dev`)}`);
+  return 0;
+}
+function runDoctor(ctx) {
+  const project = detectProject(ctx.cwd);
+  const fix = hasFlag(ctx.args, "fix");
+  const checks = [
+    {
+      label: "node >= 22.18 (type-stripped CLI) / >= 20 (runtime)",
+      run: () => {
+        const [maj, min] = process.versions.node.split(".").map(Number);
+        return maj > 22 || maj === 22 && min >= 18 ? { level: "pass", detail: `v${process.versions.node}` } : maj >= 20 ? { level: "warn", detail: `v${process.versions.node} \u2014 runtime OK; the CLI bin needs >=22.18` } : { level: "fail", detail: `v${process.versions.node}` };
+      }
+    },
+    {
+      label: "package.json",
+      run: () => project.pkg ? { level: "pass", detail: `${project.root}/package.json` } : { level: "fail", detail: "not found \u2014 run `atoll new` or cd into a project" }
+    },
+    {
+      label: "@atolljs/* dependencies",
+      run: () => {
+        const deps = { ...project.pkg?.dependencies, ...project.pkg?.devDependencies };
+        const found = Object.keys(deps).filter((d) => d.startsWith("@atolljs/"));
+        return found.length ? { level: "pass", detail: found.join(", ") } : { level: "warn", detail: "none \u2014 `atoll init` installs what the framework needs" };
+      }
+    },
+    {
+      label: ".npmrc supply-chain policy (min-release-age)",
+      run: () => {
+        const p = join3(project.root ?? ctx.cwd, ".npmrc");
+        const has = existsSync3(p) && readFileSync2(p, "utf8").includes("min-release-age");
+        if (has) return { level: "pass" };
+        if (fix) {
+          writeFileSync2(p, NPMRC);
+          return { level: "pass", detail: "written (--fix)" };
+        }
+        return { level: "warn", detail: "missing \u2014 `atoll doctor --fix` writes the hardened .npmrc" };
+      }
+    },
+    {
+      label: "lockfile present",
+      run: () => existsSync3(join3(project.root ?? ctx.cwd, "package-lock.json")) || existsSync3(join3(project.root ?? ctx.cwd, "pnpm-lock.yaml")) || existsSync3(join3(project.root ?? ctx.cwd, "yarn.lock")) ? { level: "pass" } : { level: "warn", detail: "no lockfile \u2014 installs are not reproducible" }
+    },
+    {
+      label: "worker entries bundler-detectable",
+      run: () => {
+        if (!project.srcDir || !existsSync3(project.srcDir)) return { level: "pass" };
+        let scanned = 0;
+        let bad = 0;
+        const walk = (d) => {
+          for (const e of readdirSync(d, { withFileTypes: true })) {
+            const p = join3(d, e.name);
+            if (e.isDirectory() && e.name !== "node_modules") walk(p);
+            else if (/\.(ts|tsx|js|mjs)$/.test(e.name)) {
+              scanned++;
+              const src = readFileSync2(p, "utf8");
+              const entries = src.match(/new Worker\s*\(/g) ?? [];
+              const detectable = src.match(/new Worker\s*\(\s*new URL\s*\(/g) ?? [];
+              bad += entries.length - detectable.length;
+            }
+          }
+        };
+        walk(project.srcDir);
+        return bad ? { level: "fail", detail: `${bad} new Worker() call(s) without \`new URL(..., import.meta.url)\` \u2014 bundlers can't see them` } : { level: "pass", detail: `${scanned} files scanned` };
+      }
+    },
+    {
+      label: "COOP/COEP headers (SharedArrayBuffer gate)",
+      run: () => {
+        if (NODE_HOSTS.includes(project.framework)) {
+          return { level: "pass", detail: "n/a \u2014 node runtime" };
+        }
+        const vite = ["vite.config.ts", "vite.config.js", "vite.config.mts"].map((f) => join3(project.root ?? ctx.cwd, f)).find(existsSync3);
+        if (!vite) return { level: "warn", detail: "no vite config found \u2014 verify headers on your server" };
+        const src = readFileSync2(vite, "utf8");
+        return src.includes("Cross-Origin-Opener-Policy") && src.includes("Cross-Origin-Embedder-Policy") ? { level: "pass" } : { level: "warn", detail: `${vite.split(/[\\/]/).pop()} lacks COOP/COEP \u2014 shared memory will be gated in dev` };
+      }
+    }
+  ];
+  let fails = 0;
+  for (const c of checks) {
+    const r = c.run();
+    const mark = r.level === "pass" ? "ok" : r.level === "warn" ? "warn" : "error";
+    ctx.io[mark](`${c.label}${r.detail ? ctx.io.fmt.dim(` \u2014 ${r.detail}`) : ""}`);
+    if (r.level === "fail") fails++;
+  }
+  return fails ? 1 : 0;
+}
+
+// src/cli.ts
+var HELP = (fmt) => `${fmt.strong("atoll")} \u2014 bootstrap multithreading ${fmt.dim("(experimental)")}
+
+  ${fmt.accent("atoll new <dir>")} [--framework react|vue|solid|svelte|node] [--pm npm]
+      Scaffold a fresh app \u2014 vite shell + a worker-rendered island,
+      or a tsx Node service with a pooled worker.
+
+  ${fmt.accent("atoll init")} [--name app] [--force]
+      Wire Atoll into the current project: hardened .npmrc, package
+      install, and a contract + worker + client spine under src/atoll/.
+
+  ${fmt.accent("atoll add [framework] <kind> [variant] [name]")}
+      worker      pool + typed client (+ framework bindings on UI projects)
+      memory      shared-memory contract
+      island      worker-rendered UI \u2014 facade (contract + lazy import) | mono
+      service     nestjs: @AtollService class facade + pool module + worker
+      method      nestjs: @AtollTask method-level offload
+      module      nestjs: registerPool boundary module + worker entry
+      housed      nestjs: route subtree served entirely inside workers
+      route       nextjs: api route pool \u2014 task | client variants
+      component   nextjs: 'use client' hooks component over a pool
+      instrumentation   nextjs: server bootstrap that warms route pools
+
+      Frameworks: react vue solid svelte angular nestjs nextjs node
+      [--dir <path>] [--memory <name>|--no-memory] [--variant <v>] [--force]
+
+  ${fmt.accent("atoll doctor")} [--fix]
+      Check the setup \u2014 deps, lockfile, .npmrc policy, bundler-detectable
+      worker entries, COOP/COEP headers. --fix writes a hardened .npmrc.
+
+  ${fmt.dim(`flags: --yes/-y accepts defaults, --force overwrites existing files,
+         --no-install skips dependency installation`)}
+`;
+var DISCLAIMER = "atoll is experimental \u2014 report bugs or feedback: https://github.com/jwhenry3/atolljs/issues";
+async function runCli(argv, io, cwd) {
+  const args = parseArgs(argv);
+  const ctx = { io, cwd, args };
+  const [cmd] = args._;
+  io.warn(io.fmt.dim(DISCLAIMER));
+  try {
+    switch (cmd) {
+      case "new":
+      case "create":
+        return await runCreate(ctx);
+      case "init":
+        return await runInit(ctx);
+      case "add":
+        return await runAdd(ctx);
+      case "doctor":
+        return runDoctor(ctx);
+      case "help":
+      case void 0:
+        io.print(HELP(io.fmt));
+        return cmd === void 0 ? 0 : 0;
+      default:
+        io.error(`unknown command ${io.fmt.accent(cmd)}`);
+        io.print(HELP(io.fmt));
+        return 1;
+    }
+  } catch (e) {
+    io.error(e instanceof Error ? e.message : String(e));
+    return 1;
+  } finally {
+    io.close();
+  }
+}
+var invokedAs = process.argv[1] && import.meta.url.endsWith(process.argv[1].replaceAll("\\", "/"));
+if (invokedAs) {
+  const args = parseArgs(process.argv.slice(2));
+  const interactive = process.stdin.isTTY === true && !hasFlag(args, "yes", "y");
+  const code = await runCli(process.argv.slice(2), consoleIo(interactive), process.cwd());
+  process.exit(code);
+}
+export {
+  runCli
+};