@webjsdev/server 0.8.71 → 0.8.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.71",
+  "version": "0.8.73",
   "type": "module",
   "description": "The server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Provides the file-based router, SSR, server actions, route handlers, middleware, and live reload on Node 24+ or Bun.",
   "main": "index.js",

package/src/dev/helpers.js

@@ -360,6 +360,10 @@ const RELOAD_WORKER_SRC = readFileSync(new URL('../dev-reload-worker.js', import
 const DEV_STYLES_SRC = readFileSync(new URL('../dev-styles.js', import.meta.url), 'utf8')
   .replace(/^export /gm, '');
 
+// The embed host's reload hold (#1532), same shared-source rule.
+const DEV_RELOAD_HOLD_SRC = readFileSync(new URL('../dev-reload-hold.js', import.meta.url), 'utf8')
+  .replace(/^export /gm, '');
+
 /**
  * The dev live-reload client. The `EventSource` URL is a framework-emitted
  * same-origin path, so it must carry the base path under a sub-path deploy
@@ -419,6 +423,12 @@ export function reloadClientJs(bp) {
 ${DEV_OVERLAY_SRC}
 ${RELOAD_WORKER_SRC}
 ${DEV_STYLES_SRC}
+${DEV_RELOAD_HOLD_SRC}
+// A framing host holds reloads while its agent builds (#1532): the embed bridge
+// sets __webjsEmbedHold, every signal below is kept (strongest verdict wins),
+// and releasing the hold applies that one reload, or none if nothing changed.
+var __webjsHold = createReloadHold(function (v) { __webjsApplyReload(v); }, function () { return globalThis.__webjsEmbedHold === true; });
+globalThis.__webjsDevReleaseHold = function () { __webjsHold.release(); };
 function __webjsApplyError(data) {
   let f; try { f = JSON.parse(data); } catch (_) { return; }
   renderDevOverlay(f);
@@ -453,6 +463,7 @@ function __webjsWhenReady(then) {
 // survive. Anything else, including every signal the server could not classify,
 // is the full reload this always was.
 function __webjsApplyReload(verdict) {
+  if (__webjsHold.offer(verdict)) return;
   __webjsWhenReady(function () {
     // Runtime feature detection, never an assumption. The refresh entry is
     // published by enableClientRouter and removed by disableClientRouter, so its

package/src/dev/server.js

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { strongerVerdict } from '../dev-classify.js';
-import { watch as fsWatch } from 'node:fs/promises';
+import { watchTree } from './watch-tree.js';
 import { relative } from 'node:path';
 import { createServer as createHttp1Server } from 'node:http';
 import { createRequestHandler } from './handler.js';
@@ -13,6 +13,7 @@ import { stripBasePath } from '../base-path.js';
 import { basePath } from '../importmap.js';
 import { attachWebSocket } from '../websocket.js';
 import { toWebRequest, sendWebResponse } from './helpers.js';
+import { isAddrInUse, portInUseError, reusePortRequested } from '../port-in-use.js';
 
 function debounce(fn, ms) {
   let t;
@@ -80,7 +81,7 @@ function makeHttpServer(handler) {
  * @param {import('../listener-types.js').ListenerContext} ctx
  * @returns {{ server: import('node:http').Server, close: () => Promise<void> }}
  */
-function startNodeListener(ctx) {
+async function startNodeListener(ctx) {
   const { app, dev, compress, logger, hub, port, basePathStr, timeouts, watcherAbort } = ctx;
 
   const server = makeHttpServer(async (req, res) => {
@@ -171,14 +172,25 @@ function startNodeListener(ctx) {
   // WebSocket endpoint at its URL.
   attachWebSocket(server, () => app.getRouteTable(), { dev, logger });
 
-  server.listen(port, () => {
-    logger.info(`webjs ${dev ? 'dev' : 'prod'} server ready on http://localhost:${port}`);
-    // The server is now accepting connections; warm the first-request analysis
-    // in the background so a real first request finds it memoized. Fire-and-
-    // forget: listening (and thus readiness probes / load-balancer health) does
-    // not wait on it, and a failure here does not bring the process down.
-    app.warmup();
+  // Listening is awaited, so a bind failure rejects startServer instead of
+  // surfacing as an unhandled 'error' event. A taken port fails fast with the
+  // holder named (#1527); WEBJS_REUSE_PORT=1 shares the port on purpose
+  // (SO_REUSEPORT, honoured on Linux by Node 22.12+ / 23.1+).
+  await new Promise((resolve, reject) => {
+    const onError = (/** @type {NodeJS.ErrnoException} */ e) => reject(isAddrInUse(e) ? portInUseError(port, e) : e);
+    server.once('error', onError);
+    const options = reusePortRequested() ? { port, reusePort: true } : { port };
+    server.listen(options, () => {
+      server.off('error', onError);
+      resolve(undefined);
+    });
   });
+  logger.info(`webjs ${dev ? 'dev' : 'prod'} server ready on http://localhost:${port}`);
+  // The server is now accepting connections; warm the first-request analysis
+  // in the background so a real first request finds it memoized. Fire-and-
+  // forget: listening (and thus readiness probes / load-balancer health) does
+  // not wait on it, and a failure here does not bring the process down.
+  app.warmup();
 
   const closeServer = () => new Promise((resolve, reject) => {
     server.close((err) => (err ? reject(err) : resolve(undefined)));
@@ -190,7 +202,7 @@ function startNodeListener(ctx) {
   // Catch-all process handlers: log, but don't tear the process down on a
   // single mishandled promise. Uncaught exceptions are different: state may be
   // corrupted, so log + start an orderly shutdown rather than continuing.
-  installProcessHandlers(logger, () => shutdown('uncaughtException', { fatal: true }));
+  installProcessHandlers(logger, () => shutdown('uncaughtException', { fatal: true }), { dev });
 
   return {
     server,
@@ -252,11 +264,12 @@ export async function startServer(opts) {
   /** @type {AbortController | null} */
   let watcherAbort = null;
   if (dev) {
-    // Watch the app root recursively via Node's built-in
-    // `fs.promises.watch`. Stable on macOS, Windows, and Linux as of
-    // Node 24. No external dep needed.
+    // Watch the app tree with Node's built-in `fs.watch` (no external dep):
+    // `watchTree` (#1521) watches the root plus each non-ignored top-level dir,
+    // so `node_modules` is never walked, and handles a per-path watch error
+    // (EACCES, ENOENT) with a warning instead of an uncaughtException.
     //
-    // fs.watch returns relative paths in event.filename. `shouldIgnoreWatchPath`
+    // Paths are reported relative to the watched root. `shouldIgnoreWatchPath`
     // (module-level, exported for tests) skips node_modules, .git, .webjs/, and
     // the SQLite dev DB (db/dev.db) + db/migrations so a file the dev server itself writes never loops.
     // Live-reload classification (#1398). Several files can change inside one
@@ -273,26 +286,32 @@ export async function startServer(opts) {
       app.rebuild(v || undefined);
     }, 80);
     watcherAbort = new AbortController();
-    const watchRoot = async (root) => {
-      try {
-        const events = fsWatch(root, { recursive: true, signal: watcherAbort.signal });
-        for await (const event of events) {
-          const filename = event.filename || '';
-          if (shouldIgnoreWatchPath(filename)) continue;
+    // One warning per unwatchable path (#1521): an EACCES / ENOENT on a single
+    // file must never stop the dev server, and a burst of the same temp file
+    // must not flood the log either.
+    const warned = new Set();
+    const onWatchError = (err) => {
+      const key = `${err && err.code}:${err && err.path}`;
+      if (warned.has(key) || warned.size > 200) return;
+      warned.add(key);
+      logger.warn(`file watcher skipped ${err && err.path ? err.path : 'a path'} (${err && err.code ? err.code : String(err)})`);
+    };
+    const watchRoot = (root) => {
+      const close = watchTree(root, {
+        ignore: shouldIgnoreWatchPath,
+        onEvent: (filename) => {
           // A regenerate output (#967) is a build product the server itself
           // writes on request; ignoring it stops a spurious rebuild + reload
           // (and a reload -> refetch -> recompile -> reload cycle), same as the
           // db/dev.db carve-out above. `app` exposes the check because `state`
           // lives in createRequestHandler's scope, not here.
-          if (app.isRegenerateOutput(filename)) continue;
+          if (app.isRegenerateOutput(filename)) return;
           pendingVerdict = strongerVerdict(pendingVerdict, app.classifyWatchPath(filename, root));
           rebuild();
-        }
-      } catch (err) {
-        if (err && /** @type any */(err).name !== 'AbortError') {
-          logger.warn({ err }, `file watcher exited (${root})`);
-        }
-      }
+        },
+        onError: onWatchError,
+      });
+      watcherAbort.signal.addEventListener('abort', close, { once: true });
     };
     watchRoot(app.appDir);
     // Extra roots the app reads from OUTSIDE its appDir (#894): repo-root content
@@ -321,9 +340,18 @@ export async function startServer(opts) {
   // skips the node:http bridge (toWebRequest/sendWebResponse) for ~1.9x more
   // req/s on the listening path (#511); the Bun shell is dynamically imported so
   // the `Bun.*` global is never referenced on Node.
-  if (serverRuntime() === 'bun') {
-    const { startBunListener } = await import('../listener-bun.js');
-    return startBunListener(ctx);
+  try {
+    if (serverRuntime() === 'bun') {
+      const { startBunListener } = await import('../listener-bun.js');
+      return startBunListener(ctx);
+    }
+    return await startNodeListener(ctx);
+  } catch (e) {
+    // The listener never came up (a taken port, #1527): stop what was started
+    // for it, so an embedding caller that catches this is not left with a
+    // live file watcher keeping the process alive.
+    if (watcherAbort) watcherAbort.abort();
+    hub.closeAll();
+    throw e;
   }
-  return startNodeListener(ctx);
 }

package/src/dev/watch-recursive.js

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

package/src/dev/watch-tree.js

@@ -0,0 +1,108 @@
+import { watch, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { watchRecursive } from './watch-recursive.js';
+
+/**
+ * The dev live-reload watcher over one root (#1521).
+ *
+ * Two problems with the plain `fs.promises.watch(root, { recursive: true })`
+ * this replaces, both on Node 24's JS-implemented recursive watcher on Linux
+ * (`internal/fs/recursive_watch`), which opens one `fs.watch` per FILE:
+ *
+ * 1. A per-file failure (EACCES on a `sed -i` temp file another user created
+ *    with mode 0600, ENOENT on a file that vanished between the directory event
+ *    and the watch call) is emitted as `'error'` on an internal watcher the
+ *    promise API never listens to, so it surfaces as an uncaughtException and
+ *    the dev server shuts down. The callback form takes an `'error'` listener,
+ *    and the watcher keeps delivering events for every other file after it.
+ * 2. Watching the app ROOT walks `node_modules` too: about 10k per-file watches
+ *    and roughly 275ms of synchronous work on every boot of a scaffolded app,
+ *    all for events the ignore filter then drops. So the root is watched
+ *    non-recursively and each top-level directory that is not ignored gets its
+ *    own recursive watcher.
+ *
+ * A top-level directory created or removed after start is picked up from the
+ * root watcher's events, so `mkdir lib` mid-session is watched like it was
+ * there at boot.
+ *
+ * @param {string} root  absolute directory to watch
+ * @param {{
+ *   ignore: (relPath: string) => boolean,
+ *   onEvent: (relPath: string) => void,
+ *   onError: (err: NodeJS.ErrnoException) => void,
+ * }} opts  `relPath` is relative to `root`, with OS separators.
+ * @returns {() => void} closes every watcher
+ */
+export function watchTree(root, { ignore, onEvent, onError }) {
+  /** @type {Map<string, import('node:fs').FSWatcher>} */
+  const dirs = new Map();
+  let closed = false;
+
+  const guard = (/** @type {import('node:fs').FSWatcher} */ w) => {
+    w.on('error', (err) => onError(/** @type {NodeJS.ErrnoException} */ (err)));
+    return w;
+  };
+
+  const isDir = (name) => {
+    try { return statSync(join(root, name)).isDirectory(); } catch { return false; }
+  };
+
+  const watchDir = (name) => {
+    if (closed || dirs.has(name) || ignore(name)) return;
+    try {
+      // `watchRecursive` (#1529): on Linux under Node a per-directory walker,
+      // since Node 24's recursive watcher goes deaf to a file once it is
+      // replaced (`sed -i`, an editor's atomic save).
+      const w = guard(watchRecursive(join(root, name), (_type, filename) => {
+        const rel = filename ? join(name, String(filename)) : name;
+        if (!ignore(rel)) onEvent(rel);
+      }, { ignore: (rel) => ignore(join(name, rel)) }));
+      dirs.set(name, w);
+    } catch (err) {
+      onError(/** @type {NodeJS.ErrnoException} */ (err));
+    }
+  };
+
+  /** @type {import('node:fs').FSWatcher | null} */
+  let top = null;
+  try {
+    top = guard(watch(root, (_type, filename) => {
+      if (!filename) return;
+      const name = String(filename);
+      if (ignore(name)) return;
+      // A top-level entry changed: start or stop following it as a directory.
+      if (isDir(name)) watchDir(name);
+      else if (dirs.has(name)) { try { dirs.get(name)?.close(); } catch {} dirs.delete(name); }
+      onEvent(name);
+    }));
+  } catch (err) {
+    onError(/** @type {NodeJS.ErrnoException} */ (err));
+  }
+
+  let entries = [];
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch {}
+  for (const e of entries) {
+    if (e.isDirectory() || (e.isSymbolicLink() && isDir(e.name))) watchDir(e.name);
+  }
+
+  return () => {
+    closed = true;
+    try { top?.close(); } catch {}
+    for (const w of dirs.values()) { try { w.close(); } catch {} }
+    dirs.clear();
+  };
+}
+
+/**
+ * Whether an error came from a file watcher (#1521). Node marks every
+ * `fs.watch` failure with `syscall: 'watch'` (EACCES, EPERM, ENOENT, ELOOP, and
+ * ENOSPC when the inotify limit is reached). One unwatchable path is never a
+ * reason to stop a dev server, so the dev process handlers log these and keep
+ * serving.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isWatchError(err) {
+  return !!err && typeof err === 'object' && /** @type {any} */ (err).syscall === 'watch';
+}

package/src/dev-embed-client.js

@@ -266,6 +266,11 @@ export function installEmbedBridge(origins, opts) {
       tag: picked.localName,
       text: (picked.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80),
       rect: rectOf(picked),
+      // Modifier keys (#1532), so a host can multi-select (shift/cmd-click).
+      shiftKey: !!e.shiftKey,
+      metaKey: !!e.metaKey,
+      altKey: !!e.altKey,
+      ctrlKey: !!e.ctrlKey,
     });
   }
   function setInspect(on) {
@@ -291,6 +296,57 @@ export function installEmbedBridge(origins, opts) {
   }
   cleanups.push(function () { setInspect(false); });
 
+  // Reload hold (#1532). While the host holds, the reload client keeps every
+  // live-reload signal instead of applying it (dev-reload-hold.js), and the
+  // release applies the one strongest reload, or none. The switch is a page
+  // global because the reload client is a separate script, and it is kept in
+  // sessionStorage so a new document in this tab (a full navigation or a host
+  // `reload` mid-build) starts held too.
+  var HOLD_KEY = 'webjs-embed-hold';
+  function store() {
+    try { return win.sessionStorage || null; } catch (_) { return null; }
+  }
+  function setHold(on) {
+    win.__webjsEmbedHold = on;
+    var s = store();
+    try { if (s) { if (on) s.setItem(HOLD_KEY, '1'); else s.removeItem(HOLD_KEY); } } catch (_) { /* storage blocked */ }
+    if (!on && typeof win.__webjsDevReleaseHold === 'function') {
+      try { win.__webjsDevReleaseHold(); } catch (_) { /* no reload client */ }
+    }
+    post('hold', { enabled: on });
+  }
+  try { if (store() && store().getItem(HOLD_KEY) === '1') win.__webjsEmbedHold = true; } catch (_) { /* storage blocked */ }
+  cleanups.push(function () { win.__webjsEmbedHold = false; });
+
+  // Scroll restore across a reload (#1532). A full dev reload, or the host's
+  // `reload`, would otherwise land at the top. The position is saved per path
+  // on pagehide and put back when the next document is a RELOAD of the same
+  // path: at once, after parsing, and after load (late images move layout),
+  // unless the user scrolls first.
+  var SCROLL_KEY = 'webjs-embed-scroll';
+  listen(win, 'pagehide', function () {
+    var s = store();
+    try { if (s) s.setItem(SCROLL_KEY, JSON.stringify({ path: here(), x: win.scrollX, y: win.scrollY })); } catch (_) { /* storage blocked */ }
+  });
+  (function restoreScroll() {
+    var s = store();
+    var saved = null;
+    try {
+      if (s) { saved = JSON.parse(s.getItem(SCROLL_KEY) || 'null'); s.removeItem(SCROLL_KEY); }
+    } catch (_) { saved = null; }
+    if (!saved || saved.path !== here() || typeof saved.y !== 'number') return;
+    var nav = null;
+    try { nav = win.performance.getEntriesByType('navigation')[0]; } catch (_) { /* no timing api */ }
+    if (!nav || nav.type !== 'reload') return;
+    var userMoved = false;
+    function moved() { userMoved = true; }
+    function put() { if (!userMoved) win.scrollTo(saved.x || 0, saved.y); }
+    ['wheel', 'touchstart', 'keydown', 'pointerdown'].forEach(function (t) { listen(win, t, moved, true); });
+    put();
+    if (doc.readyState === 'loading') listen(doc, 'DOMContentLoaded', put);
+    if (doc.readyState !== 'complete') listen(win, 'load', put);
+  })();
+
   // Host commands. Only from the parent window, only from an allowed origin.
   listen(win, 'message', function (e) {
     if (!e || e.source !== parent || origins.indexOf(e.origin) === -1) return;
@@ -322,6 +378,8 @@ export function installEmbedBridge(origins, opts) {
       a.remove();
     } else if (d.type === 'inspect') {
       setInspect(d.enabled === true);
+    } else if (d.type === 'hold') {
+      setHold(d.enabled === true);
     }
     // { type: 'resume' } needs nothing beyond the activity call above.
   });

package/src/dev-reload-hold.js

@@ -0,0 +1,68 @@
+/**
+ * The dev live-reload HOLD (#1532), shared source.
+ *
+ * A tool that frames a WebJs app (an AI app builder) pauses live reload while
+ * its agent is mid-build, so the preview does not flicker through every
+ * intermediate save, and releases it when the build is done. The embed bridge
+ * (`dev-embed-client.js`) owns the switch, the `__webjsEmbedHold` page global,
+ * set from the host's `{ type: 'hold', enabled }` command. The reload client
+ * routes every reload signal through this module: while held it keeps only the
+ * STRONGEST verdict seen, and on release it applies that one reload, or nothing
+ * when nothing changed.
+ *
+ * Import-free and inlined verbatim (`export` stripped) into the served reload
+ * client by `reloadClientJs` in `dev/helpers.js`, the same shared-source rule as
+ * `dev-styles.js`, so the unit test drives the code that ships.
+ */
+
+/**
+ * Verdict strength, strongest first. Restated rather than imported from
+ * `dev-reload-worker.js` because this file is inlined on its own.
+ */
+var HOLD_STRENGTH = ['reload', 'shell', 'page'];
+
+/**
+ * The stronger of two verdicts. Anything that is not a known verdict is a full
+ * `reload`, the fail-safe every other reload path uses.
+ *
+ * @param {string | null} a  the verdict held so far (null = none)
+ * @param {unknown} b  the incoming verdict
+ * @returns {string}
+ */
+export function strongerHeldVerdict(a, b) {
+  var ib = HOLD_STRENGTH.indexOf(/** @type {string} */ (b));
+  if (ib === -1) ib = 0;
+  if (a === null) return HOLD_STRENGTH[ib];
+  var ia = HOLD_STRENGTH.indexOf(a);
+  if (ia === -1) ia = 0;
+  return HOLD_STRENGTH[Math.min(ia, ib)];
+}
+
+/**
+ * Build the hold gate for one page.
+ *
+ * @param {(verdict: string) => void} apply  applies a reload (the client's own apply)
+ * @param {() => boolean} isHeld  whether the host currently holds reloads
+ * @returns {{ offer: (verdict: unknown) => boolean, release: () => void, pending: () => string | null }}
+ *   `offer` returns true when it kept the signal (held), false when the caller
+ *   should apply it now; `release` applies the one pending reload once the hold
+ *   is off.
+ */
+export function createReloadHold(apply, isHeld) {
+  /** @type {string | null} */
+  var held = null;
+  return {
+    offer: function (verdict) {
+      if (!isHeld()) return false;
+      held = strongerHeldVerdict(held, verdict);
+      return true;
+    },
+    release: function () {
+      if (isHeld() || held === null) return;
+      var v = held;
+      held = null;
+      apply(v);
+    },
+    pending: function () { return held; },
+  };
+}

package/src/listener-bun.js

@@ -48,6 +48,7 @@ import { matchApi } from './router.js';
 import { registerClient } from './broadcast.js';
 import { setTrustedRemoteIp, propagateTrustedRemoteIp } from './rate-limit.js';
 import { applyForwarded } from './forwarded.js';
+import { isAddrInUse, portInUseError, reusePortRequested } from './port-in-use.js';
 import {
   isCompressible,
   isEventsPath,
@@ -72,8 +73,16 @@ import {
 export function startBunListener(ctx) {
   const { app, dev, compress, logger, hub, port, basePathStr, timeouts, watcherAbort } = ctx;
 
-  const server = Bun.serve({
+  /** @type {any} */
+  let server;
+  try {
+    server = Bun.serve({
     port,
+    // Explicit, never Bun's default (#1527): with `development: false` Bun
+    // turns SO_REUSEPORT on, so a second server on a taken port bound silently
+    // and the kernel split the requests between the two. Off unless the
+    // operator asks for a shared port with WEBJS_REUSE_PORT=1.
+    reusePort: reusePortRequested(),
     idleTimeout: bunIdleTimeout(timeouts),
     // WebJs owns its dev error overlay (over SSE) and handles thrown errors in
     // `fetch`, so Bun's own development error page must never interfere; keep it
@@ -145,6 +154,12 @@ export function startBunListener(ctx) {
       },
     },
   });
+  } catch (e) {
+    // A taken port fails fast with the holder named (#1527); the CLI prints
+    // it and exits instead of retrying.
+    if (isAddrInUse(e)) throw portInUseError(port, e);
+    throw e;
+  }
 
   logger.info(
     `webjs ${dev ? 'dev' : 'prod'} server ready on http://localhost:${server.port} (Bun ${process.versions.bun})`,
@@ -157,7 +172,7 @@ export function startBunListener(ctx) {
   const shutdown = makeShutdown({ closeServer, hub, logger });
   process.once('SIGINT', () => shutdown('SIGINT'));
   process.once('SIGTERM', () => shutdown('SIGTERM'));
-  installProcessHandlers(logger, () => shutdown('uncaughtException', { fatal: true }));
+  installProcessHandlers(logger, () => shutdown('uncaughtException', { fatal: true }), { dev });
 
   return {
     server,

package/src/listener-core.js

@@ -23,6 +23,7 @@ import {
 } from 'node:zlib';
 import { stripBasePath } from './base-path.js';
 import { randomUUID } from 'node:crypto';
+import { isWatchError } from './dev/watch-tree.js';
 
 /** The dev live-reload SSE path (matched after base-path stripping). */
 export const EVENTS_PATH = '/__webjs/events';
@@ -416,10 +417,18 @@ export class SseHub {
 /**
  * Install once-only process error handlers. Idempotent across multiple
  * `startServer` calls in the same process. Runtime-neutral (plain `process.on`).
+ *
+ * In dev, an uncaught file-watcher error (`syscall: 'watch'`, #1521) is logged
+ * as a warning and NOT fatal: one unreadable or vanished file in a watched dir
+ * says nothing about the server's state, and shutting down over it is how a
+ * `sed -i` from another user took a whole dev preview down. Prod keeps the
+ * strict contract, every uncaught exception is fatal.
+ *
  * @param {import('./logger.js').Logger} logger
  * @param {() => void} onFatal Starts the FATAL shutdown, which exits non-zero.
+ * @param {{ dev?: boolean }} [opts]
  */
-export function installProcessHandlers(logger, onFatal) {
+export function installProcessHandlers(logger, onFatal, { dev = false } = {}) {
   if (/** @type any */ (globalThis).__webjsProcHandlers) return;
   /** @type any */ (globalThis).__webjsProcHandlers = true;
   process.on('unhandledRejection', (reason) => {
@@ -428,6 +437,10 @@ export function installProcessHandlers(logger, onFatal) {
     });
   });
   process.on('uncaughtException', (err) => {
+    if (dev && isWatchError(err)) {
+      logger.warn(`file watcher skipped ${/** @type any */ (err).path || 'a path'} (${/** @type any */ (err).code || err.message})`);
+      return;
+    }
     logger.error('uncaughtException', { err: err.stack || err.message });
     // Begin orderly shutdown; process state may be corrupt.
     try { onFatal(); } catch {}

package/src/port-in-use.js

@@ -0,0 +1,142 @@
+/**
+ * A taken port fails the server fast, with the process that holds it (#1527).
+ *
+ * Two runtimes, two failure shapes for the same mistake (a second `webjs dev`
+ * on a port another server already listens on):
+ *
+ * - **Bun** turns `SO_REUSEPORT` on by default for `Bun.serve({ development:
+ *   false })`, which the Bun listener passes. The second server then binds
+ *   SILENTLY and the kernel splits connections between the two processes, so a
+ *   stale server keeps answering a share of the requests with old code. The
+ *   listener now passes `reusePort` explicitly (`reusePortRequested()`), so the
+ *   bind fails with `EADDRINUSE` like it does on Node.
+ * - **Node** emitted `EADDRINUSE` as an unhandled `'error'` on the server,
+ *   which crashed the process with a raw stack, and the dev supervisor then
+ *   restarted it on its backoff forever.
+ *
+ * Both listeners now throw `portInUseError()`: an `EADDRINUSE` error whose
+ * message names the holder. The CLI prints it and exits with
+ * `PORT_IN_USE_EXIT_CODE`, which the dev supervisor treats as final.
+ *
+ * Sharing a port is still possible on purpose: `WEBJS_REUSE_PORT=1` sets
+ * `SO_REUSEPORT` on both runtimes (several processes behind the kernel's
+ * balancer).
+ */
+import { readFileSync, readdirSync, readlinkSync } from 'node:fs';
+
+/**
+ * Whether the operator asked for a shared port (`WEBJS_REUSE_PORT=1`).
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function reusePortRequested(env = process.env) {
+  const v = String(env.WEBJS_REUSE_PORT || '').toLowerCase();
+  return v === '1' || v === 'true';
+}
+
+/**
+ * Whether an error is a bind failure on a taken port. Node sets `code`; Bun's
+ * `Bun.serve` sets `code` too, and older Bun releases only said so in the
+ * message.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isAddrInUse(err) {
+  if (!err || typeof err !== 'object') return false;
+  const e = /** @type {any} */ (err);
+  return e.code === 'EADDRINUSE' || /EADDRINUSE|address already in use|Is port \d+ in use/i.test(String(e.message || ''));
+}
+
+/**
+ * The socket inodes LISTENing on `port`, from the text of `/proc/net/tcp` or
+ * `/proc/net/tcp6`. Columns: `sl local_address rem_address st ... inode`; the
+ * port is the hex after the colon of `local_address`, and state `0A` is LISTEN.
+ *
+ * @param {string} table
+ * @param {number} port
+ * @returns {string[]}
+ */
+export function listenInodes(table, port) {
+  const out = [];
+  for (const line of table.split('\n').slice(1)) {
+    const cols = line.trim().split(/\s+/);
+    if (cols.length < 10) continue;
+    const local = cols[1];
+    const hexPort = local.slice(local.lastIndexOf(':') + 1);
+    if (parseInt(hexPort, 16) !== port || cols[3] !== '0A') continue;
+    if (cols[9] && cols[9] !== '0') out.push(cols[9]);
+  }
+  return out;
+}
+
+/**
+ * Best effort: the process listening on `port`, found through `/proc` (Linux
+ * only). Only processes this user may inspect are visible, so a server run by
+ * another user yields null. Never throws.
+ *
+ * @param {number} port
+ * @param {{ readFile?: (p: string) => string, readDir?: (p: string) => string[], readLink?: (p: string) => string, selfPid?: number }} [io]
+ * @returns {{ pid: number, command: string } | null}
+ */
+export function findPortHolder(port, io = {}) {
+  const readFile = io.readFile || ((p) => readFileSync(p, 'utf8'));
+  const readDir = io.readDir || ((p) => readdirSync(p));
+  const readLink = io.readLink || ((p) => readlinkSync(p));
+  const selfPid = io.selfPid ?? process.pid;
+  try {
+    const inodes = new Set();
+    for (const t of ['/proc/net/tcp', '/proc/net/tcp6']) {
+      let text = '';
+      try { text = readFile(t); } catch { continue; }
+      for (const i of listenInodes(text, port)) inodes.add(`socket:[${i}]`);
+    }
+    if (inodes.size === 0) return null;
+    for (const name of readDir('/proc')) {
+      if (!/^\d+$/.test(name) || Number(name) === selfPid) continue;
+      let fds = [];
+      try { fds = readDir(`/proc/${name}/fd`); } catch { continue; }
+      for (const fd of fds) {
+        let target = '';
+        try { target = readLink(`/proc/${name}/fd/${fd}`); } catch { continue; }
+        if (!inodes.has(target)) continue;
+        let command = '';
+        try { command = readFile(`/proc/${name}/cmdline`).split('\0').filter(Boolean).join(' '); } catch {}
+        return { pid: Number(name), command: command.length > 120 ? `${command.slice(0, 119)}…` : command };
+      }
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * The message for a taken port.
+ *
+ * @param {number} port
+ * @param {{ pid: number, command: string } | null} holder
+ * @returns {string}
+ */
+export function portInUseMessage(port, holder) {
+  const who = holder
+    ? `by PID ${holder.pid}${holder.command ? ` (${holder.command})` : ''}`
+    : 'by another process';
+  return `port ${port} is already in use ${who}. Stop that server, or start this one on another port (PORT=<n> or --port <n>).`;
+}
+
+/**
+ * The error both listeners throw on a taken port: code `EADDRINUSE`, a
+ * message naming the holder, the original error as `cause`.
+ *
+ * @param {number} port
+ * @param {unknown} cause
+ * @returns {Error & { code: 'EADDRINUSE', port: number, holder: { pid: number, command: string } | null }}
+ */
+export function portInUseError(port, cause) {
+  const holder = findPortHolder(port);
+  const err = /** @type {any} */ (new Error(portInUseMessage(port, holder), { cause }));
+  err.code = 'EADDRINUSE';
+  err.port = port;
+  err.holder = holder;
+  return err;
+}