@webjsdev/cli 0.10.59 → 0.10.61

package/bin/webjs.js

@@ -6,10 +6,10 @@ import { fileURLToPath } from 'node:url';
 import { resolveBin } from '../lib/resolve-bin.js';
 import { dbGenerateTtyHint } from '../lib/db-hints.js';
 import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
-import { loadAppEnv, resolvePort } from '../lib/port.js';
+import { loadAppEnv, resolvePort, failFastOnPortInUse } from '../lib/port.js';
 import { planDevSupervisor } from '../lib/dev-supervisor.js';
 import { checkAppName, appNameErrorMessage } from '../lib/app-name.js';
-import { findCheckTarget, notAnAppMessage, notAnAppJson } from '../lib/check-target.js';
+import { findCheckTarget, notAnAppMessage, notAnAppJson, findServeTarget, notAnAppServeMessage } from '../lib/check-target.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
@@ -147,7 +147,7 @@ const USAGE = `webjs commands:
 const HELP = {
   dev: {
     usage: 'webjs dev [--port <n>] [--no-hot]',
-    summary: 'Start the dev server with live reload (source is the runtime, no build step).',
+    summary: 'Start the dev server with live reload (source is the runtime, no build step). Run it in the app directory (the one holding app/); anywhere else it exits 1 naming the app to start.',
     options: [
       { flag: '--port <n>', description: 'Port to listen on (else PORT, else 8080).' },
       { flag: '--no-hot', description: 'Run in-process, without the hot-reload supervisor.' },
@@ -156,7 +156,7 @@ const HELP = {
   },
   start: {
     usage: 'webjs start [--port <n>]',
-    summary: 'Start the production server (serves source directly, plain HTTP/1.1).',
+    summary: 'Start the production server (serves source directly, plain HTTP/1.1). Exits 1 outside an app directory.',
     options: [
       { flag: '--port <n>', description: 'Port to listen on (else PORT, else 8080).' },
     ],
@@ -442,6 +442,19 @@ async function startDevParallelTasks(commands, cwd) {
   });
 }
 
+/**
+ * Exit 1 with a clear message when `webjs dev` / `webjs start` runs where there
+ * is no `app/` directory (#1526), naming the app to start instead.
+ *
+ * @param {'dev' | 'start'} command
+ */
+async function refuseOutsideApp(command) {
+  const target = await findServeTarget(process.cwd());
+  if (target.isApp) return;
+  console.error(notAnAppServeMessage(command, process.cwd(), target));
+  process.exit(1);
+}
+
 async function main() {
   // `--version` / `-v` (top level): print the installed CLI version and exit.
   if (cmd === '--version' || cmd === '-v') {
@@ -480,6 +493,15 @@ async function main() {
   // `ERR_MODULE_NOT_FOUND: Cannot find package '@webjsdev/core'`. Probe up front
   // and surface the cause + remedy instead. No-op (a cheap resolve) when the
   // framework resolves, so the happy-path boot is untouched.
+  // #1526: refuse to serve a directory that is not an app, FIRST: before the
+  // resolve probe (whose "run npm install" advice is wrong at a workspace
+  // root), any before-step (a `webjs db migrate` in the wrong directory), or a
+  // spawn. Started from a workspace root, the server used to boot, say it was
+  // ready, and answer 404 for every route. The dev child skips it: its parent
+  // checked the same cwd it spawned the child in.
+  if ((cmd === 'dev' || cmd === 'start') && process.env.__WEBJS_DEV_CHILD !== '1') {
+    await refuseOutsideApp(cmd);
+  }
   if (cmd === 'dev' || cmd === 'start') {
     const { checkFrameworkResolves } = await import('../lib/doctor.js');
     const probe = checkFrameworkResolves(process.cwd());
@@ -500,7 +522,15 @@ async function main() {
         // too, but that runs too late to affect the port the CLI computes.
         loadAppEnv(process.cwd());
         const port = resolvePort(flag(rest, '--port'));
-        await startServer({ appDir: process.cwd(), port, dev: true });
+        // Exit with the supervisor (#1521): when its IPC channel closes, the
+        // parent is gone (killed outright, or crashed), and a child left
+        // running would hold the port against the next `webjs dev`. Unref'd
+        // so the channel itself never keeps this process alive.
+        if (process.connected) {
+          process.channel?.unref?.();
+          process.on('disconnect', () => process.exit(0));
+        }
+        await failFastOnPortInUse(startServer({ appDir: process.cwd(), port, dev: true }));
         break;
       }
 
@@ -520,36 +550,38 @@ async function main() {
       loadAppEnv(process.cwd());
       await runPhaseBeforeSteps('dev', devTasks.dev.before, process.cwd());
       const killTasks = await startDevParallelTasks(devTasks.dev.parallel, process.cwd());
-      process.on('SIGINT', () => { killTasks(); process.exit(0); });
-      process.on('SIGTERM', () => { killTasks(); process.exit(0); });
 
-      // Decide how to run: in-process (`--no-hot`), or re-exec'd under the host
-      // runtime's hot-reload supervisor (`node --watch` on Node, `bun --hot` on
-      // Bun, #514). The branch logic lives in the pure `planDevSupervisor` so it
-      // is unit-testable without spawning a process.
-      const { existsSync } = await import('node:fs');
+      // Decide how to run: in-process (`--no-hot`), or in a child under WebJs's
+      // reload supervisor (#1521), which restarts it on a change on Node and
+      // runs it under `bun --hot` on Bun (#514), and brings a crashed child
+      // back on either. The branch logic lives in the pure `planDevSupervisor`
+      // so it is unit-testable without spawning a process.
       const plan = planDevSupervisor({
         isBun: !!process.versions.bun,
         argv: process.argv.slice(1),
         noHot: rest.includes('--no-hot'),
-        exists: (p) => existsSync(p),
       });
 
       if (plan.mode === 'inline') {
+        process.on('SIGINT', () => { killTasks(); process.exit(0); });
+        process.on('SIGTERM', () => { killTasks(); process.exit(0); });
         const { startServer } = await import('@webjsdev/server');
         loadAppEnv(process.cwd());
         const port = resolvePort(flag(rest, '--port'));
-        await startServer({ appDir: process.cwd(), port, dev: true });
+        await failFastOnPortInUse(startServer({ appDir: process.cwd(), port, dev: true }), {
+          exit: (code) => { killTasks(); process.exit(code); },
+        });
         killTasks();
         break;
       }
 
-      const child = spawn(process.execPath, plan.args, {
-        stdio: 'inherit',
+      const { superviseDevServer } = await import('../lib/dev-reload.js');
+      superviseDevServer({
         cwd: process.cwd(),
+        plan,
         env: { ...process.env, __WEBJS_DEV_CHILD: '1' },
+        onExit: (code) => { killTasks(); process.exit(code); },
       });
-      child.on('exit', (code) => { killTasks(); process.exit(code ?? 0); });
       break;
     }
     case 'start': {
@@ -563,7 +595,7 @@ async function main() {
       const { readAppTasks } = await import('../lib/app-tasks.js');
       await runPhaseBeforeSteps('start', readAppTasks(process.cwd()).start.before, process.cwd());
       const port = resolvePort(flag(rest, '--port'));
-      await startServer({ appDir: process.cwd(), port, dev: false });
+      await failFastOnPortInUse(startServer({ appDir: process.cwd(), port, dev: false }));
       break;
     }
     case 'db': {

package/lib/check-target.js

@@ -24,7 +24,7 @@
 
 import { statSync } from 'node:fs';
 import { readFile, glob } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, dirname, relative } from 'node:path';
 
 /**
  * @typedef {{ isApp: boolean, workspaceApps: string[] }} CheckTarget
@@ -96,6 +96,71 @@ export async function workspaceApps(cwd) {
   return [...apps].sort();
 }
 
+/**
+ * The nearest STRICT ancestor of `cwd` that holds an `app/` directory, or
+ * `null`. Started from inside an app (its `app/` or `components/` dir), this is
+ * the app the user meant.
+ *
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function findAncestorApp(cwd) {
+  let dir = dirname(cwd);
+  for (;;) {
+    if (hasAppDir(dir)) return dir;
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+/**
+ * Where a server command (`webjs dev` / `webjs start`) that was started outside
+ * an app should have been started (#1526): the workspace's member apps when
+ * `cwd` is a workspace root, else the nearest ancestor app, else nothing.
+ * `isApp` is the same `app/` predicate `webjs check` refuses on (#1301).
+ *
+ * @param {string} cwd
+ * @returns {Promise<{ isApp: boolean, workspaceApps: string[], ancestorApp: string | null }>}
+ */
+export async function findServeTarget(cwd) {
+  const target = await findCheckTarget(cwd);
+  if (target.isApp) return { ...target, ancestorApp: null };
+  return { ...target, ancestorApp: target.workspaceApps.length ? null : findAncestorApp(cwd) };
+}
+
+/**
+ * The refusal `webjs dev` / `webjs start` print when started where there is no
+ * app (#1526). Without it the server boots, says it is ready, and answers 404
+ * for every route, which is how a launch from a workspace root used to look.
+ *
+ * @param {'dev' | 'start'} command
+ * @param {string} cwd
+ * @param {{ workspaceApps: string[], ancestorApp: string | null }} target
+ * @returns {string}
+ */
+export function notAnAppServeMessage(command, cwd, { workspaceApps, ancestorApp }) {
+  const lines = [
+    `webjs ${command}: this directory is not a WebJs app, so there is nothing to serve.`,
+    '',
+    `  ${cwd}`,
+    '',
+    'There is no `app/` directory here. Started anyway, the server would answer',
+    '404 for every route.',
+    '',
+  ];
+  if (workspaceApps.length) {
+    lines.push('This is a workspace root. Start the server inside the app:', '');
+    for (const app of workspaceApps) lines.push(`  cd ${app} && webjs ${command}`);
+  } else if (ancestorApp) {
+    lines.push('This directory is inside an app. Start the server from the app root:', '');
+    lines.push(`  cd ${relative(cwd, ancestorApp) || '.'} && webjs ${command}`);
+  } else {
+    lines.push('Change into your app directory (the one holding `app/`) and re-run.');
+  }
+  return lines.join('\n');
+}
+
 /**
  * The human refusal, for stderr.
  *

package/lib/create.js

@@ -17,7 +17,7 @@ import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
-import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
+import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi, bunifyEnvExample } from './runtime-rewrite.js';
 import { postgresCompose, postgresCi } from './db-rewrite.js';
 import { assertValidAppName, toDatabaseName } from './app-name.js';
 import { isGalleryAppShellFile } from './gallery-shell-files.js';
@@ -745,6 +745,9 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'AGENTS.md', 'CLAUDE.md', 'CONVENTIONS.md',
     '.agents/rules/workflow.md',
     'test/hello/browser/hello.test.js', 'test/hello/e2e/hello.test.ts',
+    // Comments that name a command (#1527): `npm run ci` in the hook, the
+    // Tailwind build note in the ignore file.
+    '.hooks/pre-commit', 'gitignore',
   ]);
   // compose.yaml builds from the (pure oven/bun) Dockerfile and inherits its
   // `bun --bun run start` CMD; only its healthcheck needs switching off node
@@ -753,6 +756,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'Dockerfile': bunifyDockerfile,
     'compose.yaml': bunifyCompose,
     '.github/workflows/ci.yml': bunifyCi,
+    '.env.example': bunifyEnvExample,
   };
   // Database axis (#1490): the compose + CI templates are the SQLite shape, so
   // a --db postgres app derives its variant (a Postgres service, DATABASE_URL
@@ -1240,7 +1244,13 @@ export type ActionResult<T> =
     const clearScriptSrc = join(TEMPLATES, 'scripts', 'clear-gallery.mjs');
     if (existsSync(clearScriptSrc)) {
       await mkdir(join(appDir, 'scripts'), { recursive: true });
-      await cp(clearScriptSrc, join(appDir, 'scripts', 'clear-gallery.mjs'));
+      // A Bun app gets the Bun spelling of the ui-kit command the script
+      // prints and writes into the reset layout (#1527): `bunx`, never `npx`.
+      const clearScript = await readFile(clearScriptSrc, 'utf8');
+      await writeFile(
+        join(appDir, 'scripts', 'clear-gallery.mjs'),
+        isBun ? clearScript.replaceAll('npx webjsdev ', 'bunx webjsdev ') : clearScript,
+      );
     }
 
     // Fail loudly if the @webjsdev/ui registry sources aren't on disk.
@@ -1746,10 +1756,12 @@ ThemeToggle.register('theme-toggle');
   // single-bin fallback resolves it to the `webjs` binary, so behaviour
   // matches `@webjsdev/cli` exactly while keeping the command short
   // and unambiguous.
+  // A Bun app runs one-off binaries with `bunx` (#1527).
+  const x = isBun ? 'bunx' : 'npx';
   const uiNote = isApi
     ? `# If you later add a UI to this API project:
