@webjsdev/server 0.8.69 → 0.8.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.69",
+  "version": "0.8.71",
   "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/config.js

@@ -319,13 +319,13 @@ export async function readDevWatchPathsFromApp(appDir) {
 
 /**
  * The dev tooling switches in `webjs.dev` (#1504): `embedOrigins` (the embed
- * bridge, #1498) and `sourceLocations` (#1499). Raw values; the env overrides
+ * bridge, #1498), `sourceLocations` (#1499) and `reloadIdle` (#1507). Raw values; the env overrides
  * and validation live with each feature (`resolveEmbedOrigins`,
  * `sourceLocationsRequested`). A missing or unreadable package.json is both
  * off.
  *
  * @param {string} appDir
- * @returns {Promise<{ embedOrigins: unknown, sourceLocations: unknown }>}
+ * @returns {Promise<{ embedOrigins: unknown, sourceLocations: unknown, reloadIdle: unknown }>}
  */
 export async function readDevToolingFromApp(appDir) {
   let dev;
@@ -335,8 +335,8 @@ export async function readDevToolingFromApp(appDir) {
   } catch {
     dev = undefined;
   }
-  if (!dev || typeof dev !== 'object') return { embedOrigins: undefined, sourceLocations: undefined };
-  return { embedOrigins: dev.embedOrigins, sourceLocations: dev.sourceLocations };
+  if (!dev || typeof dev !== 'object') return { embedOrigins: undefined, sourceLocations: undefined, reloadIdle: undefined };
+  return { embedOrigins: dev.embedOrigins, sourceLocations: dev.sourceLocations, reloadIdle: dev.reloadIdle };
 }
 
 /**

package/src/dev/handler.js

@@ -67,6 +67,8 @@ import {
 import {
   exists, kebab, resolveRequestId, shouldAccessLog, loadAppEnv, collectRouteModules,
   appTopLevelDirs, locateCoreDir,
+  setReloadIdleMs,
+  resolveReloadIdleMs,
 } from './helpers.js';
 import {
   handleCore, loadMiddleware, tryServeFrameworkStatic, tryServePublicAsset,
@@ -223,9 +225,13 @@ export async function createRequestHandler(opts) {
   // neither injects the script nor relaxes a framing header.
   // `webjs.dev.embedOrigins` in package.json is the default (#1504); a set
   // env var replaces it for one run.
-  const devTooling = dev ? await readDevToolingFromApp(appDir) : { embedOrigins: undefined, sourceLocations: undefined };
+  const devTooling = dev ? await readDevToolingFromApp(appDir) : { embedOrigins: undefined, sourceLocations: undefined, reloadIdle: undefined };
   const embedOriginsValue = dev ? resolveEmbedOrigins(process.env.WEBJS_EMBED_ORIGINS, devTooling.embedOrigins) : [];
   setEmbedOrigins(embedOriginsValue);
+  // Live-reload idle close (#1507): `webjs.dev.reloadIdle` seconds, or a set
+  // `WEBJS_DEV_RELOAD_IDLE`. Off by default; for a host that counts an open
+  // request as activity, so it can sleep while a preview tab sits open.
+  setReloadIdleMs(dev ? resolveReloadIdleMs(process.env.WEBJS_DEV_RELOAD_IDLE, devTooling.reloadIdle) : 0);
 
   const coreDir = locateCoreDir(appDir);
   // Switch the importmap between dist/ bundles and src/ per-file
@@ -810,7 +816,7 @@ export async function createRequestHandler(opts) {
           // path skipped it. This runs on the first warm AND after every rebuild,
           // so the pruned map is the single source of truth.
           const reachable = await scan();
-          ({ imports, integrity } = prunePinToReachable(imports, integrity, reachable));
+          ({ imports, integrity } = prunePinToReachable(imports, integrity, reachable, { appDir }));
         }
         await setVendorEntries(imports, integrity);
         return v.ok;

package/src/dev/helpers.js

@@ -368,6 +368,32 @@ const DEV_STYLES_SRC = readFileSync(new URL('../dev-styles.js', import.meta.url)
  * @param {string} bp the normalized base path (`''` = no-op)
  * @returns {string}
  */
+/** Idle close for the reload stream, in ms (#1507); 0 = off. Set by the dev handler. */
+let _reloadIdleMs = 0;
+
+/**
+ * Record `webjs.dev.reloadIdle` / `WEBJS_DEV_RELOAD_IDLE` (#1507) for the served
+ * reload scripts. A module-level switch like `setEmbedOrigins`, set once per
+ * dev handler.
+ * @param {number} ms
+ */
+export function setReloadIdleMs(ms) {
+  _reloadIdleMs = Number.isFinite(ms) && ms > 0 ? Math.round(ms) : 0;
+}
+
+/**
+ * Resolve the reload idle close in ms: a set `WEBJS_DEV_RELOAD_IDLE` (seconds)
+ * wins over `webjs.dev.reloadIdle` (seconds); anything not a positive number
+ * is off.
+ * @param {string | undefined} envRaw
+ * @param {unknown} configured
+ * @returns {number}
+ */
+export function resolveReloadIdleMs(envRaw, configured) {
+  const raw = typeof envRaw === 'string' && envRaw.trim() !== '' ? Number(envRaw) : configured;
+  return typeof raw === 'number' && Number.isFinite(raw) && raw > 0 ? Math.round(raw * 1000) : 0;
+}
+
 export function reloadClientJs(bp) {
   // The overlay renderer uses textContent throughout (never innerHTML), so the
   // error message / code frame can never inject markup (#264). Served only in
@@ -471,8 +497,8 @@ function __webjsDirectEvents() {
   // the reload debounce (#1397). The shim scope has no setTimeout, so the relay
   // picks up the tab's own timers.
   const scope = {};
-  startReloadWorker(scope, EventSource, ${eventsUrl});
-  scope.onconnect({ ports: [{ start() {}, postMessage(m) {
+  startReloadWorker(scope, EventSource, ${eventsUrl}, { idleMs: ${_reloadIdleMs} });
+  const shim = { start() {}, postMessage(m) {
     // Nothing may throw out of here, and nothing may be silently dropped.
     //
     // The relay's fanout deletes a port whose postMessage throws, which is the
@@ -495,7 +521,52 @@ function __webjsDirectEvents() {
     } catch (_) {
       console.error('[webjs] dev reload handler threw', _);
     }
-  } }] });
+  } };
+  scope.onconnect({ ports: [shim] });
+  __webjsReportVisibility(function (msg) { if (shim.onmessage) shim.onmessage({ data: msg }); });
+}
+// Tell the relay whether this tab is on screen (#1507). The relay holds the
+// live-reload stream open only while some tab is visible, so a backgrounded
+// dev tab keeps no request in flight and sends nothing; it reopens on return
+// and its hello says whether an edit landed meanwhile. \`bye\` on pagehide
+// drops the tab outright, and a bfcache restore reports in again.
+function __webjsReportVisibility(send) {
+  // The state this page was rendered at (#1516). The relay compares it with
+  // the server's on connect and on every reconnect, so an edit whose reload
+  // frame was lost (a stream replaced at a host's wake, a fresh relay, a tab
+  // that connected after the fanout) still reloads this page.
+  // Sent again on a bfcache restore, since \`bye\` dropped this tab's entry.
+  function sendPage() {
+    try {
+      var metas = document.querySelectorAll('meta[name="webjs-dev-reload"]');
+      var meta = metas.length ? metas[metas.length - 1] : null;
+      if (!meta) return;
+      var page = JSON.parse(meta.getAttribute('content') || 'null');
+      if (page && typeof page.boot === 'string') send({ type: 'page', boot: page.boot, seq: typeof page.seq === 'number' ? page.seq : null });
+    } catch (_) { /* no usable state: the relay's own hello check still runs */ }
+  }
+  sendPage();
+  function report() {
+    try { send({ type: 'visibility', visible: document.visibilityState !== 'hidden' }); } catch (_) { /* relay gone */ }
+  }
+  document.addEventListener('visibilitychange', report);
+  addEventListener('pagehide', function () { try { send({ type: 'bye' }); } catch (_) { /* relay gone */ } });
+  addEventListener('pageshow', function (e) { if (e.persisted) { sendPage(); report(); } });
+  report();
+  // Interaction keeps an idle-closing stream (webjs.dev.reloadIdle) open and
+  // reopens a closed one, at most once a second. The dev embed bridge calls
+  // __webjsDevActivity for each host command, so a framing tool can resume it.
+  var lastActivity = 0;
+  function activity() {
+    var now = Date.now();
+    if (now - lastActivity < 1000) return;
+    lastActivity = now;
+    try { send({ type: 'activity' }); } catch (_) { /* relay gone */ }
+  }
+  ['pointerdown', 'pointermove', 'keydown', 'wheel', 'touchstart', 'focus'].forEach(function (t) {
+    addEventListener(t, activity, { capture: true, passive: true });
+  });
+  globalThis.__webjsDevActivity = activity;
 }
 try {
   if (typeof SharedWorker !== 'undefined') {
@@ -506,6 +577,7 @@ try {
       else if (m.type === 'webjs-error') __webjsApplyError(m.data);
     };
     w.port.start();
+    __webjsReportVisibility(function (msg) { w.port.postMessage(msg); });
   } else {
     __webjsDirectEvents();
   }
@@ -527,7 +599,7 @@ try {
 export function reloadWorkerJs(bp) {
   return `// webjs dev reload worker (one shared connection for all tabs)
 ${RELOAD_WORKER_SRC}
-startReloadWorker(self, EventSource, ${JSON.stringify(withBasePath('/__webjs/events', bp))});
+startReloadWorker(self, EventSource, ${JSON.stringify(withBasePath('/__webjs/events', bp))}, { idleMs: ${_reloadIdleMs} });
 `;
 }
 

package/src/dev/server.js

@@ -6,7 +6,8 @@ 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 { SseHub, makeShutdown, installProcessHandlers, serverRuntime, DEV_BOOT_ID } from '../listener-core.js';
+import { setDevReloadState } from '../dev-reload-state.js';
 import { urlFromRequest } from '../forwarded.js';
 import { stripBasePath } from '../base-path.js';
 import { basePath } from '../importmap.js';
@@ -102,9 +103,15 @@ function startNodeListener(ctx) {
         // 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.
+        res.write(hub.helloFrame());
+        // The stream is silent between events (#1507), so no socket timeout may
+        // reap it. node:http sets none by default, but an inherited or future
+        // one would close a live reload stream that is simply quiet, so it is
+        // switched off for this request alone.
+        req.setTimeout?.(0);
+        res.setTimeout?.(0);
+        // Register a node client wrapper in the shared hub: the fanout lives 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 {} },
@@ -189,8 +196,7 @@ function startNodeListener(ctx) {
     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.
+      // Close every open live-reload stream.
       hub.closeAll();
       server.close(() => r());
     }),
@@ -224,6 +230,9 @@ export async function startServer(opts) {
   // identically on both). Built before the handler so its onReload / onDevError
   // callbacks can fan out through it.
   const hub = new SseHub();
+  // Pages render the stream's state into a meta tag (#1516), so the relay can
+  // re-check a page against the server on every reconnect.
+  if (dev) setDevReloadState(() => ({ boot: DEV_BOOT_ID, seq: hub.seq }));
   let app;
   try {
     app = await createRequestHandler({
@@ -236,8 +245,6 @@ export async function startServer(opts) {
       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;
   }

package/src/dev-embed-client.js

@@ -297,6 +297,10 @@ export function installEmbedBridge(origins, opts) {
     var d = e.data;
     if (!d || typeof d !== 'object' || d.source !== 'webjs-embed-host') return;
     known = e.origin;
+    // A host command is activity: it reopens a live-reload stream the dev
+    // server closed for idleness (webjs.dev.reloadIdle, #1507), and an edit
+    // made meanwhile then reloads the page.
+    if (typeof win.__webjsDevActivity === 'function') { try { win.__webjsDevActivity(); } catch (_) { /* no reload client */ } }
     if (d.type === 'reload') {
       win.location.reload();
     } else if (d.type === 'navigate') {
@@ -319,6 +323,7 @@ export function installEmbedBridge(origins, opts) {
     } else if (d.type === 'inspect') {
       setInspect(d.enabled === true);
     }
+    // { type: 'resume' } needs nothing beyond the activity call above.
   });
 
   return {

package/src/dev-reload-state.js

@@ -0,0 +1,31 @@
+/**
+ * The live-reload state a dev page was rendered at (#1516).
+ *
+ * `startServer` owns the reload stream's `SseHub`, which knows this process's
+ * boot id and how many reload frames it has sent. SSR renders that pair into a
+ * `webjs-dev-reload` meta tag, and the reload client hands it to the relay, so
+ * on every reconnect the relay can tell whether the page on screen is behind
+ * the server even when the reload frame that would have said so was lost.
+ *
+ * A module-level provider, the same shape as the base path and the embed
+ * origins, because the head is rendered far from the listener. An embedded
+ * `createRequestHandler` with no `startServer` has no reload stream, so no
+ * provider is set and no meta tag is rendered.
+ */
+
+/** @type {(() => { boot: string, seq: number }) | null} */
+let provider = null;
+
+/**
+ * Set (or clear with null) the function that reports the current state.
+ * @param {(() => { boot: string, seq: number }) | null} fn
+ */
+export function setDevReloadState(fn) {
+  provider = typeof fn === 'function' ? fn : null;
+}
+
+/** The current `{ boot, seq }`, or null when there is no reload stream. */
+export function devReloadState() {
+  if (!provider) return null;
+  try { return provider(); } catch { return null; }
+}

package/src/dev-reload-worker.js

@@ -77,58 +77,135 @@ export function parseVerdict(data) {
   return 'reload';
 }
 
+/** First reconnect wait after the stream drops (#1507), doubled per failure. */
+export const RECONNECT_BASE_MS = 300;
+/** The longest wait between reconnect attempts (#1507). */
+export const RECONNECT_MAX_MS = 30000;
+
+/**
+ * Read a `hello` frame's data (#893, #1507): `{ boot, seq }` JSON, or the bare
+ * boot id an older server sends (seq unknown).
+ * @param {string} data
+ * @returns {{ boot: string, seq: number | null }}
+ */
+export function parseHello(data) {
+  try {
+    const o = JSON.parse(data);
+    if (o && typeof o === 'object' && typeof o.boot === 'string') {
+      return { boot: o.boot, seq: typeof o.seq === 'number' ? o.seq : null };
+    }
+  } catch (_) { /* a bare boot id */ }
+  return { boot: String(data), seq: null };
+}
+
 /**
+ * Whether a tab's page is behind the server (#1516). `page` is the
+ * `{ boot, seq }` the page was rendered at (the `webjs-dev-reload` meta tag),
+ * `boot` / `seq` what the server reports now. A different boot id is a
+ * restarted process; a different seq from the same process is an edit the page
+ * has not picked up. A missing seq on either side cannot say, so it is not
+ * stale (the boot id alone still decides).
+ * @param {{ boot: string, seq: number | null } | undefined} page
+ * @param {string | null} boot
+ * @param {number | null} seq
+ */
+export function pageIsStale(page, boot, seq) {
+  if (!page || boot === null) return false;
+  if (page.boot !== boot) return true;
+  return page.seq !== null && seq !== null && page.seq !== seq;
+}
+
+/** A reload frame's `seq` (#1507), or null when it carries none. @param {string} data */
+function reloadSeq(data) {
+  try {
+    const o = JSON.parse(data);
+    return o && typeof o.seq === 'number' ? o.seq : null;
+  } catch (_) { return null; }
+}
+
+/**
+ * Run the relay.
+ *
+ * The stream is open only while at least one tab is VISIBLE (#1507). Each tab
+ * reports `{ type: 'visibility', visible }` on `visibilitychange` and
+ * `{ type: 'bye' }` on `pagehide`; when the last visible tab goes away the
+ * relay closes its `EventSource`, so a backgrounded dev tab holds no request
+ * open and sends nothing, and it reopens the moment one becomes visible. An
+ * edit made meanwhile is not lost: the reopened stream's `hello` carries the
+ * server's boot id and reload `seq`, and a difference from what this relay last
+ * saw is a reload.
+ *
+ * Every reconnect also re-checks each tab against the state its PAGE was
+ * rendered at (#1516). A tab sends `{ type: 'page', boot, seq }` from the
+ * page's `webjs-dev-reload` meta tag when it connects. A frame emitted while no
+ * stream was there to carry it is gone: a host that holds the quiet stream
+ * across a suspend and closes it at the next wake swallows the reload the wake
+ * itself caused, a fresh relay has no previous hello to compare with, and a tab
+ * that connects after a reload was fanned out never got it. In each case the
+ * next hello (or the tab's own connect) shows the page is behind, and that tab
+ * reloads.
+ *
+ * The browser's own EventSource retry is replaced by an explicit one with
+ * backoff (300ms doubling to 30s, reset by the next `hello`), so a server that
+ * is gone for a while is probed less and less often instead of every 300ms.
+ *
  * @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
+ * @param {{ idleMs?: number }} [opts]  `idleMs` (#1507, from `webjs.dev.reloadIdle`
+ *   / `WEBJS_DEV_RELOAD_IDLE`): close the stream after this long with no edit
+ *   and no interaction in any tab, and reopen on the next interaction. `0` (the
+ *   default) keeps it open while a tab is visible.
  */
-export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
-  /** @type {Set<any>} */
-  const ports = new Set();
+export function startReloadWorker(scope, EventSourceCtor, eventsUrl, opts) {
+  const idleMs = opts && opts.idleMs > 0 ? opts.idleMs : 0;
+  /** @type {Map<any, boolean>} each connected tab's port, and whether it is visible */
+  const ports = new Map();
+  /** @type {Map<any, { boot: string, seq: number | null }>} the state each tab's page reflects (#1516) */
+  const pages = new Map();
   /** @type {string | null} the last error frame, cached for late-joining tabs */
   let lastError = null;
   /** @type {string | null} the last-seen per-process boot id (#893) */
   let lastBoot = null;
+  /** @type {number | null} the last reload seq seen from that process (#1507) */
+  let lastSeq = 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
-  // the set is bounded by the tabs opened in one session.
   function fanout(msg) {
-    for (const p of ports) {
+    for (const p of ports.keys()) {
       try { p.postMessage(msg); } catch (_) { ports.delete(p); }
     }
   }
 
-  // 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';
+  /** Whether the batch reloads every tab, or only the stale ones in `batchPorts` (#1516). */
+  let batchAll = false;
+  /** @type {Set<any>} tabs whose page fell behind, reloaded on their own */
+  const batchPorts = new Set();
 
   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 });
+    const msg = { type: 'reload', verdict: v };
+    const targets = batchAll ? Array.from(ports.keys()) : Array.from(batchPorts).filter((p) => ports.has(p));
+    batchAll = false;
+    batchPorts.clear();
+    for (const p of targets) {
+      // The tab applies this reload, so from here its page reflects the state
+      // the relay knows now; a later hello compares against that.
+      if (pages.has(p) && typeof lastBoot === 'string') pages.set(p, { boot: lastBoot, seq: lastSeq });
+      try { p.postMessage(msg); } catch (_) { ports.delete(p); pages.delete(p); }
+    }
   }
 
   /** Strength rank; an unrecognised name ranks strongest, so it can only ever
@@ -138,60 +215,129 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
     return i === -1 ? 0 : i;
   }
 
-  /** @param {string} verdict */
-  function requestReload(verdict) {
-    // Lower rank is stronger, so keep the minimum across the batch.
+  /**
+   * @param {string} verdict
+   * @param {any} [port]  reload only this tab (its page fell behind); omitted, every tab
+   */
+  function requestReload(verdict, port) {
+    if (port === undefined) batchAll = true; else batchPorts.add(port);
     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
-  // per-process boot id (#893). A full server restart (Node's `node --watch`)
-  // drops this connection, and if the in-process rebuild's `reload` frame was
-  // killed with the old process no reload was delivered, so the edit would need
-  // a MANUAL refresh. The browser auto-reconnects to the FRESH process, whose
-  // boot id differs, so a CHANGED id is the edit signal: broadcast a reload (the
-  // 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. 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) requestReload('reload');
-    lastBoot = e.data;
-  });
-
-  // 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 }); });
+  /** @type {any} */ let es = null;
+  /** @type {any} */ let retryTimer = null;
+  let retryDelay = RECONNECT_BASE_MS;
+
+  /** @type {any} */ let idleTimer = null;
+
+  // Idle close (#1507). A host that counts an in-flight request as activity
+  // (a pilots sandbox does, for the request's whole life) never sleeps while
+  // the stream is open, however quiet it is. With `idleMs` set, a stream that
+  // has carried nothing and seen no interaction for that long is closed, and
+  // the next interaction, a tab showing, or a host command through the embed
+  // bridge reopens it; the hello seq then says whether an edit landed meanwhile.
+  function touch() {
+    if (!idleMs) return;
+    if (idleTimer !== null) timers.clearTimeout(idleTimer);
+    idleTimer = timers.setTimeout(() => { idleTimer = null; close(); }, idleMs);
+  }
+
+  // Reload every tab whose page is behind what the server reports now (#1516).
+  function checkPages() {
+    for (const [p, page] of pages) {
+      if (pageIsStale(page, lastBoot, lastSeq)) requestReload('reload', p);
+    }
+  }
+
+  function anyVisible() {
+    for (const v of ports.values()) if (v) return true;
+    return false;
+  }
+
+  function open() {
+    if (es || retryTimer !== null) return;
+    es = new EventSourceCtor(eventsUrl);
+    const mine = es;
+    touch();
+    es.addEventListener('hello', (e) => {
+      retryDelay = RECONNECT_BASE_MS;
+      touch();
+      const h = parseHello(e.data);
+      if (lastBoot !== null && (h.boot !== lastBoot || (h.seq !== null && lastSeq !== null && h.seq !== lastSeq))) {
+        requestReload('reload');
+      }
+      lastBoot = h.boot;
+      lastSeq = h.seq;
+      checkPages();
+    });
+    es.addEventListener('reload', (e) => {
+      touch();
+      lastError = null;
+      const n = reloadSeq(e.data);
+      if (n !== null) lastSeq = n;
+      requestReload(parseVerdict(e.data));
+    });
+    es.addEventListener('webjs-error', (e) => { lastError = e.data; fanout({ type: 'webjs-error', data: e.data }); });
+    // The stream dropped (a restarting server, a network blip, a host that
+    // slept). Close it so the browser's fixed-interval retry never runs, and
+    // come back with backoff, but only while someone is looking.
+    es.addEventListener('error', () => {
+      if (es !== mine) return;
+      try { es.close(); } catch (_) { /* already closed */ }
+      es = null;
+      if (!anyVisible()) return;
+      retryTimer = timers.setTimeout(() => { retryTimer = null; if (anyVisible()) open(); }, retryDelay);
+      retryDelay = Math.min(retryDelay * 2, RECONNECT_MAX_MS);
+    });
+  }
+
+  function close() {
+    if (idleTimer !== null) { timers.clearTimeout(idleTimer); idleTimer = null; }
+    if (retryTimer !== null) { timers.clearTimeout(retryTimer); retryTimer = null; }
+    if (es) { try { es.close(); } catch (_) { /* already closed */ } es = null; }
+    retryDelay = RECONNECT_BASE_MS;
+  }
+
+  function sync() {
+    if (anyVisible()) open(); else close();
+  }
 
   scope.onconnect = (e) => {
     const port = e.ports[0];
-    ports.add(port);
+    // A tab counts as visible until it says otherwise, so a client older than
+    // the visibility messages keeps the stream open exactly as before.
+    ports.set(port, true);
+    port.onmessage = (m) => {
+      const d = (m && m.data) || {};
+      if (d.type === 'page') {
+        // The state this tab's page was rendered at (#1516). Checked now
+        // against what the relay already knows, so a tab that missed a fanned
+        // out reload catches up, and again on every hello.
+        if (typeof d.boot === 'string') {
+          pages.set(port, { boot: d.boot, seq: typeof d.seq === 'number' ? d.seq : null });
+          if (pageIsStale(pages.get(port), lastBoot, lastSeq)) requestReload('reload', port);
+        }
+        return;
+      }
+      if (d.type === 'visibility') ports.set(port, d.visible !== false);
+      else if (d.type === 'bye') { ports.delete(port); pages.delete(port); }
+      else if (d.type === 'activity') { if (!ports.get(port)) return; touch(); }
+      else return;
+      sync();
+    };
     port.start();
-    // A tab that connects AFTER a breaking edit still needs the current overlay.
-    // The single shared EventSource already consumed the server's replay (#264),
-    // so the worker caches the last error and hands it to each new tab itself.
     if (lastError != null) {
       try { port.postMessage({ type: 'webjs-error', data: lastError }); } catch (_) { ports.delete(port); }
     }
+    sync();
   };
 
-  // Returned for tests; the served worker ignores it.
-  return { ports, es };
+  return {
+    ports,
+    /** The live EventSource, or null while paused or between retries. */
+    get es() { return es; },
+  };
 }

package/src/listener-bun.js

@@ -28,8 +28,9 @@
  *     natively on Bun), the SAME negotiation + compressor factory the node shell
  *     uses (shared in `listener-core.js`), so the Bun path gets brotli too (#517).
  *   - **Timeouts** (#237): the node `requestTimeout` maps to Bun's single
- *     `idleTimeout` (seconds), clamped above the 25s SSE keepalive so a dev
- *     live-reload stream is never reaped.
+ *     `idleTimeout` (seconds); the dev live-reload stream opts out of it per
+ *     request with `server.timeout(req, 0)` (#1507), since it is silent
+ *     between events.
  *   - **Proxy IP**: `server.requestIP(req).address` stamps the framework-trusted
  *     `x-webjs-remote-ip` (the node socket-address equivalent), after stripping
  *     any spoofed inbound value.
@@ -59,7 +60,6 @@ import {
   MAX_SYNC_COMPRESS_BYTES,
   varyWithAcceptEncoding,
   readBufferedOrStream,
-  DEV_BOOT_ID,
 } from './listener-core.js';
 
 /* global Bun */
@@ -91,6 +91,9 @@ export function startBunListener(ctx) {
         // on node, but on Bun it is a perfectly ordinary streaming Response.
         if (isEventsPath(url.pathname, basePathStr)) {
           if (!dev) return new Response(null, { status: 404 });
+          // Silent between events (#1507): switch Bun's idleTimeout off for this
+          // one request, so a quiet live-reload stream is never reaped.
+          try { srv.timeout?.(req, 0); } catch { /* an older Bun: idleTimeout still applies */ }
           return bunSseResponse(req, hub, app);
         }
 
@@ -298,11 +301,9 @@ function bunSseResponse(req, hub, app) {
         send: (s) => { try { controller.enqueue(enc.encode(s)); } catch {} },
         close: () => { try { controller.close(); } catch {} },
       };
-      // `retry: 300` shrinks the EventSource reconnect backoff so a reconnect
-      // after a dev restart re-triggers a reload promptly (#893); the `hello`
-      // data is the per-process boot id so a reconnect reloads only on a real
-      // restart, matching the node:http shell.
-      controller.enqueue(enc.encode(`retry: 300\nevent: hello\ndata: ${DEV_BOOT_ID}\n\n`));
+      // The hello frame (`SseHub.helloFrame`, shared with the node:http shell)
+      // carries the retry hint, the boot id and the reload seq (#893, #1507).
+      controller.enqueue(enc.encode(hub.helloFrame()));
       hub.add(client);
       // Replay an unresolved dev error (#264) so a tab connecting AFTER the
       // breaking edit still shows the overlay.
@@ -488,8 +489,8 @@ async function maybeCompress(resp, req) {
 
 /**
  * Map the node `requestTimeout` (ms) to Bun's single `idleTimeout` (seconds). Bun
- * caps it at 255s; we clamp it above the 25s SSE keepalive so a dev live-reload
- * stream is never reaped as idle. `0` (the node "disable" sentinel) disables it
+ * caps it at 255s; the floor of 30s is kept for ordinary requests. The dev
+ * live-reload stream is exempt per request (`server.timeout(req, 0)`, #1507). `0` (the node "disable" sentinel) disables it
  * on Bun too.
  * @param {{ requestTimeout?: number } | undefined} timeouts
  */

package/src/listener-core.js

@@ -335,22 +335,28 @@ export function loadWsModule(file, dev) {
 
 /**
  * Runtime-neutral SSE registry + fanout for dev live-reload and the dev error
- * overlay (#264). Owns the connected-client Set and the keepalive timer; the
- * fanout writes plain SSE frames through each client's `send`. Each shell adds a
- * thin client wrapper over its own transport (node `res.write`, a Bun
+ * overlay (#264). Owns the connected-client Set; the fanout writes plain SSE
+ * frames through each client's `send`. Each shell adds a thin client wrapper
+ * over its own transport (node `res.write`, a Bun
  * `ReadableStreamDefaultController`), so this fanout logic is written once.
+ *
+ * The stream is SILENT between events (#1507). It used to write a `: ka`
+ * comment every 25 seconds per open tab, which kept the host busy forever: a
+ * sandbox or a laptop that sleeps on network quiet never slept while a tab
+ * showed the app. Each shell instead switches the server's idle timeout off
+ * for this one request, so a silent stream is never reaped, and the browser
+ * relay reconnects (with backoff) only when the stream actually drops.
+ *
+ * `seq` counts the reload frames this process has sent. It rides every reload
+ * frame and the `hello` frame, so a relay that closed its stream while every
+ * tab was hidden can tell, on reconnecting, that it missed an edit.
  */
 export class SseHub {
-  /** @param {{ keepaliveMs?: number }} [opts] */
-  constructor(opts = {}) {
+  constructor() {
     /** @type {Set<{ send: (s: string) => void, close: () => void }>} */
     this.clients = new Set();
-    // Keepalive: a comment frame every 25s defeats proxy idle timeouts (and, on
-    // Bun, keeps the connection under the server idleTimeout). Cheap and safe:
-    // SSE comments are ignored by the client. Unref'd so it never holds the
-    // process open.
-    this._timer = setInterval(() => this._raw(': ka\n\n'), opts.keepaliveMs ?? 25_000);
-    if (typeof this._timer.unref === 'function') this._timer.unref();
+    /** Reload frames sent by this process (#1507). */
+    this.seq = 0;
   }
 
   /** @param {{ send: (s: string) => void, close: () => void }} client */
@@ -365,31 +371,45 @@ export class SseHub {
     }
   }
 
+  /**
+   * The frame that opens every stream. `retry: 300` shrinks the browser's
+   * native reconnect wait (#893). The `hello` data names this process (its
+   * boot id, so a reconnect to a RESTARTED server reloads) and how many reload
+   * frames it has sent (`seq`, so a reconnect after a pause that missed one
+   * reloads too). JSON since #1507; a relay older than that compares the raw
+   * data, sees a change, and reloads once, which is the safe direction.
+   * @returns {string}
+   */
+  helloFrame() {
+    return `retry: 300\nevent: hello\ndata: ${JSON.stringify({ boot: DEV_BOOT_ID, seq: this.seq })}\n\n`;
+  }
+
   /**
    * Push a live-reload event to every open tab.
    *
    * The frame carries the change's `{ v, by, why }` classification (#1398) as a
-   * single-line JSON payload, matching `devError` below. The browser relay
-   * resolves ANY payload it cannot read to `reload`, and an absent or malformed
-   * verdict is emitted as `reload` here too, so the fail-safe holds on both ends
-   * of the wire and a tab running against a restarted server can never be
-   * skewed into a lighter response than the change deserves.
+   * single-line JSON payload, matching `devError` below, plus the frame's `seq`
+   * (#1507). The browser relay resolves ANY payload it cannot read to `reload`,
+   * and an absent or malformed verdict is emitted as `reload` here too, so the
+   * fail-safe holds on both ends of the wire and a tab running against a
+   * restarted server can never be skewed into a lighter response than the
+   * change deserves.
    *
    * @param {{ v?: string, by?: string, why?: string } | null} [verdict]
    */
   reload(verdict) {
     const v = verdict && typeof verdict.v === 'string' ? verdict : { v: 'reload' };
-    this._raw(`event: reload\ndata: ${JSON.stringify(v)}\n\n`);
+    this.seq++;
+    this._raw(`event: reload\ndata: ${JSON.stringify({ ...v, seq: this.seq })}\n\n`);
   }
 
   /** Push a dev-error overlay frame (#264) to every open tab. @param {object} frame */
   devError(frame) { this._raw(`event: webjs-error\ndata: ${JSON.stringify(frame)}\n\n`); }
 
-  /** Close every client and stop the keepalive (graceful shutdown). */
+  /** Close every client (graceful shutdown). */
   closeAll() {
     for (const c of this.clients) { try { c.close(); } catch {} }
     this.clients.clear();
-    clearInterval(this._timer);
   }
 }
 

package/src/router.js

@@ -187,6 +187,12 @@ export async function buildRouteTable(appDir) {
   }
 
   pages.sort(compareSpecificity);
+  // Route handlers rank by the SAME positional specificity as pages (#1510).
+  // They used to keep filesystem walk order, so a catch-all such as
+  // `api/auth/[...path]/route.ts` could answer for a more specific sibling
+  // like `api/auth/callback/github/route.ts`, and which one won depended on
+  // the order the directory happened to list in.
+  apis.sort(compareSpecificity);
   // `instrumentation-client.*` is an app-ROOT convention file, not a router
   // stem, but it is a browser-bound entry (the boot imports it first), so the
   // table is where every consumer already looks for one. Resolved HERE rather

package/src/ssr/head.js

@@ -7,6 +7,7 @@ import { vendorIntegrityFor } from '../importmap.js';
 import { publicEnvShim } from './env-shim.js';
 import { clientRouterEnabled } from './client-router-flag.js';
 import { embedScriptTag } from '../dev-embed.js';
+import { devReloadState } from '../dev-reload-state.js';
 
 // Which icon metadata ROUTES the app has (`app/icon.*`, `app/apple-icon.*`).
 // Set at boot and on each route rebuild from the route table, the same shape
@@ -315,8 +316,12 @@ export function wrapHead(opts) {
     : '';
 
   const boot = (imports || lazyBoot) ? `<script type="module"${n}>\n${imports}${lazyBoot}\n</script>` : '';
+  // The reload state this page is rendered at (#1516), so the reload client can
+  // tell on every reconnect whether the page fell behind the server.
+  const reloadState = opts.dev ? devReloadState() : null;
   const reload = opts.dev
-    ? `<script type="module"${n} src="${escapeAttr(withBasePath('/__webjs/reload.js', bp))}"></script>`
+    ? (reloadState ? `<meta name="webjs-dev-reload" content="${escapeAttr(JSON.stringify(reloadState))}">\n` : '') +
+      `<script type="module"${n} src="${escapeAttr(withBasePath('/__webjs/reload.js', bp))}"></script>`
     : '';
   const suspenseBoot = opts.streaming
     ? `<script${n}>(function(){` +

package/src/vendor/manifest.js

@@ -91,6 +91,33 @@ export function getPackageManifest(pkgName, appDir) {
   }
 }
 
+/**
+ * The names a package depends on at runtime (`dependencies`,
+ * `peerDependencies`, `optionalDependencies`) and its installed directory,
+ * resolved from `fromDir` (#1518). Resolving a dependency from its DEPENDENT's
+ * directory finds a nested install as well as a hoisted one, so the pin prune
+ * can walk the real installed graph. Null when the package is not installed.
+ *
+ * @param {string} pkgName
+ * @param {string} fromDir  a directory holding a package.json (the app, or a dependent package)
+ * @returns {{ dir: string, names: string[] } | null}
+ */
+export function getPackageDeps(pkgName, fromDir) {
+  const real = resolvePackageDir(pkgName, fromDir);
+  if (!real) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(join(real, 'package.json'), 'utf8'));
+    const names = new Set([
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.peerDependencies || {}),
+      ...Object.keys(pkg.optionalDependencies || {}),
+    ]);
+    return { dir: real, names: [...names] };
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // JSPM Generator API client
 // ---------------------------------------------------------------------------

package/src/vendor/pins.js

@@ -1,9 +1,9 @@
 import { readFile, writeFile, mkdir, unlink, stat, rename, readdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { BUILTIN, FRAMEWORK_SERVER_ONLY, extractPackageName, scanBareImports } from './scanner.js';
-import { getPackageVersion } from './manifest.js';
+import { getPackageVersion, getPackageDeps } from './manifest.js';
 import { SUPPORTED_PROVIDERS } from './providers.js';
 import { PIN_BUNDLE_TIMEOUT_MS, fetchIntegrity, sha384Integrity } from './integrity.js';
 import { jspmGenerate } from './jspm.js';
@@ -506,17 +506,54 @@ export function basePackage(spec) {
  * when code imports `dayjs/plugin/utc`, and vice versa). Integrity hashes for
  * dropped URLs are pruned too.
  *
+ * With `opts.appDir` it also keeps the TRANSITIVE dependencies of every kept
+ * package (#1518). App code never imports a transitive (`@codemirror/view`
+ * imports `style-mod`, `@codemirror/language` imports `@lezer/lr`), so the
+ * filter above alone dropped every one of them and the browser failed to
+ * resolve the bare specifier. The closure walks each kept package's installed
+ * `package.json`, resolving each dependency from its dependent's directory, and
+ * keeps every pin entry whose base package it reaches, which is the set the
+ * live resolve serves (jspm flattens the transitives of the reachable
+ * installs). When a kept package is not on disk the graph cannot be walked, so
+ * every pin entry the app does not itself declare is kept instead: an unused
+ * entry costs nothing, a missing one breaks the page.
+ *
  * @param {Record<string, string>} imports  pin entries (specifier -> URL)
  * @param {Record<string, string>} integrity  SRI hashes keyed by URL
  * @param {Set<string>} reachable  bare specifiers used by non-elided modules
+ * @param {{ appDir?: string }} [opts]
  * @returns {{ imports: Record<string, string>, integrity: Record<string, string> }}
  */
-export function prunePinToReachable(imports, integrity, reachable) {
-  const reachableBases = new Set([...reachable].map(basePackage));
+export function prunePinToReachable(imports, integrity, reachable, opts = {}) {
+  const keepBases = new Set([...reachable].map(basePackage));
+  if (opts.appDir) {
+    const pinnedBases = new Set(Object.keys(imports || {}).map(basePackage));
+    let complete = true;
+    /** @type {Array<[string, string]>} base package, directory to resolve it from */
+    const queue = [...keepBases].filter((b) => pinnedBases.has(b)).map((b) => [b, opts.appDir]);
+    const walked = new Set();
+    while (queue.length) {
+      const [base, from] = /** @type {[string, string]} */ (queue.shift());
+      const key = `${base}\0${from}`;
+      if (walked.has(key)) continue;
+      walked.add(key);
+      const deps = getPackageDeps(base, from);
+      if (!deps) { complete = false; continue; }
+      for (const name of deps.names) {
+        if (!pinnedBases.has(name)) continue;
+        keepBases.add(name);
+        queue.push([name, deps.dir]);
+      }
+    }
+    if (!complete) {
+      const declared = declaredDeps(opts.appDir);
+      for (const b of pinnedBases) if (!declared.has(b)) keepBases.add(b);
+    }
+  }
   /** @type {Record<string, string>} */
   const keptImports = {};
   for (const [spec, url] of Object.entries(imports || {})) {
-    if (reachable.has(spec) || reachableBases.has(basePackage(spec))) {
+    if (reachable.has(spec) || keepBases.has(basePackage(spec))) {
       keptImports[spec] = url;
     }
   }
@@ -529,6 +566,25 @@ export function prunePinToReachable(imports, integrity, reachable) {
   return { imports: keptImports, integrity: keptIntegrity };
 }
 
+/**
+ * Every package the app's own package.json declares, in any dependency field.
+ * @param {string} appDir
+ * @returns {Set<string>}
+ */
+function declaredDeps(appDir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(appDir, 'package.json'), 'utf8'));
+    return new Set([
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.devDependencies || {}),
+      ...Object.keys(pkg.peerDependencies || {}),
+      ...Object.keys(pkg.optionalDependencies || {}),
+    ]);
+  } catch {
+    return new Set();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Importmap coherence check (issue #450)
 // ---------------------------------------------------------------------------

package/webjs-config.schema.json

@@ -208,6 +208,11 @@
           "type": "array",
           "items": { "type": "string" }
         },
+        "reloadIdle": {
+          "description": "Live-reload idle close (#1507), DEV-ONLY and off by default. Seconds with no edit and no interaction in any tab after which the dev live-reload stream is closed, so a host that counts an open request as activity (a sandbox that suspends when idle) can sleep while a preview tab is open; the next interaction, a tab becoming visible, or an embed-bridge host command reopens it, and an edit made meanwhile reloads the page. WEBJS_DEV_RELOAD_IDLE (seconds) overrides it. Read by the server (readDevToolingFromApp). Ignored by webjs start.",
+          "type": "number",
+          "minimum": 0
+        },
         "sourceLocations": {
           "description": "Dev source locations (#1499, #1504), DEV-ONLY and off by default. When true, element opening tags in the app's html templates carry data-webjs-src=\"<app-relative-file>:<line>\" in SSR output and client renders. WEBJS_SOURCE_LOCATIONS=1 or 0 overrides it for one run. Read by the server (readDevToolingFromApp). Ignored by webjs start.",
           "type": "boolean"