@webjsdev/server 0.8.68 → 0.8.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.68",
+  "version": "0.8.70",
   "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

@@ -317,6 +317,28 @@ export async function readDevWatchPathsFromApp(appDir) {
   return out;
 }
 
+/**
+ * The dev tooling switches in `webjs.dev` (#1504): `embedOrigins` (the embed
+ * 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, reloadIdle: unknown }>}
+ */
+export async function readDevToolingFromApp(appDir) {
+  let dev;
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    dev = pkg && pkg.webjs && pkg.webjs.dev;
+  } catch {
+    dev = undefined;
+  }
+  if (!dev || typeof dev !== 'object') return { embedOrigins: undefined, sourceLocations: undefined, reloadIdle: undefined };
+  return { embedOrigins: dev.embedOrigins, sourceLocations: dev.sourceLocations, reloadIdle: dev.reloadIdle };
+}
+
 /**
  * Resolve the node:http server timeouts (issue #237) from the app's
  * package.json `webjs.requestTimeoutMs` / `webjs.headersTimeoutMs` /

package/src/dev/handler.js

@@ -41,7 +41,7 @@ import { setAssetUrlProvider, setFormActionResolver } from '@webjsdev/core';
 import { resolveActionIdentity } from '../form-action-identity.js';
 import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, resolveAssetUrl } from '../asset-hash.js';
 import { applySecurityHeaders, webRequestIsHttps } from '../headers.js';
-import { parseEmbedOrigins, setEmbedOrigins, allowEmbedFraming } from '../dev-embed.js';
+import { resolveEmbedOrigins, setEmbedOrigins, allowEmbedFraming } from '../dev-embed.js';
 import {
   applyRedirects,
   applyTrailingSlash,
@@ -62,10 +62,13 @@ import {
   readAllowedOriginsFromApp,
   readCspConfigFromApp,
   readBodyLimitsFromApp,
+  readDevToolingFromApp,
 } from './config.js';
 import {
   exists, kebab, resolveRequestId, shouldAccessLog, loadAppEnv, collectRouteModules,
   appTopLevelDirs, locateCoreDir,
+  setReloadIdleMs,
+  resolveReloadIdleMs,
 } from './helpers.js';
 import {
   handleCore, loadMiddleware, tryServeFrameworkStatic, tryServePublicAsset,
@@ -216,12 +219,19 @@ export async function createRequestHandler(opts) {
   // analysis pass re-reads it each rebuild so a dev toggle takes effect live.
   setClientRouterEnabled(await readClientRouterEnabled(appDir));
 
-  // Dev embed bridge (#1498): `WEBJS_EMBED_ORIGINS` lets the listed parent
+  // Dev embed bridge (#1498): `WEBJS_EMBED_ORIGINS` (or `webjs.dev.embedOrigins`) lets the listed parent
   // origins frame this dev server and receive the bridge's messages. Read once
   // here, and only in dev, so a production handler records no origins and
   // neither injects the script nor relaxes a framing header.
-  const embedOriginsValue = dev ? parseEmbedOrigins(process.env.WEBJS_EMBED_ORIGINS) : [];
+  // `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, 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
@@ -288,13 +298,15 @@ export async function createRequestHandler(opts) {
   // on seeding would mean `webjs.seed: false` silently broke every no-JS form.
   await registerActionHooks({ seed: await readSeedEnabled(appDir), dev });
 
-  // Dev source locations (#1499): `WEBJS_SOURCE_LOCATIONS=1` under `webjs dev`
+  // Dev source locations (#1499): `WEBJS_SOURCE_LOCATIONS=1` (or
+  // `webjs.dev.sourceLocations: true`) under `webjs dev`
   // stamps `data-webjs-src="<file>:<line>"` on the element opening tags of the
   // app's `html` templates. Read once (the SSR load hook is process-global and
   // cannot be uninstalled), never in prod. The browser half reads
   // `state.sourceLocations` in serve.js; the SSR half is this load hook, which
   // must be in place before any app module is imported.
-  const sourceLocations = dev && sourceLocationsRequested();
+  // `webjs.dev.sourceLocations` is the default (#1504); the env var wins.
+  const sourceLocations = dev && sourceLocationsRequested(process.env, devTooling.sourceLocations);
   if (sourceLocations) {
     registerSourceLocationHook(appDir);
     // Module URLs are realpaths, so a symlinked app dir registers both forms.

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,37 @@ 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) {
+  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) 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 +562,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 +584,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,7 @@ 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 } from '../listener-core.js';
 import { urlFromRequest } from '../forwarded.js';
 import { stripBasePath } from '../base-path.js';
 import { basePath } from '../importmap.js';
@@ -102,9 +102,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 +195,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());
     }),
@@ -236,8 +241,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-embed.js

@@ -2,8 +2,9 @@
  * The dev embed bridge, SERVER half (#1498).
  *
  * `webjs dev` with `WEBJS_EMBED_ORIGINS` set (a comma-separated list of parent
- * origins, e.g. `https://crisp.app,http://localhost:8080`) makes an app ready
- * to be previewed inside an iframe on those origins:
+ * origins, e.g. `https://builder.example,http://localhost:8080`), or the app's
+ * `webjs.dev.embedOrigins` list (#1504), makes an app ready to be previewed
+ * inside an iframe on those origins:
  *
  *   1. every HTML document gets a small inline script (the browser half,
  *      `dev-embed-client.js`) that reports page state to the parent and takes
@@ -73,6 +74,23 @@ export function parseEmbedOrigins(raw, opts) {
   return out;
 }
 
+/**
+ * The effective embed origins (#1504): `WEBJS_EMBED_ORIGINS`, when set and
+ * non-empty, replaces the app's `webjs.dev.embedOrigins`; otherwise the config
+ * list applies. Both go through `parseEmbedOrigins`, so a bad entry is dropped
+ * with the same warning wherever it was written.
+ *
+ * @param {string | undefined} envRaw
+ * @param {unknown} configured the app's `webjs.dev.embedOrigins`
+ * @param {{ warn?: (msg: string) => void }} [opts]
+ * @returns {string[]}
+ */
+export function resolveEmbedOrigins(envRaw, configured, opts) {
+  if (typeof envRaw === 'string' && envRaw.trim()) return parseEmbedOrigins(envRaw, opts);
+  if (!Array.isArray(configured)) return [];
+  return parseEmbedOrigins(configured.filter((o) => typeof o === 'string').join(','), opts);
+}
+
 /**
  * Record the allowed embed origins for this process. `createRequestHandler`
  * calls it at construction: the parsed env value in dev, `[]` otherwise.

package/src/dev-reload-worker.js

@@ -77,44 +77,81 @@ 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 };
+}
+
+/** 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.
+ *
+ * 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 {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;
 
@@ -125,8 +162,6 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
     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 });
   }
@@ -140,58 +175,105 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
 
   /** @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
-  // 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);
+  }
+
+  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;
+    });
+    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 === 'visibility') ports.set(port, d.visible !== false);
+      else if (d.type === 'bye') ports.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/dev-source-locations.js

@@ -64,15 +64,21 @@ const REGEX_AFTER_KEYWORDS = new Set([
 export const SOURCE_LOCATIONS_ENV = 'WEBJS_SOURCE_LOCATIONS';
 
 /**
- * Whether the env asks for source locations. Read by the dev handler once, at
- * construction; the caller also requires `dev`, so production never consults it.
+ * Whether source locations are on (#1499, #1504). The app's
+ * `webjs.dev.sourceLocations` sets the default; the env var, when set, wins
+ * either way (`1` / `true` on, `0` / `false` off), so one run can flip it
+ * without editing package.json. Read by the dev handler once, at construction;
+ * the caller also requires `dev`, so production never consults it.
  *
  * @param {Record<string, string | undefined>} [env]
+ * @param {unknown} [configured] the app's `webjs.dev.sourceLocations`
  * @returns {boolean}
  */