-  #   npx webjsdev ui init && npx webjsdev ui add button card dialog`
-    : `npx webjsdev ui add <name>     # add more ui-* components later`;
+  #   ${x} webjsdev ui init && ${x} webjsdev ui add button card dialog`
+    : `${x} webjsdev ui add <name>     # add more ui-* components later`;
   console.log(`
 Next steps:
   ${runCommand}

package/lib/dev-reload.js

@@ -0,0 +1,406 @@
+/**
+ * The `webjs dev` reload supervisor (#1521): runs the dev server in a child
+ * process, restarts it when a watched file changes, and brings it back when it
+ * crashes. Replaces `node --watch`, which crashed on the first watcher error it
+ * could not handle (an EACCES on another user's `sed -i` temp file, a file that
+ * vanished between the directory event and the watch call) and left the
+ * preview dead until someone restarted `webjs dev` by hand.
+ *
+ * Three pieces, each testable on its own:
+ * - `watchRestartPaths` watches the planned dirs recursively and the planned
+ *   root files, handles every watcher error with a warning, and follows a
+ *   watched dir that is created or removed after start.
+ * - `createSupervisor` is the restart state machine. It takes injected spawn
+ *   and timer functions, so its behaviour is tested without a process.
+ * - `superviseDevServer` wires both to a real child, the signals, and a
+ *   last-resort `uncaughtException` guard that swallows only watcher errors.
+ *
+ * The planning (which runtime, which paths, restart on change or only on a
+ * crash) stays in `dev-supervisor.js`.
+ */
+import { spawn } from 'node:child_process';
+import { watch, statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { watchRecursive } from './watch-recursive.js';
+import { PORT_IN_USE_EXIT_CODE } from './port.js';
+
+/**
+ * Quiet window between a file event and the restart. `node --watch` used
+ * 200ms; one editor save or `sed -i` lands its events within a few ms of each
+ * other, so 50ms still coalesces a save while starting the restart 150ms
+ * sooner.
+ */
+export const RESTART_DEBOUNCE_MS = 50;
+
+/**
+ * Delays before restarting a child that exited on its own (a crash), indexed
+ * by consecutive crash count and capped at the last entry. A file change
+ * restarts it at once regardless, so the backoff only matters when nothing is
+ * being edited: the preview comes back within seconds, and a child that fails
+ * deterministically at boot is retried every 10s instead of in a tight loop.
+ */
+export const CRASH_BACKOFF_MS = [500, 1000, 2000, 5000, 10000];
+
+/** A child that stayed up this long resets the crash backoff. */
+export const STABLE_MS = 10_000;
+
+/**
+ * How long a restarting child gets to exit after SIGTERM before SIGKILL. The
+ * server's own drain allows 10s, which is right for a deploy and far too long
+ * to hold an edit back in dev.
+ */
+export const KILL_TIMEOUT_MS = 2000;
+
+/**
+ * Paths inside a watched dir whose changes never restart the server: the same
+ * noise the server's in-process watcher ignores (`shouldIgnoreWatchPath` in
+ * `@webjsdev/server`), restated here so the CLI does not depend on a server
+ * internal.
+ *
+ * @param {string} rel  path relative to the app root
+ * @returns {boolean}
+ */
+export function shouldIgnoreRestartPath(rel) {
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(rel || '');
+}
+
+/**
+ * Whether an error came from a file watcher. Node marks every `fs.watch`
+ * failure with `syscall: 'watch'`.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isWatchError(err) {
+  return !!err && typeof err === 'object' && /** @type {any} */ (err).syscall === 'watch';
+}
+
+/**
+ * The `webjs.dev.regenerate[].output` paths (#967), normalized to `/` with no
+ * leading `./`. The server writes these on request, so one that lives under a
+ * watched dir must not restart the server, or a request would restart the
+ * process that is serving it. Unreadable config yields no outputs.
+ *
+ * @param {string} cwd
+ * @returns {Set<string>}
+ */
+export function readRegenerateOutputs(cwd) {
+  const out = new Set();
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    const rules = pkg && pkg.webjs && pkg.webjs.dev && pkg.webjs.dev.regenerate;
+    if (Array.isArray(rules)) {
+      for (const r of rules) {
+        if (r && typeof r.output === 'string') out.add(r.output.replace(/\\/g, '/').replace(/^\.\//, ''));
+      }
+    }
+  } catch {}
+  return out;
+}
+
+/**
+ * Watch the restart paths of an app. Each dir in `dirs` is watched
+ * recursively; the app root is watched non-recursively, which catches an edit
+ * to a root file in `files` and a dir in `dirs` appearing or disappearing.
+ * Every watcher error goes to `onError` and never throws.
+ *
+ * @param {string} cwd  the app root
+ * @param {{
+ *   dirs: string[],
+ *   files: string[],
+ *   ignore: (rel: string) => boolean,
+ *   onChange: (rel: string) => void,
+ *   onError: (err: NodeJS.ErrnoException) => void,
+ *   watchFn?: typeof watch,
+ * }} opts
+ * @returns {() => void} closes every watcher
+ */
+export function watchRestartPaths(cwd, { dirs, files, ignore, onChange, onError, watchFn = watch }) {
+  /** @type {Map<string, import('node:fs').FSWatcher>} */
+  const watchers = new Map();
+  let closed = false;
+  const isDir = (name) => {
+    try { return statSync(join(cwd, name)).isDirectory(); } catch { return false; }
+  };
+  const guard = (w) => {
+    w.on('error', (err) => onError(err));
+    return w;
+  };
+  const watchDir = (name) => {
+    if (closed || watchers.has(name) || !isDir(name)) return;
+    try {
+      // `watchRecursive` (#1529): on Linux under Node a per-directory walker,
+      // since Node 24's recursive watcher goes deaf to a file once it is
+      // replaced (`sed -i`, an editor's atomic save), so a second edit to the
+      // same file never restarted the server.
+      watchers.set(name, guard(watchRecursive(join(cwd, name), (_type, filename) => {
+        const rel = filename ? join(name, String(filename)) : name;
+        if (!ignore(rel)) onChange(rel);
+      }, { ignore: (rel) => ignore(join(name, rel)), watchFn })));
+    } catch (err) {
+      onError(/** @type {NodeJS.ErrnoException} */ (err));
+    }
+  };
+  const unwatchDir = (name) => {
+    const w = watchers.get(name);
+    if (!w) return;
+    try { w.close(); } catch {}
+    watchers.delete(name);
+  };
+
+  /** @type {import('node:fs').FSWatcher | null} */
+  let root = null;
+  try {
+    root = guard(watchFn(cwd, (_type, filename) => {
+      const name = filename ? String(filename) : '';
+      if (dirs.includes(name)) {
+        // A watched dir was created, replaced, or removed.
+        if (isDir(name)) watchDir(name); else unwatchDir(name);
+        onChange(name);
+      } else if (files.includes(name)) {
+        onChange(name);
+      }
+    }));
+  } catch (err) {
+    onError(/** @type {NodeJS.ErrnoException} */ (err));
+  }
+  for (const d of dirs) watchDir(d);
+
+  return () => {
+    closed = true;
+    try { root?.close(); } catch {}
+    for (const name of [...watchers.keys()]) unwatchDir(name);
+  };
+}
+
+/**
+ * @typedef {{
+ *   pid?: number,
+ *   kill: (signal?: NodeJS.Signals) => boolean | void,
+ *   once: (event: 'exit', fn: (code: number | null, signal: NodeJS.Signals | null) => void) => unknown,
+ * }} ChildLike
+ */
+
+/**
+ * The restart state machine.
+ *
+ * - `change(path)` (debounced): restart a running child when `restartOnChange`
+ *   (Node), or start a child that is not running (either runtime, after a
+ *   crash).
+ * - A restart sends SIGTERM, escalates to SIGKILL after `killTimeoutMs`, and
+ *   spawns the replacement the moment the old child exits, never on a poll.
+ * - A child that exits on its own is restarted after the crash backoff, or at
+ *   once on the next change.
+ * - `stop()` stops everything and resolves once no child is left.
+ *
+ * @param {{
+ *   spawnChild: () => ChildLike,
+ *   restartOnChange: boolean,
+ *   log?: (line: string) => void,
+ *   timers?: { setTimeout: typeof setTimeout, clearTimeout: typeof clearTimeout },
+ *   now?: () => number,
+ *   debounceMs?: number,
+ *   backoffMs?: number[],
+ *   stableMs?: number,
+ *   killTimeoutMs?: number,
+ *   finalExitCodes?: number[],
+ *   onFinal?: (code: number) => void,
+ * }} opts
+ */
+export function createSupervisor({
+  spawnChild,
+  restartOnChange,
+  log = () => {},
+  timers = globalThis,
+  now = Date.now,
+  debounceMs = RESTART_DEBOUNCE_MS,
+  backoffMs = CRASH_BACKOFF_MS,
+  stableMs = STABLE_MS,
+  killTimeoutMs = KILL_TIMEOUT_MS,
+  // Exit codes a restart cannot fix (a taken port, #1527): the supervisor
+  // stops and reports instead of retrying on its backoff forever.
+  finalExitCodes = [PORT_IN_USE_EXIT_CODE],
+  onFinal = () => {},
+}) {
+  /** @type {ChildLike | null} */
+  let child = null;
+  let startedAt = 0;
+  let restarting = false;
+  let stopping = false;
+  let crashes = 0;
+  /** @type {string | null} */
+  let pendingPath = null;
+  /** @type {any} */ let debounceTimer = null;
+  /** @type {any} */ let backoffTimer = null;
+  /** @type {any} */ let killTimer = null;
+  /** @type {Array<() => void>} */
+  const stopWaiters = [];
+
+  const clear = (t) => { if (t !== null) timers.clearTimeout(t); return null; };
+
+  const launch = () => {
+    backoffTimer = clear(backoffTimer);
+    if (stopping || child) return;
+    const c = spawnChild();
+    child = c;
+    startedAt = now();
+    c.once('exit', (code, signal) => onExit(c, code, signal));
+  };
+
+  const terminate = (c) => {
+    try { c.kill('SIGTERM'); } catch {}
+    killTimer = clear(killTimer);
+    killTimer = timers.setTimeout(() => {
+      killTimer = null;
+      if (child === c) { try { c.kill('SIGKILL'); } catch {} }
+    }, killTimeoutMs);
+  };
+
+  const onExit = (c, code, signal) => {
+    if (child !== c) return;
+    child = null;
+    killTimer = clear(killTimer);
+    if (stopping) {
+      for (const w of stopWaiters.splice(0)) w();
+      return;
+    }
+    if (restarting) {
+      // The restart we asked for: start the replacement right away.
+      restarting = false;
+      crashes = 0;
+      launch();
+      return;
+    }
+    // Exited on its own: a crash, a fatal boot error, or an outside kill.
+    if (!signal && code !== null && finalExitCodes.includes(code)) {
+      stopping = true;
+      debounceTimer = clear(debounceTimer);
+      onFinal(code);
+      return;
+    }
+    if (now() - startedAt >= stableMs) crashes = 0;
+    const delay = backoffMs[Math.min(crashes, backoffMs.length - 1)];
+    crashes++;
+    const why = signal ? `signal ${signal}` : `code ${code}`;
+    log(`dev server exited (${why}); restarting in ${delay < 1000 ? `${delay}ms` : `${delay / 1000}s`}, or on the next file change`);
+    backoffTimer = timers.setTimeout(launch, delay);
+  };
+
+  const flush = () => {
+    debounceTimer = null;
+    const path = pendingPath;
+    pendingPath = null;
+    if (stopping) return;
+    if (!child) {
+      // Not running (crashed, or waiting out a backoff): a change is the cue.
+      if (path) log(`${path} changed, starting the dev server`);
+      launch();
+      return;
+    }
+    if (!restartOnChange || restarting) return;
+    restarting = true;
+    if (path) log(`${path} changed, restarting the dev server`);
+    terminate(child);
+  };
+
+  return {
+    start: launch,
+    /** @param {string} path */
+    change(path) {
+      if (stopping) return;
+      if (pendingPath === null) pendingPath = path;
+      debounceTimer = clear(debounceTimer);
+      debounceTimer = timers.setTimeout(flush, debounceMs);
+    },
+    /** @returns {Promise<void>} */
+    stop() {
+      stopping = true;
+      debounceTimer = clear(debounceTimer);
+      backoffTimer = clear(backoffTimer);
+      if (!child) return Promise.resolve();
+      const done = new Promise((r) => stopWaiters.push(() => r(undefined)));
+      terminate(child);
+      return done;
+    },
+    get running() { return child !== null; },
+  };
+}
+
+/**
+ * Run the dev server under the supervisor until a signal stops it.
+ *
+ * @param {{
+ *   cwd: string,
+ *   plan: { args: string[], restartOnChange: boolean, watchDirs: string[], watchFiles: string[] },
+ *   env: NodeJS.ProcessEnv,
+ *   onExit: (code: number) => void,
+ * }} opts
+ */
+export function superviseDevServer({ cwd, plan, env, onExit }) {
+  const log = (line) => console.log(`[webjs] ${line}`);
+  // A watcher error here is NOT logged: the server child watches the whole app
+  // tree (a superset of these paths) and prints one warning per unwatchable
+  // path itself, so logging it here too would print every warning twice. The
+  // watcher keeps running either way.
+  const ignoreWatchError = () => {};
+
+  let exiting = false;
+  /** @type {() => void} */
+  let closeWatch = () => {};
+  const shutdown = (code) => {
+    if (exiting) return;
+    exiting = true;
+    closeWatch();
+    sup.stop().then(() => onExit(code));
+  };
+
+  const sup = createSupervisor({
+    restartOnChange: plan.restartOnChange,
+    log,
+    // The child already printed why (the port and its holder); stop with its
+    // code rather than restarting a server that can never bind.
+    onFinal: (code) => shutdown(code),
+    spawnChild: () => {
+      const c = spawn(process.execPath, plan.args, {
+        // The IPC channel lets the child notice this process is gone and exit,
+        // so a killed supervisor never leaves an orphan holding the port.
+        stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+        cwd,
+        env,
+      });
+      // A failed spawn emits 'error' and may never emit 'exit'; report it as
+      // an exit so the backoff retries it (a repeated exit is ignored).
+      c.on('error', (err) => {
+        console.error(`[webjs] could not start the dev server: ${err.message}`);
+        c.emit('exit', 1, null);
+      });
+      return c;
+    },
+  });
+
+  const outputs = readRegenerateOutputs(cwd);
+  closeWatch = watchRestartPaths(cwd, {
+    dirs: plan.watchDirs,
+    files: plan.watchFiles,
+    ignore: (rel) => shouldIgnoreRestartPath(rel) || outputs.has(rel.replace(/\\/g, '/')),
+    onChange: (rel) => sup.change(rel),
+    onError: ignoreWatchError,
+  });
+
+  process.on('SIGINT', () => shutdown(0));
+  process.on('SIGTERM', () => shutdown(0));
+  process.on('SIGHUP', () => shutdown(0));
+  // Last resort: a watcher error that escaped every listener (a runtime that
+  // emits it somewhere else) is never fatal, and the server child reports the
+  // same path itself. Anything else is a real
+  // supervisor bug, so it is reported and the process exits non-zero after
+  // stopping the child.
+  process.on('uncaughtException', (err) => {
+    if (isWatchError(err)) return;
+    console.error(err && err.stack ? err.stack : err);
+    shutdown(1);
+  });
+
+  sup.start();
+  return sup;
+}

package/lib/dev-supervisor.js

@@ -1,29 +1,44 @@
 /**
- * Dev-server reload supervisor planning for `webjs dev` (issue #514).
+ * Dev-server reload supervisor planning for `webjs dev` (issues #514, #1521).
  *
- * `webjs dev` re-execs itself under the host runtime's hot-reload supervisor so
- * an edit to a transitively-imported module (an action, query, component, util)
- * takes effect without a manual restart. Both runtimes cache ES modules by
- * resolved URL with no public invalidation API, so the dev re-import in
- * `@webjsdev/server`'s `dev.js` relies on the runtime's own file-watching cache
- * invalidation:
+ * `webjs dev` runs its server in a CHILD process that a supervising parent
+ * restarts, so an edit to a transitively-imported module (an action, query,
+ * component, util) takes effect without a manual restart. Both runtimes cache
+ * ES modules by resolved URL with no public invalidation API, so the dev
+ * re-import in `@webjsdev/server`'s `dev.js` relies on a fresh process (Node)
+ * or the runtime's own cache invalidation (Bun):
  *
- * - **Node** has no in-place module-cache eviction, so it re-execs under
- *   `node --watch`, which RESTARTS the process on a file change (a fresh ESM
- *   cache each time). The dev re-import additionally appends a `?t=` cache-bust
- *   query that Node honours between restarts.
- * - **Bun** keys its module cache by path and IGNORES that `?t=` query, so the
- *   `node --watch` model does not transfer: without help a re-imported module
- *   stays STALE on Bun (the #514 bug). Bun's `--hot` invalidates loaded modules
- *   on a file change WITHOUT restarting the process, which is exactly what the
- *   dev re-import needs; `Bun.serve` is reused across hot reloads, so the
- *   listener is not duplicated. `--hot` auto-watches every loaded file, so the
- *   node `--watch-path` flags do not apply (and are not Bun flags).
+ * - **Node** has no in-place module-cache eviction, so the parent RESTARTS the
+ *   child on a change under the watched paths (a fresh ESM cache each time).
+ *   This used to be `node --watch`, which dies on the first watcher error it
+ *   cannot handle (an EACCES on a temp file another user created, a file that
+ *   vanished mid-scan, #1521) and takes the preview down for good. WebJs's own
+ *   supervisor (`lib/dev-reload.js`) watches the same paths with every watcher
+ *   error handled, and restarts the child faster.
+ * - **Bun** keys its module cache by path and IGNORES the `?t=` cache-bust, so
+ *   a restart-per-edit model is not needed: `bun --hot` invalidates loaded
+ *   modules on a file change WITHOUT restarting the process, and `Bun.serve` is
+ *   reused across hot reloads. The parent still supervises it, but only to
+ *   bring a CRASHED child back (`restartOnChange: false`).
+ *
+ * On both runtimes a child that exits on its own (a crash) is restarted on the
+ * next file change, and after a short backoff even with no change.
  *
  * This pure planner returns the spawn decision so the bin stays a thin shell and
  * the branch logic is unit-testable without spawning a process.
  */
 
+/** Project directories whose changes restart the dev server on Node. */
+export const WATCH_DIRS = ['app', 'components', 'modules', 'lib', 'actions'];
+
+/**
+ * Every extension the server's root-middleware lookup accepts, in the same
+ * order. If these two lists diverge, an app gets a middleware that loads but
+ * never restarts the dev server when edited, which is the quiet half of the
+ * bug where a `middleware.ts` was loaded by neither.
+ */
+export const WATCH_FILES = ['middleware.ts', 'middleware.js', 'middleware.mts', 'middleware.mjs'];
+
 /**
  * Plan how `webjs dev` runs its server.
  *
@@ -31,35 +46,21 @@
  * @param {boolean} opts.isBun  Whether the host runtime is Bun (`process.versions.bun`).
  * @param {string[]} opts.argv  `process.argv.slice(1)` (the script path followed by its args), forwarded to the child verbatim.
  * @param {boolean} opts.noHot  Whether `--no-hot` was passed (opt out of the supervisor entirely).
- * @param {(path: string) => boolean} opts.exists  Existence check for the Node `--watch-path` targets (relative to cwd). Unused on Bun.
- * @returns {{ mode: 'inline' } | { mode: 'spawn', args: string[] }}
- *   `inline` runs the server in this process (no reload watcher); `spawn`
- *   re-execs `process.execPath` with `args` and `__WEBJS_DEV_CHILD=1`.
+ * @returns {{ mode: 'inline' } | { mode: 'supervise', args: string[], restartOnChange: boolean, watchDirs: string[], watchFiles: string[] }}
+ *   `inline` runs the server in this process (no reload watcher); `supervise`
+ *   spawns `process.execPath` with `args` and `__WEBJS_DEV_CHILD=1` under the
+ *   supervisor, which watches `watchDirs` (recursively) and `watchFiles` (at
+ *   the app root). The directories need not exist yet: one created later is
+ *   picked up.
  */
-export function planDevSupervisor({ isBun, argv, noHot, exists }) {
+export function planDevSupervisor({ isBun, argv, noHot }) {
   // `--no-hot` opts out of the reload supervisor on either runtime: run the dev
   // server in THIS process with no watcher. Degraded dev (a deep-import edit
   // needs a manual restart) but useful under an external process manager or a
   // debugger that wants a single, un-re-exec'd process.
   if (noHot) return { mode: 'inline' };
 
-  if (isBun) return { mode: 'spawn', args: ['--hot', ...argv] };
-
-  // Node: re-exec under `node --watch`, watching the project dirs/files that
-  // exist. `--watch-preserve-output` keeps prior logs across a restart.
-  const watchPaths = [];
-  for (const dir of ['app', 'components', 'modules', 'lib', 'actions']) {
-    if (exists(dir)) watchPaths.push('--watch-path', dir);
-  }
-  // Every extension the server's root-middleware lookup accepts, in the same
-  // order. If these two lists diverge, an app gets a middleware that loads but
-  // never restarts the dev server when edited, which is the quiet half of the
-  // bug where a `middleware.ts` was loaded by neither.
-  for (const f of ['middleware.ts', 'middleware.js', 'middleware.mts', 'middleware.mjs']) {
-    if (exists(f)) watchPaths.push('--watch-path', f);
-  }
-  return {
-    mode: 'spawn',
-    args: ['--watch', '--watch-preserve-output', ...watchPaths, ...argv],
-  };
+  const watch = { watchDirs: [...WATCH_DIRS], watchFiles: [...WATCH_FILES] };
+  if (isBun) return { mode: 'supervise', args: ['--hot', ...argv], restartOnChange: false, ...watch };
+  return { mode: 'supervise', args: [...argv], restartOnChange: true, ...watch };
 }

package/lib/port.js

@@ -58,3 +58,35 @@ export function resolvePort(portFlag, env = process.env) {
   if (env.PORT) return Number(env.PORT);
   return 8080;
 }
+
+/**
+ * The exit code of a server that could not bind because its port is taken
+ * (#1527): Linux's EADDRINUSE errno. The dev supervisor treats it as final and
+ * stops instead of restarting a child that can never bind.
+ */
+export const PORT_IN_USE_EXIT_CODE = 98;
+
+/**
+ * Await a server start; on a taken port print the server's message (it names
+ * the process holding the port) and exit with `PORT_IN_USE_EXIT_CODE`. Any
+ * other error propagates unchanged.
+ *
+ * @template T
+ * @param {Promise<T>} started
+ * @param {{ error?: (line: string) => void, exit?: (code: number) => never }} [io]
+ * @returns {Promise<T>}
+ */
+export async function failFastOnPortInUse(started, io = {}) {
+  const error = io.error || ((line) => console.error(line));
+  const exit = io.exit || ((code) => process.exit(code));
+  try {
+    return await started;
+  } catch (e) {
+    const err = /** @type {any} */ (e);
+    if (err && err.code === 'EADDRINUSE') {
+      error(`[webjs] ${err.message || 'the port is already in use'}`);
+      return exit(PORT_IN_USE_EXIT_CODE);
+    }
+    throw e;
+  }
+}

package/lib/runtime-rewrite.js

@@ -161,7 +161,22 @@ export function bunifyDockerfile(s) {
  * @returns {string}
  */
 export function bunifyCompose(s) {
-  return s.replace('test: ["CMD", "node", "-e", "fetch(', 'test: ["CMD", "bun", "-e", "fetch(');
+  return s
+    .replace('test: ["CMD", "node", "-e", "fetch(', 'test: ["CMD", "bun", "-e", "fetch(')
+    // The secret-generation hint (#1527): a Bun app may have no node at all.
+    .replaceAll('# Generate: node -e ', '# Generate: bun -e ');
+}
+
+/**
+ * Rewrite `.env.example` for Bun (#1527): its secret-generation hint runs
+ * `node -e`, which a Bun-only machine (the oven/bun image, a Bun-only dev box)
+ * does not have. `bun -e` runs the same one-liner.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function bunifyEnvExample(s) {
+  return s.replaceAll('# Generate: node -e ', '# Generate: bun -e ');
 }
 
 /**

package/lib/watch-recursive.js

@@ -0,0 +1,147 @@
+/**
+ * A recursive directory watcher that keeps hearing a file after it is
+ * replaced (#1529).
+ *
+ * KEEP IN SYNC: `packages/cli/lib/watch-recursive.js` and
+ * `packages/server/src/dev/watch-recursive.js` are byte-identical copies (the
+ * CLI does not depend on server internals); `packages/cli/test/dev-supervisor/
+ * watch-recursive.test.js` fails when they drift.
+ *
+ * Node 24's `fs.watch(dir, { recursive: true })` on Linux is implemented in JS
+ * (`internal/fs/recursive_watch`) with one inotify watch per FILE plus a map of
+ * the files it knows. `sed -i`, an editor's save through a temp file, and every
+ * atomic write REPLACE the file (a new inode renamed over the old name). The
+ * per-file watch dies with the old inode, and the new file is never watched
+ * again because its name is already in the map, so every later edit to that
+ * file is silent: no dev restart, no live reload. Node 26 fixed it, but WebJs
+ * supports Node 24.
+ *
+ * A plain `fs.watch` on a DIRECTORY reports a replaced child by name on every
+ * Node version, so on Linux under Node this watches each directory
+ * non-recursively (one inotify watch per directory, fewer than one per file),
+ * adds a watcher when a subdirectory appears, and drops one when it goes away.
+ * Everywhere else the native recursive watcher is used unchanged: macOS and
+ * Windows have a kernel-level recursive watch, and Bun's `bun --hot` reloads
+ * edits itself.
+ *
+ * @module watch-recursive
+ */
+import { watch, readdirSync, realpathSync, statSync } from 'node:fs';
+import { EventEmitter } from 'node:events';
+import { join, sep } from 'node:path';
+
+/**
+ * Whether this runtime needs the per-directory walker rather than the native
+ * recursive watcher.
+ *
+ * @param {{ platform?: string, isBun?: boolean }} [env]
+ * @returns {boolean}
+ */
+export function needsDirWalker({ platform = process.platform, isBun = !!process.versions.bun } = {}) {
+  return platform === 'linux' && !isBun;
+}
+
+/**
+ * Watch `dir` and everything under it. The listener gets `(eventType,
+ * filename)` with `filename` relative to `dir`, like the native recursive
+ * watcher. The returned watcher emits `'error'` for any watch or scan failure
+ * (never throws for one) and has `close()`.
+ *
+ * @param {string} dir
+ * @param {(eventType: string, filename: string | null) => void} listener
+ * @param {{
+ *   ignore?: (relPath: string) => boolean,
+ *   watchFn?: typeof watch,
+ *   walker?: boolean,
+ * }} [opts]  `ignore` skips a subdirectory (never walked, never watched) and
+ *   its events; `watchFn` is injectable for tests; `walker` forces the mode.
+ * @returns {import('node:events').EventEmitter & { close: () => void }}
+ */
+export function watchRecursive(dir, listener, opts = {}) {
+  const { ignore = () => false, watchFn = watch, walker = needsDirWalker() } = opts;
+  if (!walker) return /** @type {any} */ (watchFn(dir, { recursive: true }, listener));
+
+  const out = /** @type {EventEmitter & { close: () => void }} */ (new EventEmitter());
+  /** @type {Map<string, import('node:fs').FSWatcher>} rel dir -> watcher */
+  const watchers = new Map();
+  /** @type {Map<string, string>} real path -> rel dir (a symlink loop guard) */
+  const reals = new Map();
+  let closed = false;
+  // Errors from the initial walk happen before the caller can attach an
+  // 'error' listener, so they are held and emitted on the next tick.
+  /** @type {unknown[] | null} */
+  let early = [];
+
+  const fail = (err) => {
+    if (closed) return;
+    if (early) early.push(err);
+    else if (out.listenerCount('error') > 0) out.emit('error', err);
+  };
+  const abs = (rel) => (rel ? join(dir, rel) : dir);
+  const isDir = (rel) => {
+    try { return statSync(abs(rel)).isDirectory(); } catch { return false; }
+  };
+  const within = (rel, root) => root === '' || rel === root || rel.startsWith(root + sep);
+
+  const drop = (root) => {
+    for (const [rel, w] of [...watchers]) {
+      if (!within(rel, root)) continue;
+      try { w.close(); } catch {}
+      watchers.delete(rel);
+    }
+    for (const [real, rel] of [...reals]) if (within(rel, root)) reals.delete(real);
+  };
+
+  const add = (rel) => {
+    if (closed || watchers.has(rel) || (rel && ignore(rel))) return;
+    let real;
+    try { real = realpathSync(abs(rel)); } catch (err) { if (!rel) fail(err); return; }
+    if (reals.has(real)) return;
+    /** @type {import('node:fs').FSWatcher} */
+    let w;
+    try {
+      w = watchFn(abs(rel), (type, name) => onEvent(rel, type, name));
+    } catch (err) {
+      fail(err);
+      return;
+    }
+    w.on('error', (err) => {
+      // A directory removed while watched errors on some kernels; that is the
+      // removal, already reported through the parent, not a failure.
+      const gone = !isDir(rel);
+      drop(rel);
+      if (!gone) fail(err);
+    });
+    watchers.set(rel, w);
+    reals.set(real, rel);
+    let entries = [];
+    try { entries = readdirSync(abs(rel), { withFileTypes: true }); } catch (err) { fail(err); }
+    for (const e of entries) {
+      const child = rel ? join(rel, e.name) : e.name;
+      if (e.isDirectory() || (e.isSymbolicLink() && isDir(child))) add(child);
+    }
+  };
+
+  const onEvent = (rel, type, name) => {
+    if (closed) return;
+    if (name == null) { listener(type, rel || null); return; }
+    const child = rel ? join(rel, String(name)) : String(name);
+    if (ignore(child)) return;
+    // A subdirectory appeared (created, or renamed into place) or went away.
+    if (isDir(child)) add(child);
+    else if (watchers.has(child)) drop(child);
+    listener(type, child);
+  };
+
+  out.close = () => {
+    closed = true;
+    drop('');
+  };
+  add('');
+  process.nextTick(() => {
+    const held = early || [];
+    early = null;
+    for (const err of held) fail(err);
+  });
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.59",
+  "version": "0.10.61",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "@webjsdev/mcp": "^0.1.0",
-    "@webjsdev/server": "^0.8.68",
+    "@webjsdev/server": "^0.8.73",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -21,13 +21,15 @@ Read this when wiring caching or rate limiting, storing uploads, hardening heade
 |---|---|
 | `REDIS_URL` | When set, sessions, rate limit, and cache use Redis instead of memory |
 | `SESSION_SECRET` / `AUTH_SECRET` | Session and auth signing (see `auth-and-sessions.md`) |
-| `PORT` | Listen port. Precedence `--port` flag, then `PORT` (real env or `.env`), then `8080` |
-| `WEBJS_SOURCE_LOCATIONS` | `webjs dev` only. `1` stamps `data-webjs-src="<app-relative-file>:<line>"` on the elements of the app's `html` templates (see below). Ignored by `webjs start` |
-| `WEBJS_EMBED_ORIGINS` | `webjs dev` only. Comma-separated parent origins (`https://builder.dev,http://localhost:8080`) allowed to frame the dev server and receive the embed bridge's messages (see below). Ignored by `webjs start` |
+| `PORT` | Listen port. Precedence `--port` flag, then `PORT` (real env or `.env`), then `8080`. A taken port fails fast: `webjs dev` / `webjs start` exit 98 with `port 8080 is already in use by PID <n> (<command>)`, on Node and Bun alike |
+| `WEBJS_REUSE_PORT` | `1` lets several `webjs dev` / `webjs start` processes share one port (`SO_REUSEPORT`, Linux; the kernel balances connections across them). Off by default, so a second server on a taken port fails instead of silently taking a share of the requests |
+| `WEBJS_SOURCE_LOCATIONS` | `webjs dev` only. `1` stamps `data-webjs-src="<app-relative-file>:<line>"` on the elements of the app's `html` templates (see below); `0` turns off a config default. Same as `webjs.dev.sourceLocations: true`. Ignored by `webjs start` |
+| `WEBJS_EMBED_ORIGINS` | `webjs dev` only. Comma-separated parent origins (`https://builder.dev,http://localhost:8080`) allowed to frame the dev server and receive the embed bridge's messages (see below). Replaces `webjs.dev.embedOrigins` when set. Ignored by `webjs start` |
+| `WEBJS_DEV_RELOAD_IDLE` | `webjs dev` only. Seconds of no edit and no interaction after which the live-reload stream closes so an idle host can sleep (`webjs.dev.reloadIdle`; this wins). Off by default; see `runtime.md` |
 
-**Source locations for tooling (`WEBJS_SOURCE_LOCATIONS=1`, dev only).** A tool that hosts the app (an inspector, click-to-edit in an embedding builder) can map a clicked element back to the line that wrote it. With the variable set, `webjs dev` adds `data-webjs-src="components/todo-list.ts:12"` to every element opening tag written in an `html` template inside the app, both in the SSR markup and in client renders (one source transform applied to the served module and to the module the server imports, so the two agree and hydration is unaffected). Read it with `el.closest('[data-webjs-src]')`. Not annotated: `*.server.*` modules, `node_modules`, `css` / `svg` tagged templates, `html` / `head` / `body` / head-only and raw-text elements, and the descendants of `svg` / `math`. Lines are exact; nothing reaches production. The importmap `<script>` in `<head>` carries an unrelated `data-webjs-src` (the app-source deploy id), so match the `file:line` value shape when querying the whole document.
+**Source locations for tooling (`webjs.dev.sourceLocations: true` or `WEBJS_SOURCE_LOCATIONS=1`, dev only, off by default).** A tool that hosts the app (an inspector, click-to-edit in an embedding builder) can map a clicked element back to the line that wrote it. With the variable set, `webjs dev` adds `data-webjs-src="components/todo-list.ts:12"` to every element opening tag written in an `html` template inside the app, both in the SSR markup and in client renders (one source transform applied to the served module and to the module the server imports, so the two agree and hydration is unaffected). Read it with `el.closest('[data-webjs-src]')`. Not annotated: `*.server.*` modules, `node_modules`, `css` / `svg` tagged templates, `html` / `head` / `body` / head-only and raw-text elements, and the descendants of `svg` / `math`. Lines are exact; nothing reaches production. The importmap `<script>` in `<head>` carries an unrelated `data-webjs-src` (the app-source deploy id), so match the `file:line` value shape when querying the whole document.
 
-**Embed bridge for iframe previews (`WEBJS_EMBED_ORIGINS`, dev only).** A tool that previews the app inside an iframe (an app builder, a docs playground) sets `WEBJS_EMBED_ORIGINS` to its own origin(s). `webjs dev` then (1) drops `X-Frame-Options` and adds those origins to a CSP `frame-ancestors`, so the frame loads without the app stripping headers in `webjs.headers`, and (2) inlines a small nonce-signed script into every document that, when framed by a listed origin, posts to `window.parent` (with that exact target origin, never `*`):
+**Embed bridge for iframe previews (`webjs.dev.embedOrigins` or `WEBJS_EMBED_ORIGINS`, dev only, off by default).** A tool that previews the app inside an iframe (an app builder, a docs playground) lists its own origin(s) in `package.json` (`"webjs": { "dev": { "embedOrigins": ["https://builder.example"] } }`) or sets `WEBJS_EMBED_ORIGINS` (comma-separated, replaces the config list for that run). `webjs dev` then (1) drops `X-Frame-Options` and adds those origins to a CSP `frame-ancestors`, so the frame loads without the app stripping headers in `webjs.headers`, and (2) inlines a small nonce-signed script into every document that, when framed by a listed origin, posts to `window.parent` (with that exact target origin, never `*`):
 
 ```js
 { source: 'webjs-embed', type: 'ready', path, title }            // document parsed
@@ -36,10 +38,11 @@ Read this when wiring caching or rate limiting, storing uploads, hardening heade
 { source: 'webjs-embed', type: 'error', message, stack, file, line, column }          // window error + unhandledrejection
 { source: 'webjs-embed', type: 'network', method, url, status, error? }               // fetch/XHR status >= 500, or status 0 on failure
 { source: 'webjs-embed', type: 'server-error', kind, message, file, line, path }      // the dev error overlay went up
-{ source: 'webjs-embed', type: 'select', src, tag, text, rect: { x, y, width, height } } // a click in inspect mode
+{ source: 'webjs-embed', type: 'select', src, tag, text, rect: { x, y, width, height }, shiftKey, metaKey, altKey, ctrlKey } // a click in inspect mode (modifiers for multi-select, #1532)
+{ source: 'webjs-embed', type: 'hold', enabled }                  // acknowledges a host hold command (#1532)
 ```
 
-and accepts, only from `window.parent` on a listed origin: `{ source: 'webjs-embed-host', type: 'navigate', path }` (a local path; a soft navigation when the client router is on), `{ source: 'webjs-embed-host', type: 'reload' }`, and `{ source: 'webjs-embed-host', type: 'inspect', enabled: true | false }` (hover highlight plus click capture that posts `select`; `src` is the nearest `data-webjs-src`, so pair it with `WEBJS_SOURCE_LOCATIONS=1` for click-to-edit). Paths are app paths (`/api/x`, `/components/x.ts`). Unset adds zero bytes; `webjs start` never injects it nor relaxes a header.
+and accepts, only from `window.parent` on a listed origin: `{ source: 'webjs-embed-host', type: 'navigate', path }` (a local path; a soft navigation when the client router is on), `{ source: 'webjs-embed-host', type: 'reload' }`, `{ source: 'webjs-embed-host', type: 'resume' }` (reopens a live-reload stream closed by `webjs.dev.reloadIdle`; every host command does this too), and `{ source: 'webjs-embed-host', type: 'inspect', enabled: true | false }` (hover highlight plus click capture that posts `select`; `src` is the nearest `data-webjs-src`, so pair it with `WEBJS_SOURCE_LOCATIONS=1` for click-to-edit), and `{ source: 'webjs-embed-host', type: 'hold', enabled: true | false }` (#1532: while held, live-reload signals are collected instead of applied, so a builder's agent can edit many files without the preview flickering through each save; releasing applies ONE reload at the strongest verdict collected, or none when nothing changed; the hold is kept in `sessionStorage`, so a new document in the same tab starts held, and only the host's release ends it). A full dev reload or a host `reload` keeps the scroll position of the path it reloads (#1532). Paths are app paths (`/api/x`, `/components/x.ts`). Unset adds zero bytes; `webjs start` never injects it nor relaxes a header.
 
 Defaults are single-instance memory stores. To scale horizontally, switch the store once at startup: `setStore(redisStore({ url: process.env.REDIS_URL }))`.
 

package/templates/.agents/skills/webjs/references/data-and-actions.md

@@ -206,7 +206,7 @@ export async function updateUser(id: number, patch: Partial<User>) { /* ... */ }
 
 ### Cancellation with `actionSignal()`
 
-Inside an action, `actionSignal()` from `@webjsdev/server` returns the request's `AbortSignal`. It fires when the client disconnects OR when a newer client render supersedes this one (the RPC stub aborts the previous in-flight fetch). Thread it into the work you start, and re-check it after an await to map an abort to a cancelled envelope:
+Inside an action, `actionSignal()` from `@webjsdev/server` returns the request's `AbortSignal`. It fires when the client disconnects OR when a newer client render supersedes this one (the RPC stub aborts the previous in-flight fetch). Only an action called in the synchronous part of a component's own `render()` is tied to that render. One called from `connectedCallback`, an event handler, `firstUpdated()` / `updated()`, or a `Task` is never cancelled by a re-render, including a child element's `connectedCallback` that runs while its parent's template is being committed, so a child can start its first fetch there without the parent's next render cancelling it. Thread it into the work you start, and re-check it after an await to map an abort to a cancelled envelope:
 
 ```ts
 'use server';

package/templates/.agents/skills/webjs/references/routing-and-pages.md

@@ -87,6 +87,7 @@ export default async function User({ params }: { params: { id: string } }) {
 
 - `[param]/page.ts` dynamic segment, read via `params.param`.
 - `[...rest]/page.ts` catch-all, `[[...rest]]/page.ts` optional catch-all.
+- Overlapping routes resolve by positional specificity, for pages and `route.ts` handlers alike: segment by segment, a static segment beats `[param]`, which beats a catch-all, so `api/auth/callback/github/route.ts` answers before `api/auth/[...path]/route.ts` whatever the directory order.
 - `(group)/...` route group: the folder is NOT in the URL but still scopes layout / error.
 - `_private/...` private folder: ignored by the router.
 

package/templates/.agents/skills/webjs/references/runtime.md

@@ -32,15 +32,21 @@ Three seams pick a runtime-specific implementation, all inside the framework, no
 | Listener | `node:http` shell | native `Bun.serve` (faster on the listening path only, not end-to-end, because SSR render dominates a real page) |
 | TS strip | built-in `module.stripTypeScriptTypes` | `amaro` (byte-identical, position-preserving) |
 | SQLite | built-in `node:sqlite` + `drizzle-orm/node-sqlite` | built-in `bun:sqlite` + `drizzle-orm/bun-sqlite` |
-| Hot reload | `node --watch` | `bun --hot` |
+| Hot reload | restart on change (the `webjs dev` supervisor, #1521) | `bun --hot` |
 | WebSocket | the `ws` library | native `Bun.serve` + a bridge adapter |
 | 103 Early Hints | yes | no (`Bun.serve` has no informational-response API) |
-| Dev edit to a page / layout | full reload (the `node --watch` restart replaces the process) | refreshes IN PLACE, no reload (#1398) |
+| Dev edit to a page / layout | full reload (the dev restart replaces the process) | refreshes IN PLACE, no reload (#1398) |
 | Reverse-proxy headers | `X-Forwarded-Proto` / `X-Forwarded-Host` honored | same |
 
+**`webjs dev` lets an idle host sleep (#1507).** The live-reload stream sends nothing between edits (no keepalive) and is held open only while a tab showing the app is visible, so a sandbox or preview host that suspends on network quiet can suspend with a backgrounded dev tab open. Showing the tab reconnects, and an edit made meanwhile reloads the page on return. A host that counts an OPEN request as activity (a sandbox that suspends on idle) also needs `"webjs": { "dev": { "reloadIdle": 20 } }` (or `WEBJS_DEV_RELOAD_IDLE=20`): after that many seconds with no edit and no interaction the stream closes, and the next interaction, a tab showing, or an embed-bridge host command (`{ source: 'webjs-embed-host', type: 'resume' }`) reopens it. Off by default. Every reconnect also compares the server's state with the state the page on screen was rendered at, so an edit whose reload signal was lost while the stream was being replaced (a host that closes a held stream when it wakes) still reloads the page.
+
 **The in-place dev refresh (#1398) needs the server process to SURVIVE the edit,** which is the whole of the Node-versus-Bun difference in that row. A page or layout never hydrates, so a freshly rendered page is the complete truth for it and the client router can swap it in without a reload, keeping scroll and (for a page edit) the hydrated state of components outside the changed region. The server classifies the changed file and puts the verdict on the live-reload event, so this needs a process that is still alive to do the classifying.
 
-Bun's `bun --hot` invalidates modules in place without restarting, so it gets the refresh. Node's `bun --hot` equivalent is `node --watch`, which RESTARTS the process on a change under `app`, `components`, `modules`, `lib`, or `actions`, or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
+Bun's `bun --hot` invalidates modules in place without restarting, so it gets the refresh. On Node the `webjs dev` supervisor (it replaced `node --watch` in #1521) RESTARTS the server process on a change under `app`, `components`, `modules`, `lib`, or `actions`, or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
+
+**`webjs dev` and `webjs start` serve the directory they are started in, and refuse anywhere else (#1526).** Run them in the app directory, the one holding `app/`. In a workspace (`apps/web` under a root `package.json` with `workspaces`) that is the member, even when the CLI is hoisted to the root `node_modules`: the hoisted bin and the Bun `--hot` child both keep the directory they were started in. Started where there is no `app/` (the workspace root, or a subdirectory such as `app/` itself), both exit 1 before any `before` step runs, naming the app to start (`cd apps/web && webjs dev`), instead of booting a server that answers 404 for every route.
+
+**`webjs dev` does not stay down (#1521).** The supervisor and the server's own watcher handle every watcher error: a file in a watched dir the dev server cannot read or watch (the 0600 temp file `sed -i` creates when another user runs it, a file removed mid-scan) logs one `file watcher skipped <path> (EACCES)` warning and both keep running, where `node --watch` used to crash and leave the preview dead. Edits that REPLACE a file (`sed -i`, an editor saving through a temp file, an atomic write) are heard every time, however often the same file is replaced (#1529: on Linux under Node the watchers watch each directory, since Node 24's own recursive watcher stopped hearing a file after its first replacement). A server process that crashes is started again on the next file change, or by itself after a backoff of 0.5s growing to 10s for repeated crashes. On Bun the supervisor does only the crash recovery, since `bun --hot` reloads edits in place. Stopping `webjs dev` (Ctrl-C, SIGTERM) stops the server child too, and a child whose supervisor was killed outright exits on its own, so nothing is left holding the port.
 
 The 103 Early Hints gap costs only a small first-load latency edge where an edge proxy forwards the 103, never correctness. The `modulepreload` hints still ship in the document head on both runtimes.