@webjsdev/server 0.8.47 → 0.8.49

package/package.json

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

package/src/dev-reload-worker.js

@@ -21,6 +21,8 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
   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,
@@ -33,6 +35,22 @@ export function startReloadWorker(scope, EventSourceCtor, eventsUrl) {
   }
 
   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 }); });
 

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 = {
@@ -2663,15 +2772,43 @@ function reloadClientJs(bp) {
   // 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}
 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('reload', () => location.reload());
+  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 {
@@ -2679,7 +2816,7 @@ try {
     const w = new SharedWorker(${workerUrl});
     w.port.onmessage = (e) => {
       const m = e.data || {};
-      if (m.type === 'reload') location.reload();
+      if (m.type === 'reload') __webjsReloadWhenReady();
       else if (m.type === 'webjs-error') __webjsApplyError(m.data);
     };
     w.port.start();

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/js-scan.js

@@ -432,7 +432,13 @@ export function maskComments(src) {
  */
 export function extractWebComponentClassBodies(content) {
   const bodies = [];
-  const re = /class\s+\w+\s+extends\s+WebComponent/g;
+  // The optional `(?:\s*<[^{}();]*?>)?` skips a TypeScript generic parameter
+  // list on the class name (`class Grid<T> extends WebComponent`), so a generic
+  // component is not missed (which would let elision wrongly strip an
+  // interactive component, the unsafe direction). The exclusion class keeps the
+  // generic from swallowing the class body / a call, and stops it staying
+  // within the type-parameter list (#753, found differentially).
+  const re = /class\s+\w+(?:\s*<[^{}();]*?>)?\s+extends\s+WebComponent/g;
   let m;
   while ((m = re.exec(content)) !== null) {
     let i = m.index + m[0].length;

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 */
@@ -237,6 +238,16 @@ async function bunUpgrade(req, srv, ctx) {
 
   const wrapper = new BunWsAdapter();
   const handlerReq = upgradeRequest(req, url);
+  // Stamp the framework-trusted socket IP on the handler request so a `WS`
+  // handler's `clientIp(req)` returns the real peer, not a spoofed inbound
+  // `x-webjs-remote-ip` (#778). `srv.requestIP` must be queried with Bun's
+  // ORIGINAL `req` (the rebuilt `handlerReq` is unknown to it); the WeakMap
+  // stamp then makes `handlerReq` authoritative. Mirrors `stampRemoteIp` on the
+  // fetch path (which strips + stamps `req` directly). `upgradeRequest` already
+  // dropped any inbound copy of the header.
+  let ip;
+  try { ip = srv.requestIP(req)?.address; } catch {}
+  setTrustedRemoteIp(handlerReq, ip || '');
   const ok = srv.upgrade(req, {
     data: { wrapper, mod, req: handlerReq, params: match.params, pathname: url.pathname },
   });
@@ -253,7 +264,14 @@ async function bunUpgrade(req, srv, ctx) {
  */
 function upgradeRequest(req, url) {
   const headers = new Headers();
-  req.headers.forEach((v, k) => { if (!k.startsWith(':')) headers.set(k, v); });
+  // Skip a client-supplied `x-webjs-remote-ip`: it is a framework-internal trust
+  // header the caller re-stamps via the authoritative WeakMap (#778). Copying it
+  // would let a client spoof `clientIp` inside the WS handler on the fallback
+  // header read.
+  req.headers.forEach((v, k) => {
+    if (k.startsWith(':') || k === 'x-webjs-remote-ip') return;
+    headers.set(k, v);
+  });
   return new Request(url, { method: 'GET', headers });
 }
 
@@ -275,7 +293,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

@@ -14,7 +14,7 @@
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve, dirname, extname, sep } from 'node:path';
-import { redactStringsAndTemplates } from './js-scan.js';
+import { redactStringsAndTemplates, redactToPlaceholders } from './js-scan.js';
 
 /**
  * Per-appDir cache of the parsed `package.json "imports"` subpath-alias map
@@ -78,7 +78,7 @@ export function expandImportAlias(spec, appDir) {
 }
 
 /** @type {RegExp} match static `import … from '…'` and `import '…'` */
-const IMPORT_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/g;
+const IMPORT_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/gd;
 
 /**
  * @type {RegExp} match `export … from '…'` re-exports.
@@ -94,12 +94,16 @@ const IMPORT_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/g;
  *
  * Barrel files are common (`lib/index.ts` re-exports its siblings),
  * and the graph must follow these edges or downstream consumers of
- * the barrel see authorisation 404s on the underlying files. The
- * gap class excludes quotes and `;` (so the lazy match cannot cross
- * a statement boundary) but DOES allow newlines, so multi-line
- * brace lists are caught.
+ * the barrel see authorisation 404s on the underlying files. The gap
+ * class excludes quotes, `;`, AND the backtick but DOES allow newlines,
+ * so multi-line brace lists are caught. The primary defence against a
+ * stray `export` word inside a literal swallowing a real later edge is
+ * that `parseFile` scans over the FULLY-BLANKED mask (every comment /
+ * string / template / regex body blanked), so no keyword can anchor
+ * inside a literal at all (#753); the exclusions here are belt-and-
+ * suspenders on top of that.
  */
-const EXPORT_FROM_RE = /\bexport\b[^'";]+?\sfrom\s+['"]([^'"]+)['"]/g;
+const EXPORT_FROM_RE = /\bexport\b[^'";`]+?\sfrom\s+['"]([^'"]+)['"]/gd;
 
 /**
  * @type {RegExp} match a dynamic `import('…')` with a STRING-LITERAL specifier
@@ -118,7 +122,7 @@ const EXPORT_FROM_RE = /\bexport\b[^'";]+?\sfrom\s+['"]([^'"]+)['"]/g;
  * `import('./pages/' + name)` the char after the closing quote is `+`, neither
  * `,` nor `)`, so it does not match.
  */
-const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*[,)]/g;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*[,)]/gd;
 
 /**
  * @typedef {Map<string, Set<string>>} ModuleGraph
@@ -170,6 +174,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 +230,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)
@@ -437,16 +463,26 @@ async function parseFile(file, appDir, graph, seen, dynamic, bare) {
   // graph edge to whatever path that string names. Since this caller only
   // checks keyword-in-code-position, blank every literal body so a
   // code-example `import` string never becomes an edge.
+  // Scan for edges over the FULLY-BLANKED mask: every comment / string /
+  // template / regex body is blanked to spaces (delimiters kept), `${...}`
+  // holes stay as code. Reason (#753, found differentially): a stray `import` /
+  // `export` word inside a comment, template, OR regex literal must not anchor a
+  // lazy regex match (e.g. `EXPORT_FROM_RE`'s `[^'";`]+?`) that spans across the
+  // literal's closing delimiter and consumes the next real `from '<spec>'`,
+  // whose keyword then sits in the blanked literal and is dropped, silently
+  // losing the real edge (the gate then 404s a legitimately imported module).
+  // Scanning over the blanked mask means NO keyword can anchor inside any
+  // literal or comment at all, so the whole class of delimiter blind spots
+  // (comment, string, template, regex) is closed at once, and there is nothing
+  // left for a per-match position guard to reject. The specifier itself is a
+  // string (blanked here), so it is read back from raw `src` via the match's
+  // group indices (the `d` flag).
   const masked = redactStringsAndTemplates(src, true);
   const deps = new Set();
   /** @type {Set<string>} bare npm vendor specifiers imported by this file (#754) */
   const bareDeps = new Set();
   for (const re of [IMPORT_RE, EXPORT_FROM_RE]) {
-    for (const m of src.matchAll(re)) {
-      // m.index is the keyword start (`\bimport` / `\bexport`). If that
-      // position is blanked in the mask, the match lives inside a literal
-      // and is not a real import edge.
-      if (masked[m.index] === ' ') continue;
+    for (const m of masked.matchAll(re)) {
       // A statement-leading `import type { X }` / `import type * as X` /
       // `import type Foo` (default type import) / `export type { X }` /
       // `export type *` is fully erased by the TS stripper, so it never becomes
@@ -459,22 +495,17 @@ async function parseFile(file, appDir, graph, seen, dynamic, bare) {
       //     followed by `from` is NOT type-only.
       //   - a MIXED `import { type A, b }` does NOT lead with `type`, so it is
       //     kept (its `b` binding is a real runtime edge).
+      // (m[0] here is over the mask, which keeps the binding syntax verbatim.)
       // #805
       const lead = m[0];
       const typeOnly =
         /^(?:import|export)\s+type\s*[{*]/.test(lead) ||
         (/^import\s+type\s+[A-Za-z_$]/.test(lead) && !/^import\s+type\s+from\b/.test(lead));
       if (typeOnly) continue;
-      const spec = m[1];
-      // Guard a match whose `from '<spec>'` tail reaches INTO a blanked literal:
-      // EXPORT_FROM_RE's lazy `[^'";]+?` can span a template body to a `from`
-      // written inside example code (`export const t = html\`...import x from
-      // 'left-pad'\``), so the KEYWORD is real but the SPECIFIER is not. A real
-      // string keeps its delimiters in the mask (only the body blanks), while a
-      // template body blanks whole, so a blanked opening quote means the
-      // specifier is inside a literal and the match is spurious.
-      const quoteAt = m.index + m[0].length - spec.length - 2;
-      if (masked[quoteAt] === ' ') continue;
+      // The specifier is read from RAW src at the match's captured-group indices
+      // (the group is the blanked string body in the mask; its position is the
+      // real specifier in src).
+      const spec = src.slice(m.indices[1][0], m.indices[1][1]);
       // Only resolve relative imports + `#`-style subpath aliases (#555)
       // within the project. A bare npm specifier (dayjs) has no alias match
       // and is skipped FROM THE GRAPH, but recorded as a vendor edge so SSR
@@ -491,12 +522,30 @@ async function parseFile(file, appDir, graph, seen, dynamic, bare) {
   }
   // Dynamic `import('…')` with a string-literal specifier (#751): a separate
   // edge class so the gate admits the lazily-loaded module (no 404) without
-  // preloading it. Same redaction-mask + alias rules as the static scan. A
-  // target already statically imported is not duplicated as a dynamic edge.
+  // preloading it. A target already statically imported is not duplicated as a
+  // dynamic edge.
+  //
+  // The static scan above runs over the FULLY-BLANKED mask, which also blanks
+  // the code inside `${...}` template holes. That drops a dynamic import written
+  // directly inside a hole (`html\`${import('./x.ts')}\``), which the AST counts
+  // as an edge but the mask scan did not, so the gate 404s a legitimately-loaded
+  // module (#918, the admit-fewer direction of the #753 family). So the dynamic
+  // scan instead runs over the PLACEHOLDER redaction (#634), which keeps `${...}`
+  // hole code readable (so a hole-position `import(...)` IS seen) while still
+  // tokenizing string / template-TEXT bodies to `__STR_<idx>__` and blanking
+  // comment / regex bodies (so a dynamic import written as literal TEXT is NOT
+  // an edge). The #753 swallow class stays closed because `DYNAMIC_IMPORT_RE` is
+  // tightly anchored on `import(`, never a lazy cross-delimiter span. The
+  // specifier surfaces as a `__STR_<idx>__` token, recovered from `literals`; a
+  // computed `import(expr)` still falls out (its char after the quote is not
+  // `,`/`)`), preserving the documented limitation.
+  const { redacted: holeAware, literals } = redactToPlaceholders(src);
   const dynDeps = new Set();
-  for (const m of src.matchAll(DYNAMIC_IMPORT_RE)) {
-    if (masked[m.index] === ' ') continue;
-    const spec = m[1];
+  for (const m of holeAware.matchAll(DYNAMIC_IMPORT_RE)) {
+    const token = m[1];
+    const pm = /^__STR_(\d+)__$/.exec(token);
+    const spec = pm ? literals[Number(pm[1])] : token;
+    if (spec == null) continue;
     if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) continue;
     const resolved = resolveImport(spec, file, appDir);
     if (resolved && !deps.has(resolved)) dynDeps.add(resolved);

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';
@@ -194,25 +194,30 @@ export async function ssrPage(route, params, url, opts) {
     // enter the viewport.
     const { eager: eagerComponents, lazy: lazyComponents } =
       componentPreloads(suspenseCtx.usedComponents, opts.appDir, opts.elidableComponents);
+    // The walk roots for BOTH preload passes are the BOOT's actually-shipped
+    // module set (`moduleUrls`, which already drops inert page/layout modules and
+    // substitutes an import-only page with its components), NOT the raw route
+    // entries `[route.file, ...route.layouts]`. Rooting at the raw entries would
+    // walk a dropped page's SSR-only subtree (a direct import OR a relative
+    // helper) and hint a `modulepreload` for a module nothing that ships imports,
+    // an over-fetch (#780, the app-module analog of the #754 vendor over-fetch).
+    const shippedRoots = moduleUrls.map((u) =>
+      resolve(opts.appDir, u.startsWith('/') ? u.slice(1) : u));
     const preloads = deduplicatedPreloads(
       eagerComponents,
       moduleUrls,
       opts.moduleGraph,
-      [route.file, ...route.layouts],
+      shippedRoots,
       opts.appDir,
       opts.serverFiles,
       opts.elidableComponents,
     );
     // Vendor modulepreload (#754): flatten the npm CDN waterfall by hinting the
     // vendor URLs the page's SHIPPED modules actually import, fetched in parallel
-    // instead of discovered level by level. The walk roots are the BOOT's shipped
-    // module set (`moduleUrls`, which already drops inert page/layout modules and
-    // substitutes an import-only page with its components) plus the rendered
-    // components, so a vendor reached ONLY through a dropped module (a page's
-    // SSR-only direct import OR its SSR-only relative helper) is never preloaded
-    // (no over-fetch).
-    const shippedRoots = moduleUrls.map((u) =>
-      resolve(opts.appDir, u.startsWith('/') ? u.slice(1) : u));
+    // instead of discovered level by level. Same shipped-module roots as the
+    // app-module walk above, so a vendor reached ONLY through a dropped module
+    // (a page's SSR-only direct import OR its SSR-only relative helper) is never
+    // preloaded (no over-fetch).
     const vendorPreloads = vendorPreloadTargets(
       reachedVendorSpecifiers(
         opts.moduleGraph,
@@ -419,6 +424,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 +452,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 });
 }
@@ -1579,10 +1586,24 @@ function componentPreloads(usedTags, appDir, elidable) {
  * Merge component preloads with transitive dependencies from the module
  * graph, then deduplicate against the already-imported module URLs.
  *
+ * The walk ROOTS (`entryFiles`) are the boot's actually-SHIPPED page/layout
+ * module set (the caller passes the absolute paths of `moduleUrls`, which
+ * already drops an inert page/layout and substitutes an import-only page with
+ * its components), NOT the raw `[route.file, ...route.layouts]` route entries.
+ * This matches `reachedVendorSpecifiers`' roots so the two walks stay
+ * consistent. Rooting at the shipped set means a module reached ONLY through a
+ * dropped page/layout (its SSR-only direct app import OR its SSR-only relative
+ * helper) is never a walk root's dep, so it gets no `modulepreload` hint (no
+ * over-fetch, #780). A module that also ships some other way (a component shared
+ * with a live route, or reached via an import-only page's substituted
+ * components) is still reached through a real shipped root, so its hint stays
+ * (no under-fetch). `seen = new Set(moduleUrls)` already excludes the shipped
+ * modules' own URLs; the shipped-roots change closes the TRANSITIVE gap.
+ *
  * @param {string[]} componentUrls  direct component module URLs
  * @param {string[]} moduleUrls     boot script imports (page + layouts)
  * @param {import('./module-graph.js').ModuleGraph | undefined} graph
- * @param {string[]} entryFiles     absolute paths of page + layout files
+ * @param {string[]} entryFiles     absolute paths of the SHIPPED page/layout modules (from `moduleUrls`)
  * @param {string} appDir
  * @param {Set<string>} [elidableComponents]  absolute paths to skip in the walk
  * @returns {string[]}
@@ -1717,6 +1738,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/src/websocket.js

@@ -4,6 +4,7 @@ import { urlFromRequest } from './forwarded.js';
 import { registerClient } from './broadcast.js';
 import { loadWsModule } from './listener-core.js';
 import { makeThenable } from './thenable-params.js';
+import { setTrustedRemoteIp } from './rate-limit.js';
 
 /**
  * WebSocket support.
@@ -106,7 +107,17 @@ function buildRequestFromUpgrade(req, url) {
   const headers = {};
   for (const [k, v] of Object.entries(req.headers)) {
     if (k.startsWith(':')) continue;
+    // Never copy an inbound `x-webjs-remote-ip`: it is a framework-internal
+    // trust header a client could spoof on the upgrade. The real socket IP is
+    // stamped below via the authoritative WeakMap (#778, the WS-seam analog of
+    // the #773 fetch-path IP-trust fix).
+    if (k === 'x-webjs-remote-ip') continue;
     headers[k] = Array.isArray(v) ? v.join(',') : String(v ?? '');
   }
-  return new Request(url, { method: 'GET', headers });
+  const webReq = new Request(url, { method: 'GET', headers });
+  // Stamp the framework-trusted socket IP so `clientIp(req)` inside the `WS`
+  // handler returns the real peer address (the WeakMap is authoritative and
+  // ignores the inbound header), matching the fetch path's `toWebRequest`.
+  setTrustedRemoteIp(webReq, req.socket?.remoteAddress || '');
+  return webReq;
 }

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" }
         }
       }
     },