@webjsdev/cli 0.10.59 → 0.10.60

package/bin/webjs.js

@@ -500,6 +500,14 @@ 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'));
+        // 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 startServer({ appDir: process.cwd(), port, dev: true });
         break;
       }
@@ -520,22 +528,21 @@ 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'));
@@ -544,12 +551,13 @@ async function main() {
         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': {

package/lib/dev-reload.js

@@ -0,0 +1,382 @@
+/**
+ * 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';
+
+/**
+ * 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 {
+      watchers.set(name, guard(watchFn(join(cwd, name), { recursive: true }, (_type, filename) => {
+        const rel = filename ? join(name, String(filename)) : name;
+        if (!ignore(rel)) onChange(rel);
+      })));
+    } 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,
+ * }} 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,
+}) {
+  /** @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 (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 = () => {};
+
+  const sup = createSupervisor({
+    restartOnChange: plan.restartOnChange,
+    log,
+    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);
+  const 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,
+  });
+
+  let exiting = false;
+  const shutdown = (code) => {
+    if (exiting) return;
+    exiting = true;
+    closeWatch();
+    sup.stop().then(() => onExit(code));
+  };
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.59",
+  "version": "0.10.60",
   "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": {

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

@@ -22,12 +22,13 @@ 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` |
+| `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
@@ -39,7 +40,7 @@ Read this when wiring caching or rate limiting, storing uploads, hardening heade
 { source: 'webjs-embed', type: 'select', src, tag, text, rect: { x, y, width, height } } // a click in inspect mode
 ```
 
-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). 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,19 @@ 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` 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. 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.