@webjsdev/cli 0.10.62 → 0.10.63

package/bin/webjs.js

@@ -7,7 +7,7 @@ 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, failFastOnPortInUse } from '../lib/port.js';
-import { planDevSupervisor } from '../lib/dev-supervisor.js';
+import { planDevSupervisor, readDevSourceLocations, sourceLocationsOn } from '../lib/dev-supervisor.js';
 import { checkAppName, appNameErrorMessage } from '../lib/app-name.js';
 import { findCheckTarget, notAnAppMessage, notAnAppJson, findServeTarget, notAnAppServeMessage } from '../lib/check-target.js';
 
@@ -513,7 +513,7 @@ async function main() {
   }
   switch (cmd) {
     case 'dev': {
-      // If we're already inside the reload child (node --watch or bun --hot),
+      // If we're already inside the reload child (under the supervisor),
       // start the server directly.
       if (process.env.__WEBJS_DEV_CHILD === '1') {
         const { startServer } = await import('@webjsdev/server');
@@ -553,13 +553,15 @@ async function main() {
 
       // 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
+      // runs it under `bun --hot` on Bun (#514), restarting it there only for an
+      // edit to a module a Bun.plugin serves (#1550), 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'),
+        sourceLocations: sourceLocationsOn(process.env, readDevSourceLocations(process.cwd())),
       });
 
       if (plan.mode === 'inline') {

package/lib/dev-reload.js

@@ -205,11 +205,16 @@ export function watchRestartPaths(cwd, { dirs, files, ignore, onChange, onError,
  *   killTimeoutMs?: number,
  *   finalExitCodes?: number[],
  *   onFinal?: (code: number) => void,
+ *   restartFor?: (path: string) => boolean,
  * }} opts
  */
 export function createSupervisor({
   spawnChild,
   restartOnChange,
+  // Which changed paths restart a live child (default: all). On Bun only the
+  // paths `bun --hot` cannot reload in place do (#1550); the rest it reloads
+  // itself. A dead child is started by any change either way.
+  restartFor = () => true,
   log = () => {},
   timers = globalThis,
   now = Date.now,
@@ -230,6 +235,8 @@ export function createSupervisor({
   let crashes = 0;
   /** @type {string | null} */
   let pendingPath = null;
+  // Whether any change in the current debounce window asks for a restart.
+  let pendingRestart = false;
   /** @type {any} */ let debounceTimer = null;
   /** @type {any} */ let backoffTimer = null;
   /** @type {any} */ let killTimer = null;
@@ -289,7 +296,9 @@ export function createSupervisor({
   const flush = () => {
     debounceTimer = null;
     const path = pendingPath;
+    const wantsRestart = pendingRestart;
     pendingPath = null;
+    pendingRestart = false;
     if (stopping) return;
     if (!child) {
       // Not running (crashed, or waiting out a backoff): a change is the cue.
@@ -297,7 +306,7 @@ export function createSupervisor({
       launch();
       return;
     }
-    if (!restartOnChange || restarting) return;
+    if (!restartOnChange || restarting || !wantsRestart) return;
     restarting = true;
     if (path) log(`${path} changed, restarting the dev server`);
     terminate(child);
@@ -308,7 +317,10 @@ export function createSupervisor({
     /** @param {string} path */
     change(path) {
       if (stopping) return;
-      if (pendingPath === null) pendingPath = path;
+      if (restartFor(path)) {
+        if (!pendingRestart) pendingPath = path;
+        pendingRestart = true;
+      } else if (pendingPath === null) pendingPath = path;
       debounceTimer = clear(debounceTimer);
       debounceTimer = timers.setTimeout(flush, debounceMs);
     },
@@ -331,7 +343,7 @@ export function createSupervisor({
  *
  * @param {{
  *   cwd: string,
- *   plan: { args: string[], restartOnChange: boolean, watchDirs: string[], watchFiles: string[] },
+ *   plan: { args: string[], restartOnChange: boolean, restartFor?: (path: string) => boolean, watchDirs: string[], watchFiles: string[] },
  *   env: NodeJS.ProcessEnv,
  *   onExit: (code: number) => void,
  * }} opts
@@ -356,6 +368,7 @@ export function superviseDevServer({ cwd, plan, env, onExit }) {
 
   const sup = createSupervisor({
     restartOnChange: plan.restartOnChange,
+    ...(plan.restartFor ? { restartFor: plan.restartFor } : {}),
     log,
     // The child already printed why (the port and its holder); stop with its
     // code rather than restarting a server that can never bind.

package/lib/dev-supervisor.js

@@ -15,11 +15,18 @@
  *   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`).
+ * - **Bun** runs the child under `bun --hot`, which invalidates loaded modules
+ *   on a file change WITHOUT restarting the process (so a page edit can be
+ *   refreshed in place, #1398). But `bun --hot` does not watch a file whose
+ *   contents a `Bun.plugin` `onLoad` returned (#1550), and two plugins serve
+ *   app modules on Bun: the `'use server'` seed plugin (every `*.server.*`
+ *   module, always on) and the SSR source-locations plugin (every other app
+ *   JS/TS module when source locations are on). An edit to one of THOSE
+ *   restarts the child, like Node; every other edit is left to `bun --hot`.
+ *   A module the server re-imports directly (a page, an action module) is fresh
+ *   even before the restart lands, because the dev cache-bust import rides a
+ *   plain path on Bun (`devImportSpecifier` in `@webjsdev/server`; Bun drops a
+ *   `file://` specifier's query).
  *
  * 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.
@@ -27,6 +34,8 @@
  * 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.
  */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 
 /** Project directories whose changes restart the dev server on Node. */
 export const WATCH_DIRS = ['app', 'components', 'modules', 'lib', 'actions'];
@@ -46,14 +55,15 @@ export const WATCH_FILES = ['middleware.ts', 'middleware.js', 'middleware.mts',
  * @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).
- * @returns {{ mode: 'inline' } | { mode: 'supervise', args: string[], restartOnChange: boolean, watchDirs: string[], watchFiles: string[] }}
+ * @param {boolean} [opts.sourceLocations]  Whether dev source locations are on (`WEBJS_SOURCE_LOCATIONS` / `webjs.dev.sourceLocations`), which puts every app module behind a Bun plugin.
+ * @returns {{ mode: 'inline' } | { mode: 'supervise', args: string[], restartOnChange: boolean, restartFor?: (path: string) => 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 }) {
+export function planDevSupervisor({ isBun, argv, noHot, sourceLocations = false }) {
   // `--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
@@ -61,6 +71,53 @@ export function planDevSupervisor({ isBun, argv, noHot }) {
   if (noHot) return { mode: 'inline' };
 
   const watch = { watchDirs: [...WATCH_DIRS], watchFiles: [...WATCH_FILES] };
-  if (isBun) return { mode: 'supervise', args: ['--hot', ...argv], restartOnChange: false, ...watch };
+  if (isBun) return { mode: 'supervise', args: ['--hot', ...argv], restartOnChange: true, restartFor: bunPluginServed(sourceLocations), ...watch };
   return { mode: 'supervise', args: [...argv], restartOnChange: true, ...watch };
 }
+
+const SERVER_MODULE = /\.server\.m?[jt]s$/;
+const APP_MODULE = /\.m?[jt]s$/;
+
+/**
+ * The changed paths `bun --hot` cannot reload because a `Bun.plugin` serves
+ * them (#1550): every `*.server.*` module (the `'use server'` seed plugin), and
+ * with source locations on every JS/TS app module (the source-locations
+ * plugin). Paths are app-relative, as the supervisor's watcher reports them.
+ *
+ * @param {boolean} sourceLocations
+ * @returns {(path: string) => boolean}
+ */
+export function bunPluginServed(sourceLocations) {
+  return (path) => SERVER_MODULE.test(path) || (sourceLocations && APP_MODULE.test(path));
+}
+
+/**
+ * Whether dev source locations are on, the same rule the server applies
+ * (`sourceLocationsRequested` in `@webjsdev/server`): `WEBJS_SOURCE_LOCATIONS`
+ * set to 1/true or 0/false wins, otherwise `webjs.dev.sourceLocations`.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {unknown} configured the app's `webjs.dev.sourceLocations`
+ * @returns {boolean}
+ */
+export function sourceLocationsOn(env, configured) {
+  const v = String(env.WEBJS_SOURCE_LOCATIONS || '').trim().toLowerCase();
+  if (v === '1' || v === 'true') return true;
+  if (v === '0' || v === 'false') return false;
+  return configured === true;
+}
+
+/**
+ * The app's `webjs.dev.sourceLocations` from `<appDir>/package.json`, or
+ * undefined when the file or the key is missing or unreadable.
+ *
+ * @param {string} appDir
+ * @returns {unknown}
+ */
+export function readDevSourceLocations(appDir) {
+  try {
+    return JSON.parse(readFileSync(join(appDir, 'package.json'), 'utf8'))?.webjs?.dev?.sourceLocations;
+  } catch {
+    return undefined;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.62",
+  "version": "0.10.63",
   "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.73",
+    "@webjsdev/server": "^0.8.79",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

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

@@ -101,6 +101,8 @@ export const GET = handlers.GET;
 export const POST = handlers.POST;
 ```
 
+**Cookie names.** `createAuth` sets `webjs.auth` (session) and, for OAuth, `webjs.auth.state` and `webjs.auth.redirect` in development. In production (`NODE_ENV=production`) each carries the `__Host-` prefix (`__Host-webjs.auth`, ...), which a browser stores only when `Secure`, `Path=/` and without `Domain`, so an app on a sibling subdomain cannot toss its own session cookie into yours. Production reads only the prefixed names; a test or tool that hand-sets the cookie in production must use the prefixed name.
+
 **The no-JS sign-in / sign-out flow is plain forms** (progressive-enhancement-safe). Sign in by POSTing to `/api/auth/signin/credentials` with a hidden `redirectTo`, and read `?error` (mapped from `pages.error`) for feedback; sign out by POSTing to `/api/auth/signout`:
 
 ```html

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

@@ -390,6 +390,10 @@ every hole position (a child, a plain attribute, a `?bool`, a `.prop`). So
 was previously resolved only in a child hole, which served `open=""` and let
 hydration close the element a moment later (#1443).
 
+## Lazy components: load on first sight
+
+`static lazy = true` defers a component's module until an element with its tag is first visible: scrolled within 200px of the viewport, or shown when a `hidden` tab panel or a closed `<dialog>` around it opens. Reach for it for heavy panes and dialogs a first screen does not show (an editor behind a Code tab, a data browser, a settings dialog). It stays lazy when the component that renders it imports it (`import './code-pane.ts'`): the server keeps that import for SSR, and the browser copy of the importer gets an `observeLazy` registration in its place, with no preload for the lazy subtree (#1524). Only a SIDE-EFFECT import defers; a binding import (`import { CodePane } from ...`) stays eager, and one anywhere in the app makes that component eager everywhere. Until the module arrives the element is not upgraded, so a parent calling into it uses optional calls (`this.#pane.value?.save?.()`). The loader scans light DOM only, so do not render a lazy tag inside a shadow root. Browser tests (`webjs test --browser`) get every import as written, so a test that imports a lazy component has it defined at once. A component opened by a window event rather than by becoming visible (a panel that renders nothing until an `open` event) does not fit `static lazy`: dynamically `import()` its module in the code that dispatches the event, then dispatch.
+
 ## Display-only elision
 
 A component that does no client-side work renders the same SSR'd HTML with or without its JS, so WebJs strips its import from the served source (and any vendor reachable only through it). This is automatic and conservative. A component stays elidable while it has NONE of:

package/templates/.agents/skills/webjs/references/muscle-memory-gotchas.md

@@ -206,7 +206,7 @@ The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middlewa
 
 ### No `<Link>`, no `next/navigation`, no `next/*` libraries
 
-Navigation is automatic. The client router auto-enables when `@webjsdev/core` loads (any page with a component), so a plain `<a href>` gets soft navigation for free. There is no `<Link>` to import and no `useRouter`. For programmatic navigation import `navigate()` / `revalidate()` from `@webjsdev/core`. There is no `next/image`, `next/font`, `next/script`, or `next/dynamic`. WebJs is no-build: use a plain `<img>`, a `<link>` / `@font-face`, a component's `static lazy = true` for viewport lazy-loading, and a dynamic `import()` where code should load lazily.
+Navigation is automatic. The client router auto-enables when `@webjsdev/core` loads (any page with a component), so a plain `<a href>` gets soft navigation for free. There is no `<Link>` to import and no `useRouter`. For programmatic navigation import `navigate()` / `revalidate()` from `@webjsdev/core`. There is no `next/image`, `next/font`, `next/script`, or `next/dynamic`. WebJs is no-build: use a plain `<img>`, a `<link>` / `@font-face`, a component's `static lazy = true` to load it when it is first visible (scrolled near, or its hidden tab panel or dialog opened, and it stays lazy when another component imports it), and a dynamic `import()` where code should load lazily.
 
 ### No `<ScrollRestoration>`, and no scroll restore of your own
 

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

@@ -32,21 +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 | restart on change (the `webjs dev` supervisor, #1521) | `bun --hot` |
+| Hot reload | restart on change (the `webjs dev` supervisor, #1521) | `bun --hot`, plus a restart for a `*.server.*` edit and, with source locations on, any app module edit (#1550) |
 | 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 dev 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), unless source locations are on |
 | 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. 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. An in-place refresh loads the rebuilt stylesheets (a `webjs.dev.regenerate` compile runs on that request) BEFORE it swaps the new markup in, and drops the old sheets only after, so an element that gained a utility class never paints without its rule (#1535; a full reload never had the gap, since a head stylesheet is render-blocking). 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. It cannot reload a module a `Bun.plugin` serves, though (#1550): every `'use server'` `*.server.*` module (the action-seeding plugin) and, when dev source locations are on (`WEBJS_SOURCE_LOCATIONS=1`), every app module (the source-locations plugin). The supervisor restarts the server for an edit to one of those, so on Bun with source locations on every app edit is a full reload, as on Node. 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. An in-place refresh loads the rebuilt stylesheets (a `webjs.dev.regenerate` compile runs on that request) BEFORE it swaps the new markup in, and drops the old sheets only after, so an element that gained a utility class never paints without its rule (#1535; a full reload never had the gap, since a head stylesheet is render-blocking). 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.
+**`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 restarts the server only for an edit `bun --hot` cannot reload in place (a `*.server.*` module, or with source locations on any app module, #1550), and otherwise does only the crash recovery. 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.