@webjsdev/server 0.8.63 → 0.8.65

package/src/dev/server.js

@@ -0,0 +1,322 @@
+import { existsSync } from 'node:fs';
+import { strongerVerdict } from '../dev-classify.js';
+import { watch as fsWatch } from 'node:fs/promises';
+import { relative } from 'node:path';
+import { createServer as createHttp1Server } from 'node:http';
+import { createRequestHandler } from './handler.js';
+import { readServerTimeoutsFromApp, readDevWatchPathsFromApp } from './config.js';
+import { defaultLogger } from '../logger.js';
+import { SseHub, makeShutdown, installProcessHandlers, DEV_BOOT_ID, serverRuntime } from '../listener-core.js';
+import { urlFromRequest } from '../forwarded.js';
+import { stripBasePath } from '../base-path.js';
+import { basePath } from '../importmap.js';
+import { attachWebSocket } from '../websocket.js';
+import { toWebRequest, sendWebResponse } from './helpers.js';
+
+function debounce(fn, ms) {
+  let t;
+  return (...args) => {
+    clearTimeout(t);
+    t = setTimeout(() => fn(...args), ms);
+  };
+}
+
+/**
+ * Start a WebJs HTTP server. Thin wrapper around `createRequestHandler`.
+ *
+ * Speaks plain HTTP/1.1. TLS termination + HTTP/2 to the browser is
+ * expected to be handled by a reverse proxy (PaaS edge, nginx, Caddy,
+ * etc.) sitting in front of this process. See the deployment docs for
+ * the recommended topology.
+ *
+/**
+ * Paths under the app root whose changes must NOT trigger a dev rebuild.
+ * `node_modules` / `.git` are noise. `.webjs/` is the framework's generated
+ * artefact dir (the #258 routes.d.ts and the vendor pin) that the dev server
+ * itself writes on startup and on every rebuild, so without this skip the
+ * write fires a watch event, triggers a rebuild, re-writes the file, and loops
+ * forever. `db/dev.db*` (the SQLite file + sidecars) and `db/migrations`
+ * (drizzle-kit output) churn during db:migrate. The `db/dev.db` branch is
+ * prefix-only (no trailing separator) so the `-journal` / `-wal` sidecars match
+ * too, while staying anchored to `db/dev.db` so a SOURCE file like
+ * `db/schema.server.ts` still triggers a reload. The others stay
+ * separator-anchored so an unrelated name like `node_modules.bak/foo` does not.
+ *
+ * @param {string} filename relative path from an fs.watch `event.filename`
+ * @returns {boolean} true when the change should be ignored
+ */
+export function shouldIgnoreWatchPath(filename) {
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(filename || '');
+}
+
+/**
+ * Install signal handlers that stop accepting new connections, close SSE
+ * clients, and exit once in-flight requests drain.
+ * @param {import('node:http').Server} server
+ * @param {Set<import('node:http').ServerResponse>} sseClients
+ * @param {import('../logger.js').Logger} logger
+ */
+/**
+ * Create a plain HTTP/1.1 server. WebJs deploys are expected to sit
+ * behind a reverse proxy (PaaS edge, nginx, Caddy, etc.) that handles
+ * TLS termination and speaks HTTP/2 to clients: Node's http2 module
+ * doesn't need to be involved on the framework side.
+ *
+ * @param {(req: any, res: any) => void} handler
+ */
+function makeHttpServer(handler) {
+  return createHttp1Server(handler);
+}
+
+/* ------------ helpers ------------ */
+
+/**
+ * The node:http listener shell: the original `startServer` socket path, now
+ * reading the shared `ListenerContext`. Bridges node `IncomingMessage` ->
+ * `Request` (`toWebRequest`) and `Response` -> `ServerResponse`
+ * (`sendWebResponse`), emits 103 Early Hints, and drives SSE + WS over node
+ * primitives, sharing the SSE registry + lifecycle wiring with the Bun shell.
+ * @param {import('../listener-types.js').ListenerContext} ctx
+ * @returns {{ server: import('node:http').Server, close: () => Promise<void> }}
+ */
+function startNodeListener(ctx) {
+  const { app, dev, compress, logger, hub, port, basePathStr, timeouts, watcherAbort } = ctx;
+
+  const server = makeHttpServer(async (req, res) => {
+    try {
+      const url = urlFromRequest(req);
+
+      // SSE: handled specially; doesn't fit the req→Response model. Match the
+      // base-path-stripped pathname so the reload stream answers at
+      // `<basePath>/__webjs/events` under a sub-path deploy (#256). With no
+      // basePath this is a pure pass-through (the bare path still matches).
+      if (stripBasePath(url.pathname, basePathStr) === '/__webjs/events') {
+        if (!dev) { res.writeHead(404); res.end(); return; }
+        res.writeHead(200, {
+          'content-type': 'text/event-stream',
+          'cache-control': 'no-cache',
+          connection: 'keep-alive',
+        });
+        // `retry: 300` shrinks the browser's EventSource reconnect backoff from
+        // its ~3s default so a reconnect after a `node --watch` restart happens
+        // promptly. The `hello` data is a per-process boot id (#893): the client
+        // reloads on a reconnect ONLY when it changes (a real restart), so a
+        // transient reconnect never triggers a spurious reload.
+        res.write(`retry: 300\nevent: hello\ndata: ${DEV_BOOT_ID}\n\n`);
+        // Register a node client wrapper in the shared hub: the fanout + keepalive
+        // live in SseHub; only the transport write (res.write / res.end) is local.
+        const client = {
+          send: (s) => { try { res.write(s); } catch {} },
+          close: () => { try { res.end(); } catch {} },
+        };
+        hub.add(client);
+        // Replay an unresolved dev error (#264) so a tab that connects AFTER the
+        // breaking edit (e.g. opened via a fresh navigation) still shows the
+        // overlay, not only the tab that was open when the error fired.
+        const pending = app.getLastDevError?.();
+        if (pending) {
+          try { res.write(`event: webjs-error\ndata: ${JSON.stringify(pending)}\n\n`); } catch {}
+        }
+        res.socket?.on('close', () => hub.remove(client));
+        return;
+      }
+
+      // 103 Early Hints: before running SSR, send preload hints for the
+      // page's module URLs so the browser can begin fetching them while
+      // the server is still computing the body. Skipped in dev (file churn
+      // would send stale URLs after rebuilds) and for non-GET/HEAD.
+      if (
+        !dev &&
+        (req.method === 'GET' || req.method === 'HEAD') &&
+        typeof res.writeEarlyHints === 'function'
+      ) {
+        const match = app.routeFor(url.pathname);
+        if (match && match.moduleUrls.length) {
+          try {
+            res.writeEarlyHints({
+              link: match.moduleUrls.map((u) => `<${u}>; rel=modulepreload`),
+            });
+          } catch (e) {
+            logger.warn('writeEarlyHints failed', { err: String(e) });
+          }
+        }
+      }
+
+      const webReq = toWebRequest(req, url);
+      const resp = await app.handle(webReq);
+      await sendWebResponse(res, resp, req, { compress });
+    } catch (e) {
+      logger.error('request pipeline threw', { err: e instanceof Error ? e.stack : String(e) });
+      if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain' });
+      res.end(dev && e instanceof Error ? `webjs error: ${e.stack}` : 'Internal server error');
+    }
+  });
+
+  // node:http built-in timeouts: `requestTimeout` bounds the time to receive the
+  // WHOLE request, `headersTimeout` just the headers (kept strictly under
+  // requestTimeout so it actually fires), `keepAliveTimeout` the idle window
+  // before a kept-alive socket is closed.
+  server.requestTimeout = timeouts.requestTimeout;
+  server.headersTimeout = timeouts.headersTimeout;
+  server.keepAliveTimeout = timeouts.keepAliveTimeout;
+
+  // WebSocket upgrade handling: any route.js that exports `WS` becomes a
+  // 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();
+  });
+
+  const closeServer = () => new Promise((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve(undefined)));
+  });
+  const shutdown = makeShutdown({ closeServer, hub, logger });
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+
+  // 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 }));
+
+  return {
+    server,
+    close: () => new Promise((r) => {
+      if (watcherAbort) watcherAbort.abort();
+      // Clear the shared SSE keepalive timer so repeated startServer/close cycles
+      // (e.g. across a test run) don't accumulate live intervals.
+      hub.closeAll();
+      server.close(() => r());
+    }),
+  };
+}
+
+/**
+ * The core request → response pipeline, minus middleware.
+ * @param {Request} req
+ * @param {{state: any, appDir: string, coreDir: string, dev: boolean}} ctx
+ */
+/**
+ * @param {{
+ *   appDir: string,
+ *   port?: number,
+ *   dev?: boolean,
+ *   compress?: boolean,
+ *   logger?: import('../logger.js').Logger,
+ *   onError?: (error: unknown, ctx: { request: Request, requestId: string|null, phase: string }) => void,
+ * }} opts
+ */
+export async function startServer(opts) {
+  const dev = !!opts.dev;
+  const port = opts.port ?? 8080;
+  // Compression default: on in prod, off in dev (cheaper to debug raw bytes).
+  const compress = opts.compress ?? !dev;
+  const logger = opts.logger || defaultLogger({ dev });
+
+  // Runtime-neutral SSE registry + fanout (shared by the node:http and Bun.serve
+  // shells via listener-core.js, so live-reload + the dev error overlay behave
+  // identically on both). Built before the handler so its onReload / onDevError
+  // callbacks can fan out through it.
+  const hub = new SseHub();
+  let app;
+  try {
+    app = await createRequestHandler({
+      ...opts,
+      logger,
+      onReload: (verdict) => hub.reload(verdict),
+      // Dev error overlay (#264): push a frame to every open tab over the SAME
+      // SSE channel. A distinct `webjs-error` event name (NOT `error`, which is
+      // EventSource's native connection-error event) carries the JSON frame.
+      onDevError: (frame) => hub.devError(frame),
+    });
+  } catch (e) {
+    // The hub starts its keepalive interval in its constructor (before this
+    // await), so a boot failure must clear it rather than leak a live timer.
+    hub.closeAll();
+    throw e;
+  }
+
+  /** @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.
+    //
+    // fs.watch returns relative paths in event.filename. `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
+    // 80ms debounce window, so hold the STRONGEST verdict of the window and
+    // hand it to the rebuild. Same rule as the browser relay's cross-batch
+    // accumulation, for the same reason: a window mixing a page edit and a
+    // component edit is a component edit, and taking the last one would morph
+    // fresh markup onto the old component class.
+    /** @type {import('../dev-classify.js').ReloadVerdict | null} */
+    let pendingVerdict = null;
+    const rebuild = debounce(() => {
+      const v = pendingVerdict;
+      pendingVerdict = null;
+      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;
+          // 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;
+          pendingVerdict = strongerVerdict(pendingVerdict, app.classifyWatchPath(filename, root));
+          rebuild();
+        }
+      } catch (err) {
+        if (err && /** @type any */(err).name !== 'AbortError') {
+          logger.warn({ err }, `file watcher exited (${root})`);
+        }
+      }
+    };
+    watchRoot(app.appDir);
+    // Extra roots the app reads from OUTSIDE its appDir (#894): repo-root content
+    // dirs (blog markdown, data fixtures) the recursive appDir watch can't see.
+    // Opt-in via `webjs.dev.watch`; each funnels into the same debounced rebuild.
+    const extraWatch = (await readDevWatchPathsFromApp(app.appDir)).filter((p) => existsSync(p));
+    for (const root of extraWatch) watchRoot(root);
+    if (extraWatch.length) logger.info?.(`[webjs] also watching ${extraWatch.length} extra dev path(s): ${extraWatch.join(', ')}`);
+  }
+
+  // Inbound server timeouts (issue #237). On node these are the node:http
+  // built-ins; on Bun the node `requestTimeout` maps to Bun's single
+  // `idleTimeout`. Defends against slowloris and hung connections. Overridable
+  // via `webjs.requestTimeoutMs` / `headersTimeoutMs` / `keepAliveTimeoutMs` in
+  // package.json or the matching WEBJS_*_MS env vars; `0` disables that timeout.
+  const timeouts = await readServerTimeoutsFromApp(app.appDir);
+
+  // The shared context both listener shells consume. The transport-specific glue
+  // (node:http `res.write`, Bun.serve streaming Response) lives in each shell;
+  // the SSE registry, the live-reload path predicate, the WS module loader, and
+  // the lifecycle wiring are shared via listener-core.js so the shells can't drift.
+  /** @type {import('../listener-types.js').ListenerContext} */
+  const ctx = { app, dev, compress, logger, hub, port, basePathStr: basePath(), timeouts, watcherAbort };
+
+  // Pick the adapter by runtime. Bun is Request/Response-native, so its shell
+  // 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);
+  }
+  return startNodeListener(ctx);
+}