-export function sourceLocationsRequested(env = process.env) {
+export function sourceLocationsRequested(env = process.env, configured = false) {
   const v = String(env[SOURCE_LOCATIONS_ENV] || '').trim().toLowerCase();
-  return v === '1' || v === 'true';
+  if (v === '1' || v === 'true') return true;
+  if (v === '0' || v === 'false') return false;
+  return configured === true;
 }
 
 /**

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/webjs-config.schema.json

@@ -202,6 +202,20 @@
           "description": "Extra directories the dev live-reload watcher follows in addition to the appDir (#894), for content the app reads from outside its own tree (e.g. blog markdown in a repo-root blog/ dir). Each entry is resolved relative to the app root and may escape it (../blog). Read by the server (readDevWatchPathsFromApp).",
           "type": "array",
           "items": { "type": "string" }
+        },
+        "embedOrigins": {
+          "description": "Dev embed bridge (#1498, #1504), DEV-ONLY and off by default. Parent origins (e.g. https://builder.example) allowed to frame the dev server: X-Frame-Options is dropped and frame-ancestors widened for them, and every document carries a nonce-signed script that posts { source: 'webjs-embed', type } messages to such a parent and takes { source: 'webjs-embed-host', type } commands from it. A set WEBJS_EMBED_ORIGINS env var replaces this list. Read by the server (readDevToolingFromApp). Ignored by webjs start.",
+          "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"
         }
       }
     },