@webjsdev/server 0.8.46 → 0.8.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.46",
+  "version": "0.8.48",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/dev-reload-worker.js

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @param {{ onconnect: any }} scope  the worker global (`self`)
+ * @param {new (url: string) => any} EventSourceCtor  the `EventSource` constructor
+ * @param {string} eventsUrl  the base-path-aware `/__webjs/events` URL
+ */
+export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
+  /** @type {Set<any>} */
+  const ports = new Set();
+  /** @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;
+
+  // 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) {
+      try { p.postMessage(msg); } catch (_) { ports.delete(p); }
+    }
+  }
+
+  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.
+  es.addEventListener('hello', (e) => {
+    if (lastBoot !== null && e.data !== lastBoot) fanout({ type: 'reload' });
+    lastBoot = e.data;
+  });
+
+  es.addEventListener('reload', () => { lastError = null; fanout({ type: 'reload' }); });
+  es.addEventListener('webjs-error', (e) => { lastError = e.data; fanout({ type: 'webjs-error', data: e.data }); });
+
+  scope.onconnect = (e) => {
+    const port = e.ports[0];
+    ports.add(port);
+    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); }
+    }
+  };
+
+  // Returned for tests; the served worker ignores it.
+  return { ports, es };
+}

package/src/dev.js

@@ -1,6 +1,7 @@
 import { createServer as createHttp1Server } from 'node:http';
 import { stat, readFile, watch as fsWatch } from 'node:fs/promises';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { join, extname, resolve, dirname, relative, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -44,9 +45,10 @@ import {
   negotiateEncoding,
   createCompressor,
   varyWithAcceptEncoding,
+  DEV_BOOT_ID,
 } from './listener-core.js';
 import { scanBareImports, resolveVendorImports, serveDownloadedBundle, clearVendorCache, hasVendorPin, readPinFile, prunePinToReachable } from './vendor.js';
-import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport, appImportsMap } from './module-graph.js';
+import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport, appImportsMap, seenFilesFor } from './module-graph.js';
 import { primeComponentRegistry, findOrphanComponents, scanComponents } from './component-scanner.js';
 import { analyzeElision, elideImportsFromSource } from './component-elision.js';
 
@@ -86,7 +88,7 @@ function resolveRequestId(req) {
 function shouldAccessLog(pathname) {
   return !pathname.startsWith('/__webjs/');
 }
-import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath, setImportAliasEntries, importAliasBrowserEntries } from './importmap.js';
+import { setVendorEntries, setCoreInstall, publishBuildId, setAppSourceId, setBasePath, basePath, setImportAliasEntries, importAliasBrowserEntries } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { propagateTrustedRemoteIp } from './rate-limit.js';
 import { readAllowedOrigins } from './csrf.js';
@@ -421,6 +423,50 @@ export async function readBodyLimitsFromApp(appDir) {
   return readBodyLimits(pkg);
 }
 
+/**
+ * Extra dev watch roots from the app's package.json `webjs.dev.watch` (#894).
+ * These are directories the app READS from but that live OUTSIDE its appDir, so
+ * the recursive `fs.watch(appDir)` never sees them (e.g. the website renders
+ * posts from a repo-root `blog/` dir, a sibling of the app, so editing a post
+ * would not live-reload). Each entry is resolved relative to the appDir and MAY
+ * escape it (`"../blog"`); a change under one runs the same rebuild + reload as
+ * an in-tree edit. Opt-in: a missing/empty config yields `[]`, so a plain app
+ * watches only its appDir, unchanged.
+ *
+ * Returns absolute, de-duped paths, skipping any that overlap the appDir (the
+ * appDir is already watched recursively, so an ancestor or descendant root
+ * would just double-fire the rebuild). Existence is NOT checked here (the caller
+ * filters missing paths so it can log them); the reader stays a pure
+ * package.json read, matching the other `readXFromApp` helpers.
+ *
+ * @param {string} appDir
+ * @returns {Promise<string[]>}
+ */
+export async function readDevWatchPathsFromApp(appDir) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    return [];
+  }
+  const raw = pkg && pkg.webjs && pkg.webjs.dev && pkg.webjs.dev.watch;
+  if (!Array.isArray(raw)) return [];
+  /** @type {string[]} */
+  const out = [];
+  const seen = new Set();
+  for (const entry of raw) {
+    if (typeof entry !== 'string' || !entry.trim()) continue;
+    const abs = resolve(appDir, entry);
+    // Skip the appDir itself and any ancestor/descendant overlap: the appDir is
+    // already watched recursively, so an overlapping extra root double-fires.
+    if (abs === appDir || appDir.startsWith(abs + sep) || abs.startsWith(appDir + sep)) continue;
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    out.push(abs);
+  }
+  return out;
+}
+
 /**
  * Resolve the node:http server timeouts (issue #237) from the app's
  * package.json `webjs.requestTimeoutMs` / `webjs.headersTimeoutMs` /
@@ -875,6 +921,25 @@ export async function createRequestHandler(opts) {
             } else {
               setAppSourceFingerprint('');
             }
+            // App-source deploy SIGNAL (#899), distinct from the #318 html-cache
+            // fingerprint above: hashes ALL app source (the module-graph `seen`
+            // set, INCLUDING server-only `.server.ts` that `browserBoundFiles`
+            // omits) with a raw per-file byte digest (decoupled from the
+            // asset-hash memo/elision machinery), plus the installed
+            // `@webjsdev/server` version, so an app-source OR a server-framework
+            // deploy moves it. Sorted + appDir-relative for determinism across
+            // instances. Drives the client's soft cache-evict (not a reload).
+            // PROD only; empty in dev (fs.watch + SSE handle staleness there).
+            if (!dev && state.moduleGraph) {
+              const relApp = (p) => (p.startsWith(appDir + sep) ? p.slice(appDir.length) : p);
+              const srcLines = [...seenFilesFor(state.moduleGraph)]
+                .map((abs) => `${relApp(abs)}:${fileByteHash(abs)}`)
+                .sort();
+              srcLines.push(`@webjsdev/server:${frameworkServerVersion()}`);
+              setAppSourceId(srcLines.join('\n'));
+            } else {
+              setAppSourceId('');
+            }
             t.elision = now() - m;
             if (dev) {
               for (const { className, file } of await findOrphanComponents(appDir)) {
@@ -1491,6 +1556,38 @@ export function shouldIgnoreWatchPath(filename) {
   return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(filename || '');
 }
 
+/**
+ * A short content digest of a single file's bytes for the app-source deploy
+ * signal (#899). Raw `sha256(bytes)`, deliberately independent of `assetHashFor`
+ * (which folds the elision fingerprint and memoizes for `?v` emission): the
+ * signal only needs "did the source bytes change", and server-only files never
+ * enter the asset-hash memo anyway. Returns `''` on a read failure, so a
+ * transient error degrades the id rather than throwing during analysis.
+ * @param {string} abs
+ * @returns {string}
+ */
+function fileByteHash(abs) {
+  try { return createHash('sha256').update(readFileSync(abs)).digest('hex').slice(0, 16); }
+  catch { return ''; }
+}
+
+/** @type {string} memoized `@webjsdev/server` version, folded into the app-source signal (#899). */
+let _frameworkServerVersion;
+/**
+ * The installed `@webjsdev/server` version (this package). Folded into the
+ * app-source deploy signal so a server-framework release (which alters SSR
+ * output but ships no new browser module) turns over the client's stale caches.
+ * @returns {string}
+ */
+function frameworkServerVersion() {
+  if (_frameworkServerVersion !== undefined) return _frameworkServerVersion;
+  try {
+    const v = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    _frameworkServerVersion = typeof v === 'string' ? v.replace(/[^\w.-]/g, '').slice(0, 32) : '';
+  } catch { _frameworkServerVersion = ''; }
+  return _frameworkServerVersion;
+}
+
 /**
  * @param {{
  *   appDir: string,
@@ -1543,9 +1640,9 @@ export async function startServer(opts) {
     // the SQLite dev DB (db/dev.db) + db/migrations so a file the dev server itself writes never loops.
     const rebuild = debounce(() => app.rebuild(), 80);
     watcherAbort = new AbortController();
-    (async () => {
+    const watchRoot = async (root) => {
       try {
-        const events = fsWatch(app.appDir, { recursive: true, signal: watcherAbort.signal });
+        const events = fsWatch(root, { recursive: true, signal: watcherAbort.signal });
         for await (const event of events) {
           const filename = event.filename || '';
           if (shouldIgnoreWatchPath(filename)) continue;
@@ -1553,10 +1650,17 @@ export async function startServer(opts) {
         }
       } catch (err) {
         if (err && /** @type any */(err).name !== 'AbortError') {
-          logger.warn({ err }, 'file watcher exited');
+          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
@@ -1611,7 +1715,12 @@ function startNodeListener(ctx) {
           'cache-control': 'no-cache',
           connection: 'keep-alive',
         });
