@webjsdev/cli 0.10.58 → 0.10.60

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/doctor/codes.js

@@ -49,6 +49,7 @@ export const DOCTOR_CODES = {
   'Component elision (what the browser drops)': 'ELISION_COMPONENTS',
   'Static build outputs (dev.regenerate freshness)': 'STATIC_ASSET_FRESHNESS',
   'Asset urls (unmarked stylesheet links)': 'UNMARKED_ASSET_LINKS',
+  'workspace-overrides': 'WORKSPACE_OVERRIDES',
 };
 
 /**

package/lib/doctor/probes/workspace-overrides.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, sep, matchesGlob } from 'node:path';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/** @param {string} p */
+function readJson(p) {
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+/**
+ * The workspace globs a root package.json declares (npm / bun / yarn), in
+ * either the array form or yarn's `{ packages: [...] }` form, else null.
+ * @param {any} pkg
+ * @returns {string[] | null}
+ */
+function workspaceGlobs(pkg) {
+  const ws = pkg?.workspaces;
+  if (Array.isArray(ws)) return ws;
+  if (ws && Array.isArray(ws.packages)) return ws.packages;
+  return null;
+}
+
+/**
+ * Find the workspace root that `appDir` is a MEMBER of: the nearest ancestor
+ * whose package.json `workspaces` globs match the app's relative path. A plain
+ * parent with a package.json but no matching glob is not a workspace for this
+ * app, so it does not count.
+ * @param {string} appDir
+ * @returns {string | null}
+ */
+export function findWorkspaceRoot(appDir) {
+  let dir = dirname(appDir);
+  for (;;) {
+    const pkg = existsSync(join(dir, 'package.json')) ? readJson(join(dir, 'package.json')) : null;
+    const globs = workspaceGlobs(pkg);
+    if (globs) {
+      const rel = relative(dir, appDir).split(sep).join('/');
+      const included = globs.filter((g) => !g.startsWith('!')).some((g) => matchesGlob(rel, g.replace(/^\.\//, '').replace(/\/$/, '')));
+      const excluded = globs.filter((g) => g.startsWith('!')).some((g) => matchesGlob(rel, g.slice(1).replace(/^\.\//, '')));
+      if (included && !excluded) return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * CHECK (#1492), dependency overrides declared in a workspace MEMBER. npm and
+ * bun honour `overrides` (and yarn / bun `resolutions`) only in the workspace
+ * ROOT package.json, so the same block in a member is silently ignored and the
+ * security floor it encodes (the scaffold's puppeteer-core and basic-ftp
+ * floors) never applies. WARN naming the root to move it to; PASS otherwise.
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+export function checkWorkspaceOverrides(appDir) {
+  const name = 'workspace-overrides';
+  const pkg = readJson(join(appDir, 'package.json'));
+  const keys = ['overrides', 'resolutions'].filter((k) => pkg && pkg[k] && typeof pkg[k] === 'object' && Object.keys(pkg[k]).length);
+  if (keys.length === 0) {
+    return { name, status: 'pass', message: 'No dependency overrides in this package.json.' };
+  }
+  const root = findWorkspaceRoot(appDir);
+  if (!root) {
+    return { name, status: 'pass', message: `\`${keys.join('` / `')}\` apply: this app is not a workspace member.` };
+  }
+  const rel = relative(appDir, join(root, 'package.json')) || 'package.json';
+  return {
+    name,
+    status: 'warn',
+    message: `package.json declares \`${keys.join('` / `')}\`, but this app is a member of the workspace at ${rel}, `
+      + 'and package managers honour overrides only at the workspace root, so these are ignored.',
+    fix: `Move the \`${keys.join('` / `')}\` block into ${rel} (merge it with any the root already has).`,
+  };
+}

package/lib/doctor/runner.js

@@ -11,6 +11,7 @@ import { checkElisionCarriers, checkElisionComponents } from './probes/elision.j
 import { checkStaticAssetFreshness } from './probes/static-asset-freshness.js';
 import { checkUnmarkedAssetLinks } from './probes/unmarked-asset-links.js';
 import { checkFrameworkResolves, checkFrameworkLinks } from './probes/framework-resolves.js';
+import { checkWorkspaceOverrides } from './probes/workspace-overrides.js';
 
 /**
  * @typedef {import('./codes.js').DoctorResult} DoctorResult
@@ -64,6 +65,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkElisionComponents(elision),
     checkStaticAssetFreshness(appDir),
     checkUnmarkedAssetLinks(appDir),
+    Promise.resolve(checkWorkspaceOverrides(appDir)),
   ]);
   // Attach the stable machine code to every result (#975). Centralized here so
   // each check function stays free of the code-contract concern.

package/lib/package-manager.js

@@ -0,0 +1,93 @@
+/**
+ * Package-manager detection for `webjs create` (#1494).
+ *
+ * KEEP IN SYNC with `packages/ui/src/utils/package-manager.js`, the copy
+ * `webjs ui add` uses. The two published
+ * packages carry the same small module rather than one importing the other,
+ * so a `@webjsdev/cli` release can never fail at import time against an older
+ * `@webjsdev/ui` that lacks the export. `packages/cli/test/package-manager.test.mjs`
+ * asserts both copies agree on every fixture.
+ *
+ * Detection order (with `prefer: 'lockfile'`, the default):
+ *   1. A lockfile in `cwd` or any ancestor. The walk stops at the first
+ *      workspace root (a package.json declaring `workspaces`, or a
+ *      `pnpm-workspace.yaml`) or at the filesystem root, so an app nested in a
+ *      workspace finds the root's lockfile. Within one directory the order is
+ *      pnpm, yarn, bun (`bun.lock`, the text lockfile Bun writes since 1.2,
+ *      and the older binary `bun.lockb`), then npm.
+ *   2. `npm_config_user_agent`, which npm, pnpm, yarn and bun set when they
+ *      run a script or a `dlx` / `bunx` / `npx` binary.
+ *   3. `npm`.
+ * With `prefer: 'agent'` steps 1 and 2 swap, which suits `webjs create`: the
+ * tool that invoked it is the strongest signal for a directory that has no
+ * lockfile yet.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/** @typedef {'npm'|'pnpm'|'yarn'|'bun'} PackageManager */
+
+/** Lockfile name to manager, in per-directory precedence order. */
+const LOCKFILES = /** @type {const} */ ([
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['yarn.lock', 'yarn'],
+  ['bun.lock', 'bun'],
+  ['bun.lockb', 'bun'],
+  ['package-lock.json', 'npm'],
+  ['npm-shrinkwrap.json', 'npm'],
+]);
+
+/**
+ * Whether `dir` is a workspace root, where the lockfile walk stops.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isWorkspaceRoot(dir) {
+  if (existsSync(join(dir, 'pnpm-workspace.yaml'))) return true;
+  const pkgPath = join(dir, 'package.json');
+  if (!existsSync(pkgPath)) return false;
+  try {
+    return Boolean(JSON.parse(readFileSync(pkgPath, 'utf8')).workspaces);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk up from `cwd` looking for a lockfile.
+ * @param {string} cwd
+ * @returns {PackageManager | null}
+ */
+export function managerFromLockfile(cwd) {
+  let dir = resolve(cwd);
+  for (;;) {
+    for (const [file, manager] of LOCKFILES) {
+      if (existsSync(join(dir, file))) return manager;
+    }
+    if (isWorkspaceRoot(dir)) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Read the manager from an `npm_config_user_agent` value such as
+ * `bun/1.3.14 npm/? node/v24.0.0 linux x64`.
+ * @param {string | undefined} ua
+ * @returns {PackageManager | null}
+ */
+export function managerFromUserAgent(ua) {
+  const name = String(ua || '').split('/')[0];
+  return name === 'pnpm' || name === 'yarn' || name === 'bun' || name === 'npm' ? name : null;
+}
+
+/**
+ * @param {{ cwd?: string | null, env?: Record<string, string | undefined>, prefer?: 'lockfile' | 'agent' }} [opts]
+ * @returns {PackageManager}
+ */
+export function detectPackageManager({ cwd = null, env = process.env, prefer = 'lockfile' } = {}) {
+  const fromLock = () => (cwd ? managerFromLockfile(cwd) : null);
+  const fromAgent = () => managerFromUserAgent(env.npm_config_user_agent);
+  return (prefer === 'agent' ? fromAgent() ?? fromLock() : fromLock() ?? fromAgent()) ?? 'npm';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.58",
+  "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": {
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "@webjsdev/mcp": "^0.1.0",
-    "@webjsdev/server": "^0.8.67",
+    "@webjsdev/server": "^0.8.68",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

package/templates/.agents/skills/webjs/references/auth-and-sessions.md

@@ -113,6 +113,17 @@ export const POST = handlers.POST;
 <form method="POST" action="/api/auth/signout"><button>Log out</button></form>
 ```
 
+**OAuth sign-in returns the user where they started, with the same one form.** POST to `/api/auth/signin/github` (or `google`) with a hidden `redirectTo`, or link to `GET /api/auth/signin/github?redirectTo=/dashboard/x`; `signIn('github', undefined, { redirectTo })` does the same from an action. The target rides through the provider round trip in a short-lived signed cookie and the callback lands on it, so no wrapper around the auth route is needed:
+
+```html
+<form method="POST" action="/api/auth/signin/github">
+  <input type="hidden" name="redirectTo" value="/dashboard/x">
+  <button>Sign in with GitHub</button>
+</form>
+```
+
+A `redirectTo` that arrives from a request (a form field or a query param, for OAuth or credentials) must be a same-origin local path: one leading `/`, not followed by `/` or `\`. An absolute URL, a protocol-relative `//host`, or a backslash variant is dropped (not repaired) and the sign-in lands on `/`, so the field is never an open redirect. A denied sign-in still goes to `pages.error`.
+
 For a programmatic sign-in (the auto-login-after-signup pattern), `signIn('credentials', creds, { redirectTo })` returns a `302` `Response` that a form-bound action can return directly (the framework honors a returned `Response` verbatim).
 
 Sessions are JWT by default (stateless, scales horizontally). OAuth

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

@@ -22,6 +22,25 @@ 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); `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.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.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
+{ source: 'webjs-embed', type: 'navigate', path, title }         // every client-router navigation + popstate
+{ source: 'webjs-embed', type: 'console', level: 'error' | 'warn', message, dropped? } // max 20/s
+{ 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
+```
+
+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 }))`.
 
@@ -275,6 +294,25 @@ Three levels, the same scale ESLint uses: `error` fails the exit, `warn` reports
 
 Two guarantees worth knowing. A result that could not check (a network or toolchain outage) is capped at `warn` and can never be escalated, so a jspm or npm outage cannot red your CI. And a malformed gate exits 1 naming the offender rather than being ignored, so a typo cannot silently un-gate the build. That covers an unknown code, a bad severity, a wrong shape (a non-object `doctor` or `gate`), and a misspelled sibling of `gate` such as `gates`, since every one of those would otherwise leave the build un-gated while the `package.json` looks gated. Under `--json` the offenders come back as a `configErrors` array alongside an empty `results`, each entry a `{ kind }` of `malformed` / `unknown-key` / `unknown-code` / `bad-severity`. Wire it up with one workflow step, `npm run doctor`, and change what is fatal in `package.json` rather than in the workflow.
 
+### Dependency audit allowlist
+
+`webjs audit` runs `npm audit` or `bun audit` (by the nearest lockfile, so a workspace member uses the root's) and fails on any advisory at or above `webjs.audit.level` (default `high`) that `webjs.audit.ignore` does not list. The scaffold's `Security: dependency audit` CI step runs it.
+
+```jsonc
+{ "webjs": {
+  "audit": {
+    "level": "high",
+    "ignore": [
+      { "id": "GHSA-vfj7-8cjw-p6xm", "reason": "braces has no patched release; reached only through dev tooling" }
+    ]
+  }
+} }
+```
+
+The allowlist is the ONE place an accepted advisory lives, each with its reason. Accept only an advisory with no patched release that the app's users cannot reach; upgrade anything that has a fix. Never "fix" a red audit with `npm audit fix --force`, which proposes breaking majors that often keep the same vulnerable chain. A malformed block (unknown key, bad level, an entry without an id or a reason) exits 1, and an id the audit stops reporting prints as stale, so remove it then.
+
+Overrides apply only at a WORKSPACE ROOT. The scaffold's `overrides` block (the `puppeteer-core` and `basic-ftp` security floors) is ignored once the app is a member of an npm or bun workspace, so move it into the root `package.json`; `webjs doctor` warns with `WORKSPACE_OVERRIDES` until you do.
+
 ## Observability
 
 Wired at the single response funnel, covering pages, routes, actions, and assets uniformly.

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.
 

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

@@ -63,6 +63,8 @@ WEBJS_E2E=1 npm run test  # adds the e2e layer
 
 `npm run test` dispatches on the runtime (`node --test` on Node, `bun test` on Bun). The scaffold's `web-test-runner.config.js` globs `test/**/browser/**/*.test.js` and is already wired, so you do not set it up.
 
+An app with no browser tests yet (for example right after `npm run gallery:clear`) is not a failure: `webjs test --browser` sees that no file matches the config's `files` globs, prints `no browser tests yet`, and exits 0, the same way the server layer passes with zero files. So `npm run ci` stays green until you write the first browser test, and from then on the browser layer runs as normal.
+
 A scaffolded app has one root `test/` directory shaped the same way (feature first, kind second):
 
 ```

package/templates/.dockerignore

@@ -18,7 +18,7 @@ build
 out
 .cache
 
-# Local env files. The container gets its env from compose / uncloud, not a
+# Local env files. The container gets its env from compose or the host, not a
 # committed file. Keep the example for reference.
 .env
 !.env.example

package/templates/Dockerfile

@@ -1,7 +1,7 @@
 # Production image for the {{APP_NAME}} webjs app.
 #
-# Works with a plain `docker build` / `docker compose up`, and is the same
-# artifact the webdeploy hosting tool (ubicloud + uncloud) builds and ships.
+# Works with a plain `docker build` / `docker compose up`, and with any host
+# that builds from a Dockerfile.
 #
 # webjs serves .ts directly by stripping types at the runtime layer, so there is
 # NO JavaScript build step (webjs is buildless end to end; there is no bundler or
@@ -41,7 +41,7 @@ COPY . .
 # step runs `webjs db migrate`). See the CMD note below.
 
 ENV NODE_ENV=production
-# webjs start reads $PORT (default 8080). compose / uncloud / Railway set it.
+# webjs start reads $PORT (default 8080). compose and most hosts set it.
 ENV PORT=8080
 EXPOSE 8080
 

package/templates/compose.yaml

@@ -2,9 +2,9 @@
 #
 #   docker compose up --build   →   http://localhost:8080
 #
-# In production the webdeploy tool (ubicloud + uncloud) provisions a managed
-# Postgres and injects DATABASE_URL + AUTH_SECRET for you. Locally this uses
-# the scaffold's SQLite file on a named volume so data survives `compose down`.
+# In production your host provides DATABASE_URL + AUTH_SECRET. Locally this
+# uses the scaffold's SQLite file on a named volume so data survives
+# `compose down`.
 services:
   app:
     build: .