package/src/dev-classify.js

@@ -0,0 +1,174 @@
+/**
+ * Classify a dev-watcher file change into a live-reload verdict (#1398).
+ *
+ * Every dev edit used to produce a full page reload: the page blinks, hydrated
+ * component state resets, scroll position is lost. For an edit to a page, a
+ * layout, or a server-only module that is heavier than necessary, because pages
+ * and layouts never hydrate. Their function runs only on the server, so freshly
+ * rendered server HTML is the complete truth for them and nothing in the
+ * browser can be stale after a re-render. Such a change can be applied in place
+ * through the client router instead of reloading.
+ *
+ * The decision is made HERE, on the server, and the browser is a dumb executor
+ * of the verdict it is handed (the shape Vite and Next.js both settle on). It
+ * is kept in its own module, with no server state and no imports, so the ladder
+ * is unit-testable without booting anything.
+ *
+ * The classification walks the MODULE GRAPH, never the path shape. A path-shape
+ * heuristic ("anything under `app/**` named `page.ts` can morph") is wrong in
+ * both directions and neither failure is exotic:
+ *
+ * - A page that imports a client-effecting non-component util SHIPS WHOLE (the
+ *   import-only rule in `component-elision.js`, #605 / #963). Editing it changes
+ *   browser-bound JS, so it must reload despite being a page.
+ * - A helper under `modules/<feature>/utils/` imported by both a page and a
+ *   component is a component edit by reachability, and its path says nothing.
+ *
+ * Everything the server cannot classify is a full reload. A wrong morph is a
+ * broken page; a wrong reload is a flash.
+ */
+
+/**
+ * The three verdicts, STRONGEST FIRST. The index in this array IS the strength
+ * order, which is what `strongerVerdict` compares and what lets a batch of
+ * changes collapse to the strongest verdict it contains rather than the last.
+ *
+ * - `reload`: a component module, anything transitively reaching one, or any
+ *   path the server cannot place. The browser does `location.reload()`.
+ * - `shell`: a layout module, or a server-only module. The browser re-renders
+ *   the current URL and replaces the whole body, preserving scroll.
+ * - `page`: a page module and nothing else. The browser re-renders the current
+ *   URL and morphs the deepest shared boundary, preserving scroll AND the
+ *   hydrated state of components outside the changed region.
+ *
+ * @type {readonly ['reload', 'shell', 'page']}
+ */
+export const RELOAD_VERDICTS = /** @type {const} */ (['reload', 'shell', 'page']);
+
+/**
+ * @typedef {{ v: 'page' | 'shell' | 'reload', by: string, why: string }} ReloadVerdict
+ */
+
+/**
+ * The stronger of two verdicts, treating `null` / `undefined` as weakest and an
+ * unrecognised one as `reload` (fail safe, never fail open).
+ *
+ * Used twice for the same reason. The watcher can see several files change
+ * inside one 80ms debounce window, and the browser relay coalesces a burst of
+ * signals into ONE emitted reload (#1397). In both places a batch mixing a page
+ * edit and a component edit is a COMPONENT edit, so taking the last verdict
+ * would leave the old component class running against fresh markup.
+ *
+ * @param {ReloadVerdict | null | undefined} a
+ * @param {ReloadVerdict | null | undefined} b
+ * @returns {ReloadVerdict | null}
+ */
+export function strongerVerdict(a, b) {
+  if (!a) return b || null;
+  if (!b) return a;
+  return verdictRank(a.v) <= verdictRank(b.v) ? a : b;
+}
+
+/**
+ * Strength rank of a verdict name. An unknown name ranks as `reload` (0), the
+ * strongest, so a corrupt or future value can only ever over-reload.
+ * @param {string} v
+ * @returns {number}
+ */
+function verdictRank(v) {
+  const i = RELOAD_VERDICTS.indexOf(/** @type any */ (v));
+  return i === -1 ? 0 : i;
+}
+
+/**
+ * Classify one changed absolute path into a reload verdict.
+ *
+ * The ladder, first match wins:
+ *
+ * 1. The analysis has NEVER completed, so nothing is known yet. Fail safe. This
+ *    mirrors Vite's pessimistic seed (`needFullReload = modules.length === 0`).
+ *    In practice this is the window between boot and the first request.
+ *
+ *    `analysisReady` deliberately means "the sets are POPULATED", not "they are
+ *    current". A rebuild invalidates the lazy analysis and nothing re-warms it
+ *    until an HTTP request arrives, while the relay defers that request by its
+ *    2000ms quiet window (#1397), which is longer than the measured inter-save
+ *    gap. Reading currency here would therefore turn the feature off for every
+ *    edit after the first in a burst. Classifying against the previous build's
+ *    graph is the intended behaviour, and it is conservative in the right
+ *    direction: a file the stale graph has never seen falls to rung 6 and
+ *    reloads.
+ * 2. The path is outside `appDir`. The watcher only fires for `appDir` plus the
+ *    opt-in `webjs.dev.watch` roots (#894), and a file outside `appDir` is
+ *    content the server reads at render time, never a browser module. It can
+ *    change what any layout renders, so it takes the whole-body `shell` swap.
+ * 3. The path is in the SHIPPED closure. This is the transitive answer and the
+ *    one that matters: the browser holds this module, so the page must reload.
+ * 4. The path is a page module. Morphable.
+ * 5. The path is somewhere else in the module graph (a layout, a server-only
+ *    util, a `.server.*` file reachable only from a page). Server-only by
+ *    elimination, so `shell`.
+ * 6. Anything else. A brand-new file, a deleted file, and every `public/` asset
+ *    land here. `public/` is not in the module graph at all, so the server
+ *    cannot tell what the file IS or what depends on it, and most of what lives
+ *    there (an image, a font, a service worker, a hand-written script) is
+ *    something no amount of re-rendering picks up. The refresh does re-request
+ *    the page's stylesheets, so a `public/` CSS edit alone would now survive a
+ *    morph, but that is one knowable case inside a rung whose whole point is
+ *    that the file is unknowable.
+ *
+ * Note what step 3 sweeps in deliberately. A `'use server'` action file
+ * imported by a SHIPPING component is inside the closure (the graph keeps a
+ * `.server.*` node and stops at it), so editing it reloads. That is correct
+ * rather than merely conservative, because adding an export to that file
+ * changes the generated RPC stub the browser holds. The same action imported
+ * only by a page falls to step 5 and gets `shell`.
+ *
+ * @param {string} abs  absolute path of the changed file
+ * @param {object} ctx
+ * @param {string} ctx.appDir
+ * @param {Set<string>} ctx.shippedFiles  transitive closure of every module the browser can load
+ * @param {Set<string>} ctx.graphFiles  every app source file the module graph walked
+ * @param {Set<string>} ctx.pageFiles  every `page.{js,ts}` on the route table
+ * @param {boolean} ctx.analysisReady  false before the first analysis completes
+ * @param {string} [ctx.sep]  path separator, injectable so the ladder is testable off-platform
+ * @returns {ReloadVerdict}
+ */
+export function classifyChangedPath(abs, ctx) {
+  const sep = ctx.sep || '/';
+  const by = relativize(abs, ctx.appDir, sep);
+  if (!abs) return { v: 'reload', by: '', why: 'no-path' };
+  if (!ctx.analysisReady) return { v: 'reload', by, why: 'analysis-cold' };
+  if (!isUnder(abs, ctx.appDir, sep)) return { v: 'shell', by, why: 'extra-watch-root' };
+  if (ctx.shippedFiles && ctx.shippedFiles.has(abs)) return { v: 'reload', by, why: 'ships-to-browser' };
+  if (ctx.pageFiles && ctx.pageFiles.has(abs)) return { v: 'page', by, why: 'page-module' };
+  if (ctx.graphFiles && ctx.graphFiles.has(abs)) return { v: 'shell', by, why: 'server-only-module' };
+  return { v: 'reload', by, why: 'unknown-path' };
+}
+
+/**
+ * True when `abs` sits inside `dir`. The `dir + sep` boundary is what stops a
+ * sibling directory sharing a prefix (`/app-old` against `/app`) from being
+ * read as containment, the same guard `asset-hash` uses.
+ * @param {string} abs
+ * @param {string} dir
+ * @param {string} sep
+ */
+function isUnder(abs, dir, sep) {
+  if (!dir) return false;
+  return abs === dir || abs.startsWith(dir.endsWith(sep) ? dir : dir + sep);
+}
+
+/**
+ * The app-relative path, or the absolute path when it is not under `appDir`.
+ * Diagnostic only: it rides the SSE frame as `by` so a dev can see which file
+ * produced a verdict, and nothing branches on it.
+ * @param {string} abs
+ * @param {string} dir
+ * @param {string} sep
+ */
+function relativize(abs, dir, sep) {
+  if (!abs) return '';
+  if (!isUnder(abs, dir, sep)) return abs;
+  return abs.slice(dir.endsWith(sep) ? dir.length : dir.length + 1);
+}