-        res.write(`event: hello\ndata: webjs\n\n`);
+        // `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 = {
@@ -1745,6 +1854,14 @@ async function tryServeFrameworkStatic(path, method, ctx) {
     });
   }
 
+  // Dev live-reload SharedWorker: one shared connection for all tabs (#887).
+  if (path === '/__webjs/reload-worker.js') {
+    if (!dev) return new Response('Not found', { status: 404 });
+    return new Response(reloadWorkerJs(basePath()), {
+      headers: { 'content-type': 'application/javascript; charset=utf-8' },
+    });
+  }
+
   // Core module: /__webjs/core/*
   //
   // ETag + ~1h max-age, NOT immutable. The URL path is un-versioned
@@ -1822,7 +1939,8 @@ async function handleCore(req, ctx) {
 
   // Health / readiness probes (`/__webjs/health`, `/__webjs/ready`) and the
   // framework-internal static assets (`/__webjs/core/*`, `/__webjs/reload.js`,
-  // downloaded `/__webjs/vendor/*`) are served in `handle()` BEFORE ensureReady,
+  // `/__webjs/reload-worker.js`, downloaded `/__webjs/vendor/*`) are served in
+  // `handle()` BEFORE ensureReady,
   // so they are not repeated here. This fallback covers the (currently
   // unreachable) case of handleCore being entered for one of those assets, so
   // the routing stays correct if a future caller bypasses the early path.
@@ -2259,7 +2377,25 @@ async function sendWebResponse(res, webRes, req, opts) {
  */
 async function fileResponse(abs, opts) {
   try {
-    const data = await readFile(abs);
+    let data = await readFile(abs);
+    // In dev an external watcher (tailwindcss --watch, esbuild, ...) rewrites a
+    // public asset with truncate-then-write, so the file is 0 bytes for a short
+    // window during a rebuild. A hot reload that lands in that window would
+    // serve empty CSS / JS and the page paints unstyled (#891). Close that
+    // 0-byte window: when an empty read comes from a file that was JUST modified
+    // (the mid-rewrite signal), re-read a few times so the truncated read does
+    // not reach the browser. A genuinely empty, untouched asset is served
+    // immediately (no delay), and a non-zero-but-partial write is a smaller
+    // residual gap this does not cover. Prod has no such watcher and is
+    // left untouched.
+    if (opts.dev && data.length === 0) {
+      let midRewrite = false;
+      try { midRewrite = Date.now() - (await stat(abs)).mtimeMs < 500; } catch { /* gone */ }
+      for (let i = 0; midRewrite && i < 12 && data.length === 0; i++) {
+        await new Promise((r) => setTimeout(r, 20));
+        try { data = await readFile(abs); } catch { break; }
+      }
+    }
     const type = MIME[extname(abs).toLowerCase()] || 'application/octet-stream';
     // The body is fully buffered (read into `data`), so opt it into the
     // conditional-GET funnel, which is the single place that hashes the bytes
@@ -2609,18 +2745,102 @@ function locatePackageDir(appDir, pkgName) {
 const DEV_OVERLAY_SRC = readFileSync(new URL('./dev-overlay.js', import.meta.url), 'utf8')
   .replace(/^export /gm, '');
 
+// The reload SharedWorker relay source (#887), read once + `export`-stripped so
+// it inlines into the served worker script. Sharing the one source
+// (`dev-reload-worker.js`, which the browser test imports directly) means the
+// test drives the EXACT relay code that ships, with no drift (same as #264).
+const RELOAD_WORKER_SRC = readFileSync(new URL('./dev-reload-worker.js', import.meta.url), 'utf8')
+  .replace(/^export /gm, '');
+
 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
   // dev (the /__webjs/reload.js branch 404s in prod), so it never reaches a
   // production page.
+  //
+  // Every tab shares ONE live-reload connection through a SharedWorker (#887).
+  // The old client opened an `EventSource` per tab, and because the dev server
+  // is HTTP/1.1 and browsers cap concurrent connections per host at ~6, a
+  // handful of open tabs would hold every connection slot with idle SSE streams
+  // and later tabs could not even fetch their HTML. The SharedWorker holds the
+  // single `EventSource` (see reloadWorkerJs) and relays each `reload` /
+  // `webjs-error` to every tab. The overlay still renders on the main thread
+  // (a worker has no DOM), so the worker forwards only the raw frame data.
+  //
+  // Fallback: where `SharedWorker` is missing (some mobile browsers) or its
+  // construction throws (a strict dev CSP without `worker-src`), each tab opens
+  // its own `EventSource`, the original behaviour. Correct, just not shared.
+  const eventsUrl = JSON.stringify(withBasePath('/__webjs/events', bp));
+  const workerUrl = JSON.stringify(withBasePath('/__webjs/reload-worker.js', bp));
+  const versionUrl = JSON.stringify(withBasePath('/__webjs/version', bp));
   return `// webjs dev reload client
 ${DEV_OVERLAY_SRC}
-const es = new EventSource(${JSON.stringify(withBasePath('/__webjs/events', bp))});
-es.addEventListener('reload', () => location.reload());
-es.addEventListener('webjs-error', (e) => {
-  let f; try { f = JSON.parse(e.data); } catch (_) { return; }
+function __webjsApplyError(data) {
+  let f; try { f = JSON.parse(data); } catch (_) { return; }
   renderDevOverlay(f);
-});
+}
+// Never reload INTO a server that is still restarting (Node's node --watch
+// briefly kills the process on an edit), which would paint a style-less,
+// half-rendered page (#893). Probe the lightweight /__webjs/version endpoint
+// until it answers, THEN reload. Under an in-process reload the server is up,
+// so the first probe passes and the reload is instant; under a restart the
+// probes fail until the fresh server is listening, so the old page stays put
+// until the new one is ready. Bounded, so a genuinely-dead server still
+// reloads (and shows the browser's own error) rather than hanging forever.
+function __webjsReloadWhenReady() {
+  var tries = 0;
+  function attempt() {
+    fetch(${versionUrl}, { cache: 'no-store' }).then(function (r) {
+      if (r && r.ok) location.reload(); else again();
+    }).catch(again);
+  }
+  function again() { if (++tries > 100) location.reload(); else setTimeout(attempt, 100); }
+  attempt();
+}
+function __webjsDirectEvents() {
+  // Same restart-reload as the SharedWorker relay (#893), for the per-tab
+  // fallback: the hello frame carries the server's per-process boot id, so a
+  // CHANGED id on reconnect means a real restart (reload), while a transient
+  // reconnect to the same process keeps the id (no spurious reload).
+  var lastBoot = null;
+  const es = new EventSource(${eventsUrl});
+  es.addEventListener('hello', (e) => {
+    if (lastBoot !== null && e.data !== lastBoot) __webjsReloadWhenReady();
+    lastBoot = e.data;
+  });
+  es.addEventListener('reload', () => __webjsReloadWhenReady());
+  es.addEventListener('webjs-error', (e) => __webjsApplyError(e.data));
+}
+try {
+  if (typeof SharedWorker !== 'undefined') {
+    const w = new SharedWorker(${workerUrl});
+    w.port.onmessage = (e) => {
+      const m = e.data || {};
+      if (m.type === 'reload') __webjsReloadWhenReady();
+      else if (m.type === 'webjs-error') __webjsApplyError(m.data);
+    };
+    w.port.start();
+  } else {
+    __webjsDirectEvents();
+  }
+} catch (_) {
+  __webjsDirectEvents();
+}
+`;
+}
+
+/**
+ * The dev live-reload SharedWorker. One instance is shared across every tab of
+ * the same origin (a SharedWorker is keyed by its script URL), so it holds the
+ * ONE `EventSource` to `/__webjs/events` and fans each event out to all tabs
+ * over their `MessagePort`s (#887). The `EventSource` URL carries the base path
+ * the same way the client's does (#256). Served only in dev.
+ * @param {string} bp the normalized base path (`''` = no-op)
+ * @returns {string}
+ */
+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))});
 `;
 }

package/src/importmap.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { createHash } from 'node:crypto';
 import { digestHex } from './crypto-utils.js';
 import { jsonForScriptTag } from './script-tag-json.js';
 import { withBasePath } from './base-path.js';
@@ -192,6 +193,9 @@ export function importMapHash() {
   return _importMapHash;
 }
 
+/** The installed `@webjsdev/core` version, folded into the published build id (#899). */
+let _coreVersion = '';
+
 /**
  * The published, client-facing build id: the value stamped into the
  * `data-webjs-build` attribute and the `X-Webjs-Build` header that the
@@ -220,16 +224,53 @@ export function publishedBuildId() {
 }
 
 /**
- * Promote the current `importMapHash()` to the advertised build id.
- * Called by `dev.js` when the importmap becomes authoritatively final.
- * Idempotent; the value only changes when the underlying map does, so
- * re-publishing an unchanged map is a no-op for the client. Within a
- * single process the published id therefore never changes after the
- * first publish (a rebuild in dev re-publishes the fresh map, but dev
- * already forces a full reload via SSE).
+ * Promote the current `importMapHash()` (folded with the installed
+ * `@webjsdev/core` version, #899) to the advertised build id. Called by `dev.js`
+ * when the importmap becomes authoritatively final. Idempotent; the value only
+ * changes when the map OR the core version does, so re-publishing an unchanged
+ * install is a no-op for the client. Within a single process the published id
+ * therefore never changes after the first publish (a rebuild in dev re-publishes
+ * the fresh map, but dev already forces a full reload via SSE).
+ *
+ * The empty-until-final guard holds: while `_importMapHash` is `''` (the warmup
+ * window) the published id stays `''`, so the router never hard-reloads against
+ * an unknown version even with the core version present.
  */
 export function publishBuildId() {
-  _publishedBuildId = _importMapHash;
+  if (!_importMapHash) { _publishedBuildId = ''; return; }
+  _publishedBuildId = _coreVersion ? `${_importMapHash}.c${_coreVersion}` : _importMapHash;
+}
+
+/**
+ * The app-source deploy signal (#899): a short digest advertised as the
+ * `data-webjs-src` attribute and the `X-Webjs-Src` header, distinct from the
+ * build id above. The client compares it across navigations and, on a mismatch,
+ * EVICTS its snapshot/prefetch caches (a soft re-fetch, NOT a hard reload):
+ * an app-source or server-framework change alters the SSR output but ships no
+ * new browser module the running page must swap, so a full reload would be an
+ * over-correction. Set by `dev.js` from a content hash of ALL app source (the
+ * module-graph `seen` set, including server-only `.server.ts`) folded with the
+ * installed `@webjsdev/server` version, PROD only. Empty in dev / warmup, which
+ * the client reads as "unknown" and never acts on (mirrors the build id guard).
+ *
+ * @type {string}
+ */
+let _appSourceId = '';
+
+/** @returns {string} the advertised app-source id, or `''` when unknown. */
+export function appSourceId() {
+  return _appSourceId;
+}
+
+/**
+ * Set the app-source id from a raw, deterministic input string (sorted
+ * `relpath:contentHash` lines plus the server version). Digested to a short hex
+ * so it stays a compact header/attribute value. An empty input clears it.
+ * @param {string} raw
+ * @returns {void}
+ */
+export function setAppSourceId(raw) {
+  _appSourceId = raw ? createHash('sha256').update(raw).digest('hex').slice(0, 16) : '';
 }
 
 /**
@@ -299,6 +340,15 @@ let _coreEntries = {
  */
 export async function setCoreInstall(coreDir, distMode) {
   _coreEntries = buildCoreEntries(coreDir, !!distMode);
+  // Capture the installed @webjsdev/core version (#899). The importmap targets
+  // core at a version-independent URL, so a core RELEASE (new implementation,
+  // same exports) does not move `_importMapHash`; folding the version into the
+  // published build id makes such a release change the client's hard-reload
+  // signal, since a running page cannot hot-swap the committed importmap core.
+  try {
+    const v = JSON.parse(readFileSync(join(coreDir, 'package.json'), 'utf8')).version;
+    _coreVersion = typeof v === 'string' ? v.replace(/[^\w.-]/g, '').slice(0, 32) : '';
+  } catch { _coreVersion = ''; }
   _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap({ fingerprint: false })));
 }
 
@@ -562,5 +612,9 @@ export function importMapTag(opts = {}) {
   // window never advertises an id that later changes. See
   // publishedBuildId() above for the rationale.
   const b = ` data-webjs-build="${publishedBuildId()}"`;
-  return `<script type="importmap"${n}${b}>${jsonForScriptTag(buildImportMap())}</script>`;
+  // The app-source deploy signal (#899), stamped alongside the build id. A
+  // change here evicts the client caches softly (see appSourceId()); empty until
+  // the analysis is ready, which the client reads as "unknown".
+  const s = ` data-webjs-src="${appSourceId()}"`;
+  return `<script type="importmap"${n}${b}${s}>${jsonForScriptTag(buildImportMap())}</script>`;
 }

package/src/listener-bun.js

@@ -58,6 +58,7 @@ import {
   MAX_SYNC_COMPRESS_BYTES,
   varyWithAcceptEncoding,
   readBufferedOrStream,
+  DEV_BOOT_ID,
 } from './listener-core.js';
 
 /* global Bun */
@@ -275,7 +276,11 @@ function bunSseResponse(req, hub, app) {
         send: (s) => { try { controller.enqueue(enc.encode(s)); } catch {} },
         close: () => { try { controller.close(); } catch {} },
       };
-      controller.enqueue(enc.encode('event: hello\ndata: webjs\n\n'));
+      // `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`));
       hub.add(client);
       // Replay an unresolved dev error (#264) so a tab connecting AFTER the
       // breaking edit still shows the overlay.

package/src/listener-core.js

@@ -22,10 +22,21 @@ import {
   constants as zlibConstants,
 } from 'node:zlib';
 import { stripBasePath } from './base-path.js';
+import { randomUUID } from 'node:crypto';
 
 /** The dev live-reload SSE path (matched after base-path stripping). */
 export const EVENTS_PATH = '/__webjs/events';
 
+/**
+ * A per-PROCESS id sent on the dev SSE `hello` frame (#893). It is regenerated
+ * on every server start, so a `node --watch` RESTART yields a NEW id while a
+ * transient reconnect (laptop sleep/wake, a network blip, a tab evicted at the
+ * HTTP/1.1 connection cap) reconnects to the SAME process and sees the SAME id.
+ * The reload client reloads only when this id CHANGES, so a mere reconnect never
+ * triggers a spurious full reload that would discard in-page dev state.
+ */
+export const DEV_BOOT_ID = randomUUID();
+
 /**
  * Detect the host runtime so `startServer` can pick an adapter. Bun sets
  * `process.versions.bun` (and also reports a `node` version via its compat

package/src/module-graph.js

@@ -170,6 +170,27 @@ export function bareImports(graph) {
   return BARE_EDGES.get(graph) || new Map();
 }
 
+/**
+ * Every app source file walked while building a graph (#899). `graph` itself
+ * holds only files that HAVE imports, so a leaf (e.g. a no-import `.server.ts`)
+ * is absent from it; this side-channel carries the COMPLETE set of `.js/.ts/
+ * .mjs/.mts` files under the appDir (excluding `node_modules`/`.webjs`/`public`/
+ * dotfiles), INCLUDING server-only files. Used to derive the app-source deploy
+ * signal that covers an SSR-only change a browser-bound-only set would miss.
+ * @type {WeakMap<ModuleGraph, Set<string>>}
+ */
+const SEEN_FILES = new WeakMap();
+
+/**
+ * The complete set of app source files walked for a built graph, or an empty
+ * set if none. Absolute paths.
+ * @param {ModuleGraph} graph
+ * @returns {Set<string>}
+ */
+export function seenFilesFor(graph) {
+  return SEEN_FILES.get(graph) || new Set();
+}
+
 /**
  * True for a bare npm vendor specifier (`dayjs`, `@scope/pkg/sub`), excluding
  * relative / absolute / `#`-alias paths and `node:` / protocol specifiers.
