@webjsdev/server 0.8.72 → 0.8.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.72",
+  "version": "0.8.74",
   "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
@@ -481,10 +492,16 @@ function __webjsApplyReload(verdict) {
       // overlay comes back describing the CURRENT error. Dismissing afterwards
       // would race that push and wipe a legitimately new overlay.
       dismissDevOverlay();
-      refresh(verdict).then(function (ok) {
-        if (!ok) { location.reload(); return; }
-        refreshStyles();
-      }, function () { location.reload(); });
+      // Load the rebuilt stylesheets FIRST and swap the markup in only once
+      // they are in (#1535): a \`webjs.dev.regenerate\` compile takes 100ms to
+      // seconds, and markup swapped in before it lands paints a new class with
+      // no rule. The old sheets stay applied until the swap, then go.
+      preloadStyles().then(function (styles) {
+        return refresh(verdict).then(function (ok) {
+          if (!ok) { location.reload(); return; }
+          styles.commit();
+        });
+      }).then(null, function () { location.reload(); });
       return;
     }
     location.reload();

package/src/dev/server.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)));
@@ -328,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

@@ -1,5 +1,6 @@
 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).
@@ -49,10 +50,13 @@ export function watchTree(root, { ignore, onEvent, onError }) {
   const watchDir = (name) => {
     if (closed || dirs.has(name) || ignore(name)) return;
     try {
-      const w = guard(watch(join(root, name), { recursive: true }, (_type, filename) => {
+      // `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));

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/dev-styles.js

@@ -17,39 +17,42 @@
  */
 
 /**
- * Re-request every same-origin stylesheet under `root`, cache-busted.
+ * Load the rebuilt stylesheets BEFORE the in-place refresh swaps the markup in
+ * (#1535), so a new class never paints without its rule.
  *
- * The replacement is inserted BESIDE the old link, and which of the two
- * survives depends on how the request went. That asymmetry is the whole point
- * and must not be collapsed into one shared handler:
+ * The re-request used to run AFTER the swap, and that order was the flash: the new
+ * markup is on screen while its stylesheet is still being rebuilt and fetched
+ * (a `webjs.dev.regenerate` compile is 100ms to seconds), so an element that
+ * gained a utility class shows with no rule for it until the sheet lands.
+ * Measured on a fixture with an 800ms compile: 56 animation frames (about
+ * 0.9s) painted the edited element unstyled. A full reload never had the
+ * problem, because a `<head>` stylesheet is render-blocking and the browser
+ * holds the old page until it loads.
  *
- * - On `load` the OLD link is dropped, so the page is never briefly unstyled.
- * - On `error` the NEW link is dropped and the old one kept. A re-request can
- *   fail (the server is mid-restart, the file was renamed or deleted), and
- *   removing the last working sheet there would leave the page permanently
- *   unstyled, which is exactly the failure #936 and #1400 exist to prevent.
- *
- * Duplicates are collapsed to one link per IDENTITY, where the identity is
- * every attribute except the href's query. The duplicate being collapsed is the
- * one the head merge re-appends (the incoming bare-href link beside the busted
- * one), so the head would otherwise gain a link on every refresh. Keying on the
- * path alone would be wrong in the other direction: it would delete an author's
- * second, legitimately distinct link to the same file, such as a `media="print"`
- * sheet.
+ * So the cache-busted replacements go in first, BESIDE the current links
+ * (both apply meanwhile, the same rules twice), and the returned promise
+ * resolves once each has loaded or failed, or after `timeoutMs` for one that
+ * hangs. The caller swaps the markup in and then calls `commit()`, which drops
+ * each old link whose replacement loaded, plus any same-identity copy the head
+ * merge appended, keeping the replacement. A replacement that failed is
+ * removed and the old link kept (#936, #1400: never take the last working
+ * sheet down). One still pending at commit finishes the same way when it
+ * settles.
  *
  * @param {ParentNode} [root]  where to scan, defaulting to the whole document.
- *   Injectable so a browser test can scope itself to its own container.
  * @param {() => number} [now]  cache-buster source, injectable for tests.
- * @returns {Element[]} the replacement links, so a caller (a test) can await them.
+ * @param {number} [timeoutMs]  the longest to hold the swap for a stylesheet.
+ * @returns {Promise<{ links: Element[], commit: () => void }>}
  */
-export function refreshStyles(root, now) {
+export function preloadStyles(root, now, timeoutMs) {
   const scope = root || (typeof document !== 'undefined' ? document : null);
-  if (!scope) return [];
+  const limit = typeof timeoutMs === 'number' ? timeoutMs : 10000;
+  if (!scope) return Promise.resolve({ links: [], commit: function () {} });
   const stamp = now || Date.now;
   /** @type {Record<string, { el: Element, url: URL }>} */
   const kept = Object.create(null);
-  const links = [].slice.call(scope.querySelectorAll('link[rel~="stylesheet"][href]'));
-  for (const el of links) {
+  const current = [].slice.call(scope.querySelectorAll('link[rel~="stylesheet"][href]'));
+  for (const el of current) {
     let url;
     try { url = new URL(el.getAttribute('href'), location.href); } catch (_) { continue; }
     if (url.origin !== location.origin) continue;
@@ -57,7 +60,21 @@ export function refreshStyles(root, now) {
     if (kept[key]) { if (el.parentNode) el.parentNode.removeChild(el); continue; }
     kept[key] = { el, url };
   }
-  const added = [];
+  let committed = false;
+  /** @type {Array<{ key: string, old: Element, next: Element, state: string }>} */
+  const pairs = [];
+  // Drop every other copy of this sheet (the old link, a copy the head merge
+  // re-appended) so exactly the replacement is left.
+  const settleLoaded = function (pair) {
+    const links = [].slice.call(scope.querySelectorAll('link[rel~="stylesheet"][href]'));
+    for (const el of links) {
+      if (el === pair.next) continue;
+      let url;
+      try { url = new URL(el.getAttribute('href'), location.href); } catch (_) { continue; }
+      if (url.origin === location.origin && identityKey(el, url) === pair.key && el.parentNode) el.parentNode.removeChild(el);
+    }
+  };
+  const waits = [];
   for (const key of Object.keys(kept)) {
     const old = kept[key].el;
     const url = kept[key].url;
@@ -65,17 +82,34 @@ export function refreshStyles(root, now) {
     url.searchParams.set('__webjs_dev', String(stamp()));
     const next = /** @type {Element} */ (old.cloneNode(false));
     next.setAttribute('href', url.pathname + url.search);
-    next.addEventListener('load', function () {
-      if (old.parentNode) old.parentNode.removeChild(old);
-    });
-    next.addEventListener('error', function () {
-      // Keep the sheet that still works rather than the one that just failed.
-      if (next.parentNode) next.parentNode.removeChild(next);
-    });
+    const pair = { key, old, next, state: 'pending' };
+    pairs.push(pair);
+    waits.push(new Promise(function (resolve) {
+      next.addEventListener('load', function () {
+        pair.state = 'load';
+        if (committed) settleLoaded(pair);
+        resolve(undefined);
+      });
+      next.addEventListener('error', function () {
+        pair.state = 'error';
+        if (next.parentNode) next.parentNode.removeChild(next);
+        resolve(undefined);
+      });
+    }));
     old.parentNode.insertBefore(next, old.nextSibling);
-    added.push(next);
   }
-  return added;
+  const commit = function () {
+    committed = true;
+    for (const pair of pairs) if (pair.state === 'load') settleLoaded(pair);
+  };
+  const links = pairs.map(function (p) { return p.next; });
+  if (!waits.length) return Promise.resolve({ links, commit });
+  return new Promise(function (resolve) {
+    let done = false;
+    const finish = function () { if (!done) { done = true; resolve({ links, commit }); } };
+    Promise.all(waits).then(finish);
+    setTimeout(finish, limit);
+  });
 }
 
 /**

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})`,

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;
+}