package/src/dev-reload-worker.js

@@ -2,17 +2,86 @@
  * The dev live-reload SharedWorker relay (#887), the BROWSER half. Kept as a
  * standalone browser-safe module (no node imports) so the served worker inlines
  * the EXACT source a browser test drives, with no drift, the same pattern as
- * `dev-overlay.js` (#264). `reloadWorkerJs` in dev.js reads this file, strips
- * the `export` keyword, and appends a
- * `startReloadWorker(self, EventSource, '<eventsUrl>')` call.
+ * `dev-overlay.js` (#264).
+ *
+ * BOTH served dev scripts inline this file, `export`-stripped. `reloadWorkerJs`
+ * appends a `startReloadWorker(self, EventSource, '<eventsUrl>')` call for the
+ * SharedWorker, and since #1397 `reloadClientJs` inlines it too, so the per-tab
+ * fallback runs this same relay over a shim port instead of a second copy of
+ * the boot-id rule and the reload debounce.
  *
  * One SharedWorker is shared across every tab of the origin (a SharedWorker is
  * keyed by its script URL), so it holds the ONE `EventSource` to
  * `/__webjs/events` and fans each `reload` / `webjs-error` out to every tab over
  * its `MessagePort`. Tab count never touches the browser's per-host HTTP/1.1
  * connection cap, which the per-tab `EventSource` it replaces used to exhaust.
+ */
+
+/**
+ * Reload coalescing (#1397). An agent saves several files a second or two
+ * apart, and EACH save produces TWO reload signals: the in-process `reload`
+ * frame from the fs.watch rebuild, then a changed boot id when the browser
+ * reconnects to the process `node --watch` restarted (measured 429ms apart, and
+ * 1071ms between one save's reconnect and the next save's in-process frame).
+ * Acting on every one reloads into a server that is about to be killed again,
+ * which is how the page ends up unstyled.
+ *
+ * 2000ms is above the measured 1071ms inter-save gap so a realistic burst
+ * collapses to one reload, and deliberately not NEAR it, since a window close
+ * to that gap fires just as the next restart begins. It also lands just past
+ * the 1900ms analysis warm measured on the website app, which is the useful
+ * place for it: the restarted process kicks off `warmup()` as soon as it
+ * listens, so the wait overlaps work the reload request would have blocked on
+ * anyway and the reload arrives at a server that has finished warming.
+ */
+export const RELOAD_QUIET_MS = 2000;
+
+/**
+ * The longest a reload is ever held, measured from the FIRST signal of a batch
+ * (#1397). A quiet window alone would freeze the page on stale content for a
+ * whole agent burst, so a sustained burst still repaints at least this often.
+ * 2.5x the quiet window, so it never fires for an ordinary pair of edits.
+ */
+export const RELOAD_MAX_HOLD_MS = 5000;
+
+/**
+ * Verdict strength, STRONGEST FIRST (#1398). Mirrors `RELOAD_VERDICTS` in the
+ * server's `dev-classify.js`; duplicated rather than imported because this file
+ * is inlined verbatim into two served browser scripts and must stay
+ * import-free.
+ *
+ * A batch collapses to ONE emitted reload, so it must take the STRONGEST
+ * verdict in the batch and never the last one: a burst mixing a page edit and a
+ * component edit is a component edit, and morphing it would leave the old
+ * component class running against fresh markup.
+ */
+export const VERDICT_STRENGTH = ['reload', 'shell', 'page'];
+
+/**
+ * Resolve an SSE `reload` frame's `data` to a verdict name.
  *
- * @param {{ onconnect: any }} scope  the worker global (`self`)
+ * ANY failure resolves to `reload`: an absent payload, malformed JSON, a
+ * non-object, a `v` outside the three literals, or the legacy bare `data: now`.
+ * That is what makes the wire-format change safe in both directions between a
+ * long-running browser tab and a restarted server, since the worst a skew can
+ * produce is the full reload that was the behaviour before this existed.
+ *
+ * @param {string} data
+ * @returns {string} one of VERDICT_STRENGTH
+ */
+export function parseVerdict(data) {
+  try {
+    const o = JSON.parse(data);
+    if (o && typeof o === 'object' && VERDICT_STRENGTH.indexOf(o.v) !== -1) return o.v;
+  } catch (_) { /* fall through to the fail-safe */ }
+  return 'reload';
+}
+
+/**
+ * @param {{ onconnect: any, setTimeout?: any, clearTimeout?: any }} scope  the
+ *   worker global (`self`), or a plain shim object for the per-tab fallback.
+ *   Timers are read off it when it has them, which is what lets a browser test
+ *   drive the debounce on a fake clock.
  * @param {new (url: string) => any} EventSourceCtor  the `EventSource` constructor
  * @param {string} eventsUrl  the base-path-aware `/__webjs/events` URL
  */
@@ -24,6 +93,13 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
   /** @type {string | null} the last-seen per-process boot id (#893) */
   let lastBoot = null;
 
+  // Timers come from the worker global when it has them (the real SharedWorker
+  // scope does, and so does a tab running the per-tab fallback), else the
+  // ambient globals. Reading them off `scope` is what lets the browser test
+  // drive a fake clock and keep its assertions synchronous, and calling them as
+  // `timers.setTimeout(...)` keeps `this` the global in a real browser.
+  const timers = scope && typeof scope.setTimeout === 'function' ? scope : globalThis;
+
   // A MessagePort has no reliable close event, so prune a port when a post to it
   // throws (a closed tab). Some browsers silently no-op instead of throwing,
   // leaving a dead port in the set, but that is a harmless dev-only no-op and
@@ -34,6 +110,43 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
     }
   }
 
+  // The ONE debounced reload emitter (#1397). Two timers rather than a clock:
+  // the quiet timer is re-armed by every signal, the cap timer is armed once
+  // per batch and NEVER re-armed, so the cap measures from the first signal of
+  // the batch instead of sliding with the burst. Whichever fires first emits
+  // and cancels the other, which also starts a fresh batch.
+  /** @type {any} */ let quietTimer = null;
+  /** @type {any} */ let capTimer = null;
+
+  /** @type {string} the strongest verdict seen in the CURRENT batch (#1398) */
+  let batchVerdict = 'page';
+
+  function emitReload() {
+    if (quietTimer !== null) { timers.clearTimeout(quietTimer); quietTimer = null; }
+    if (capTimer !== null) { timers.clearTimeout(capTimer); capTimer = null; }
+    const v = batchVerdict;
+    // Resetting HERE rather than in requestReload is load-bearing: emitReload is
+    // the single place a batch ends, and it is reached from both timers.
+    batchVerdict = 'page';   // a fresh batch starts at the weakest verdict
+    fanout({ type: 'reload', verdict: v });
+  }
+
+  /** Strength rank; an unrecognised name ranks strongest, so it can only ever
+   * over-reload. @param {string} v */
+  function rank(v) {
+    const i = VERDICT_STRENGTH.indexOf(v);
+    return i === -1 ? 0 : i;
+  }
+
+  /** @param {string} verdict */
+  function requestReload(verdict) {
+    // Lower rank is stronger, so keep the minimum across the batch.
+    if (rank(verdict) < rank(batchVerdict)) batchVerdict = VERDICT_STRENGTH[rank(verdict)];
+    if (quietTimer !== null) timers.clearTimeout(quietTimer);
+    quietTimer = timers.setTimeout(emitReload, RELOAD_QUIET_MS);
+    if (capTimer === null) capTimer = timers.setTimeout(emitReload, RELOAD_MAX_HOLD_MS);
+  }
+
   const es = new EventSourceCtor(eventsUrl);
 
   // The `hello` frame fires on every (re)connect and carries the server's
@@ -45,13 +158,26 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
   // tab still gates it on a readiness probe). A transient reconnect (sleep/wake,
   // a network blip, a tab evicted at the HTTP/1.1 cap) reconnects to the SAME
   // process with the SAME id, so it never reloads. The first `hello` only
-  // records the baseline.
+  // records the baseline. Both reload paths route through the ONE debounced
+  // emitter above (#1397), since a burst of edits produces one signal of each
+  // kind per save.
+  //
+  // A changed boot id is unconditionally a FULL RELOAD (#1398), and it is NOT a
+  // "no verdict" signal to be overridden by a lighter one already in the batch.
+  // A restart carries no filename, so nothing survives it to classify, and a
+  // burst can hold a page edit whose in-process frame was delivered next to a
+  // component edit whose frame died with the old process. In that burst the
+  // changed boot id is the component edit's ONLY trace.
   es.addEventListener('hello', (e) => {
-    if (lastBoot !== null && e.data !== lastBoot) fanout({ type: 'reload' });
+    if (lastBoot !== null && e.data !== lastBoot) requestReload('reload');
     lastBoot = e.data;
   });
 
-  es.addEventListener('reload', () => { lastError = null; fanout({ type: 'reload' }); });
+  // The cached error is cleared IMMEDIATELY, not on the debounced emit: a tab
+  // connecting during the pending window must not be replayed an overlay for an
+  // error the rebuild already fixed. `webjs-error` itself stays undebounced,
+  // since an overlay has to appear at once and it is not a reload.
+  es.addEventListener('reload', (e) => { lastError = null; requestReload(parseVerdict(e.data)); });
   es.addEventListener('webjs-error', (e) => { lastError = e.data; fanout({ type: 'webjs-error', data: e.data }); });
 
   scope.onconnect = (e) => {