@@ -205,6 +226,7 @@ export async function buildModuleGraph(appDir) {
   await walk(appDir, appDir, graph, seen, dynamic, bare);
   if (dynamic.size) DYNAMIC_EDGES.set(graph, dynamic);
   if (bare.size) BARE_EDGES.set(graph, bare);
+  if (seen.size) SEEN_FILES.set(graph, seen);
   // Evict parse-cache entries for files no longer in the tree (a rebuild after
   // a rename or delete), so a long dev session does not accumulate dead
   // entries. Scoped to appDir so a multi-app process (tests, dogfood smoke)

package/src/ssr.js

@@ -1,7 +1,7 @@
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { renderToString, isNotFound, isRedirect, isForbidden, isUnauthorized, lookupModuleUrl, isLazy, cspNonce } from '@webjsdev/core';
-import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath, vendorPreconnectOrigins, vendorPreloadTargets } from './importmap.js';
+import { importMapTag, vendorIntegrityFor, publishedBuildId, appSourceId, basePath, vendorPreconnectOrigins, vendorPreloadTargets } from './importmap.js';
 import { withBasePath } from './base-path.js';
 import { withAssetHash } from './asset-hash.js';
 import { jsonForScriptTag } from './script-tag-json.js';
@@ -419,6 +419,7 @@ function htmlResponse(html, status, req, url, metadata) {
   // final, so a warming response is reload-safe. See router-client.js
   // applySwap and publishedBuildId() in importmap.js.
   headers.set('x-webjs-build', publishedBuildId());
+  headers.set('x-webjs-src', appSourceId());
   // Buffered (string) body: opt into the conditional-GET funnel so a
   // PUBLIC-cacheable page (metadata.cacheControl) gets a weak ETag + 304.
   // The funnel still excludes the no-store default, so a private page is
@@ -446,6 +447,7 @@ function cachedHtmlResponse(rec, req, url) {
   const headers = new Headers({ 'content-type': rec.contentType });
   headers.set('cache-control', rec.cacheControl);
   headers.set('x-webjs-build', publishedBuildId());
+  headers.set('x-webjs-src', appSourceId());
   headers.set(BUFFERED_MARKER, '1');
   return new Response(rec.body, { status: rec.status, headers });
 }
@@ -1717,6 +1719,7 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
   // See htmlResponse: published build id on every response for the
   // client router's importmap-mismatch detection on partial swaps.
   headers.set('x-webjs-build', publishedBuildId());
+  headers.set('x-webjs-src', appSourceId());
 
   if (!ctx.pending.length) {
     // No pending boundaries: this degrades to a single buffered (string)

package/webjs-config.schema.json

@@ -173,6 +173,11 @@
           "description": "Long-lived commands run as child processes alongside the dev server, torn down on exit so a watcher cannot leak past it.",
           "type": "array",
           "items": { "type": "string" }
+        },
+        "watch": {
+          "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" }
         }
       }
     },