@webjsdev/server 0.8.0 → 0.8.2

package/package.json

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

package/src/actions.js

@@ -46,8 +46,9 @@ async function rpcResponse(payload, init = {}) {
  * ignored.
  *
  * The server:
- *   1. Scans the app tree on boot, classifying server files into
- *      RPC-callable actions vs. server-only utilities.
+ *   1. Scans the app tree lazily on the first request (in `ensureReady`),
+ *      classifying server files into RPC-callable actions vs. server-only
+ *      utilities. Hashing is eager-per-file; only `expose()` files load.
  *   2. Serves a generated ES-module stub when the browser imports
  *      the file URL (an RPC stub for actions, a throw-at-load stub
  *      for server-only utilities).
@@ -106,7 +107,22 @@ export async function buildActionIndex(appDir, dev) {
     const h = await hashFile(file);
     hashToFile.set(h, file);
     fileToHash.set(file, h);
-    // Load module once at scan time to pick up any expose() tags.
+    // Pure-RPC actions are NOT executed at boot: invokeAction and
+    // serveActionStub import the module on demand (first RPC call / first stub
+    // fetch), so the hash index above is all the analysis needs. Eagerly
+    // running every server module (and its transitive Prisma init, DB
+    // connects, etc.) would be wasted work. The one thing that DOES need eager loading is expose(),
+    // which registers a REST route the router must know before any request can
+    // hit it. So load only files that REFERENCE expose. We match the bare
+    // `expose` identifier (not `expose(`) so an aliased import
+    // (`import { expose as exp }`, whose import clause still names `expose`) is
+    // not missed: missing it would silently 404 that file's REST route. A stray
+    // mention in a comment or string only over-matches, costing one harmless
+    // extra module load; the common pure-RPC file never names `expose` and so
+    // still defers entirely.
+    let src = '';
+    try { src = await readFile(file, 'utf8'); } catch {}
+    if (!/\bexpose\b/.test(src)) continue;
     try {
       const mod = await loadModule(file, dev);
       for (const [name, fn] of Object.entries(mod)) {

package/src/check.js

@@ -62,7 +62,7 @@ export const RULES = [
   {
     name: 'components-have-register',
     description:
-      'Component files that define a class extending WebComponent must register the class with ClassName.register(\'tag\') (or customElements.define). The server-side scanner derives the module URL from the file path at boot.',
+      'Component files that define a class extending WebComponent must register the class with ClassName.register(\'tag\') (or customElements.define). The server-side scanner derives the module URL from the file path.',
   },
   {
     name: 'no-server-env-in-components',

package/src/component-elision.js

@@ -648,28 +648,80 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     }
   }
 
-  // Ship any component whose transitive import closure does client work,
-  // through ANY import (not just npm): a relative helper that imports a
-  // reactive primitive (shared module-scope signal), enables the client
-  // router, references a browser global, or side-effect imports a package.
-  // Same closure rule the route analysis applies, so a display-only
-  // component that pulls in a client-effecting helper still ships.
-  const closureIsClientEffecting = (d) =>
-    reactiveFiles.has(d) || clientRouterFiles.has(d) || clientGlobalOrBareFiles.has(d);
+  // Reverse import edges (who imports each file), built once from the graph.
+  // Drives both the closure-client-work reachability below and the fixpoint's
+  // import rule, each in O(N+E) rather than a per-component closure walk.
+  /** @type {Map<string, Set<string>>} */
+  const importersOf = new Map();
+  for (const [file, deps] of moduleGraph) {
+    for (const dep of deps) {
+      let set = importersOf.get(dep);
+      if (!set) { set = new Set(); importersOf.set(dep, set); }
+      set.add(file);
+    }
+  }
+
+  // Files that reach client work through their imports: a reactive primitive,
+  // the client router, a browser global, an `@event` binding, or a side-effect
+  // npm import. Computed by propagating BACKWARD from the client-effecting
+  // files through the reverse edges, stopping at `.server` files (the forward
+  // closure skips them, since the browser only ever sees their stub). This is
+  // O(N+E) instead of a full transitive-closure walk per component, which was
+  // the second O(N^2) on a deep component chain.
+  /** @type {Set<string>} */
+  const reachesClientWork = new Set();
+  {
+    const work = [];
+    for (const f of [...reactiveFiles, ...clientRouterFiles, ...clientGlobalOrBareFiles]) {
+      if (!reachesClientWork.has(f)) { reachesClientWork.add(f); work.push(f); }
+    }
+    while (work.length) {
+      const node = /** @type {string} */ (work.pop());
+      const importers = importersOf.get(node);
+      if (!importers) continue;
+      for (const imp of importers) {
+        if (serverFiles.has(imp)) continue;  // a server file blocks the forward closure
+        if (!reachesClientWork.has(imp)) { reachesClientWork.add(imp); work.push(imp); }
+      }
+    }
+  }
+
+  // Ship any component whose transitive import closure does client work (the
+  // helper-imports-a-signal case): it ships if any of its direct, non-server
+  // deps reaches client work. Equivalent to the old per-component closure walk
+  // (a component that is itself client-effecting is already shipping via
+  // analyzeComponentSource), but linear.
   if (appDir) {
     for (const file of componentFiles) {
       if (mustShip.has(file)) continue;
-      const deps = transitiveDeps(moduleGraph, [file], appDir, serverFiles);
-      if (deps.some(closureIsClientEffecting)) mustShip.add(file);
+      const deps = moduleGraph.get(file);
+      if (!deps) continue;
+      for (const dep of deps) {
+        if (serverFiles.has(dep)) continue;
+        if (reachesClientWork.has(dep)) { mustShip.add(file); break; }
+      }
     }
   }
 
-  // Tags each component can emit on a client re-render (own + helper closure).
+  // Tags each component can emit on a client re-render: its OWN rendered tags
+  // plus tags returned by the template HELPERS it imports (the lib/utils/ui.ts
+  // pattern). The closure deliberately SKIPS component and server files:
+  // importing another component does not mean rendering its tag (a rendered tag
+  // is already in the importer's own source via extractRenderedTags), and a
+  // server file renders nothing client-side. Following component edges here
+  // makes the closure O(N^2) in time AND memory on a deep component chain
+  // (every component would accumulate every downstream tag); helper-only
+  // closures keep it linear. This is verdict-SAFE: it never elides a component
+  // that the render rule requires to ship (so it can never break a page), and
+  // it actually elides strictly MORE in some shapes, because following
+  // component edges made the old version over-ship components whose tags
+  // nothing actually renders client-side.
+  const tagClosureSkip = new Set([...componentFiles, ...serverFiles]);
   /** @type {Map<string, Set<string>>} */
   const emittableTags = new Map();
   for (const file of componentFiles) {
     const tags = new Set(fileTags.get(file));
-    const deps = appDir ? transitiveDeps(moduleGraph, [file], appDir) : [];
+    const deps = appDir ? transitiveDeps(moduleGraph, [file], appDir, tagClosureSkip) : [];
     for (const dep of deps) {
       const dt = fileTags.get(dep);
       if (dt) for (const t of dt) tags.add(t);
@@ -677,24 +729,26 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     emittableTags.set(file, tags);
   }
 
-  // Fixpoint: render rule + import rule.
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const parent of mustShip) {
-      const tags = emittableTags.get(parent);
-      if (!tags) continue;
+  // Fixpoint by worklist (render rule + import rule), O(N+E). Seed with the
+  // components already known to ship; each shipping node forces the components
+  // whose tags it can emit (render rule) and the COMPONENT files that import it
+  // (import rule). Replaces the old iterate-until-stable double loop, which was
+  // O(N^2) per pass and O(N^3) / out-of-memory on a deep render chain.
+  const queue = [...mustShip];
+  while (queue.length) {
+    const node = /** @type {string} */ (queue.pop());
+    const tags = emittableTags.get(node);
+    if (tags) {
       for (const tag of tags) {
         const childFile = tagToFile.get(tag);
-        if (childFile && !mustShip.has(childFile)) { mustShip.add(childFile); changed = true; }
+        if (childFile && !mustShip.has(childFile)) { mustShip.add(childFile); queue.push(childFile); }
       }
     }
-    for (const file of componentFiles) {
-      if (mustShip.has(file)) continue;
-      const deps = moduleGraph.get(file);
-      if (!deps) continue;
-      for (const dep of deps) {
-        if (componentFiles.has(dep) && mustShip.has(dep)) { mustShip.add(file); changed = true; break; }
+    const importers = importersOf.get(node);
+    if (importers) {
+      for (const imp of importers) {
+        if (!componentFiles.has(imp)) continue;  // import rule is component -> component
+        if (!mustShip.has(imp)) { mustShip.add(imp); queue.push(imp); }
       }
     }
   }

package/src/component-scanner.js

@@ -2,7 +2,7 @@
  * Server-side scanner that walks the app tree and records the
  * browser-visible URL for every webjs component module.
  *
- * Called once at server boot. Results are used to prime the core
+ * Called once on the first request (lazily, via `ensureReady`), then memoized. Results are used to prime the core
  * registry (`primeModuleUrl`) BEFORE any SSR render: so when a page
  * renders a component tag, `lookupModuleUrl(tag)` already has the URL
  * ready for `<link rel="modulepreload">` hints.
@@ -18,11 +18,24 @@
  * we only need `{ tag, className, moduleUrl }` tuples.
  */
 
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { sep } from 'node:path';
 import { walk } from './fs-walk.js';
 import { primeModuleUrl } from '@webjsdev/core';
 
+/**
+ * mtime-keyed cache of extracted components per file, so a rebuild re-reads
+ * only files that changed (an unchanged file reuses its cached component list
+ * after a single `stat`). Makes the component scan incremental for large apps.
+ * Keyed by mtime AND size (a same-tick length-changing edit is caught even on
+ * coarse-mtime filesystems).
+ * @type {Map<string, { mtimeMs: number, size: number, comps: Array<{ tag: string, className: string }> }>}
+ */
+const SCAN_CACHE = new Map();
+
+/** Introspection for tests/ops: is `file` currently in the scan cache? */
+export function _scanCacheHas(file) { return SCAN_CACHE.has(file); }
+
 /**
  * Recognise either registration pattern:
  *
@@ -70,21 +83,39 @@ export function extractComponents(src) {
 export async function scanComponents(appDir) {
   /** @type {Array<{ tag: string, className: string, moduleUrl: string, file: string }>} */
   const components = [];
+  /** @type {Set<string>} live component files this scan, for cache eviction */
+  const seen = new Set();
   const filter = (p) =>
     /\.m?[jt]sx?$/.test(p) &&
     !/\.(test|spec)\.m?[jt]sx?$/.test(p) &&
     !/\.server\.m?[jt]s$/.test(p);
 
   for await (const file of walk(appDir, filter)) {
-    let src;
-    try { src = await readFile(file, 'utf8'); } catch { continue; }
-    const comps = extractComponents(src);
+    let mtimeMs, size;
+    try { const st = await stat(file); mtimeMs = st.mtimeMs; size = st.size; } catch { continue; }
+    seen.add(file); // mark live (hit and miss) for cache eviction
+    let comps;
+    const cached = SCAN_CACHE.get(file);
+    if (cached && cached.mtimeMs === mtimeMs && cached.size === size) {
+      comps = cached.comps;
+    } else {
+      let src;
+      try { src = await readFile(file, 'utf8'); } catch { continue; }
+      comps = extractComponents(src);
+      SCAN_CACHE.set(file, { mtimeMs, size, comps });
+    }
     if (!comps.length) continue;
     const moduleUrl = toUrlPath(file, appDir);
     for (const c of comps) {
       components.push({ ...c, moduleUrl, file });
     }
   }
+  // Evict scan-cache entries for files no longer walked (renamed/deleted),
+  // scoped to this app so a multi-app process keeps other apps' entries.
+  const prefix = appDir.endsWith(sep) ? appDir : appDir + sep;
+  for (const key of SCAN_CACHE.keys()) {
+    if ((key === appDir || key.startsWith(prefix)) && !seen.has(key)) SCAN_CACHE.delete(key);
+  }
   return components;
 }
 

package/src/dev.js

@@ -58,7 +58,7 @@ import {
 import { defaultLogger } from './logger.js';
 import { withRequest } from './context.js';
 import { attachWebSocket } from './websocket.js';
-import { scanBareImports, resolveVendorImports, serveDownloadedBundle, clearVendorCache } from './vendor.js';
+import { scanBareImports, resolveVendorImports, serveDownloadedBundle, clearVendorCache, hasVendorPin, readPinFile } from './vendor.js';
 import { buildModuleGraph, transitiveDeps, reachableFromEntries, resolveImport } from './module-graph.js';
 import { primeComponentRegistry, findOrphanComponents, scanComponents } from './component-scanner.js';
 import { analyzeElision, elideImportsFromSource } from './component-elision.js';
@@ -67,7 +67,7 @@ import { analyzeElision, elideImportsFromSource } from './component-elision.js';
 function kebab(name) {
   return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 }
-import { setVendorEntries, setCoreInstall } from './importmap.js';
+import { setVendorEntries, setCoreInstall, publishBuildId } from './importmap.js';
 import { urlFromRequest } from './forwarded.js';
 
 const MIME = {
@@ -212,149 +212,346 @@ export async function createRequestHandler(opts) {
     existsSync(join(distDir, 'webjs-core-browser.js'));
   await setCoreInstall(coreDir, distComplete);
 
-  // Build module dependency graph for transitive preload hints.
-  const moduleGraph = await buildModuleGraph(appDir);
-
-  // Scan for component classes and prime their module URLs into the
-  // core registry. SSR uses this for modulepreload hints without
-  // requiring authors to pass `import.meta.url` themselves. The same
-  // scan result feeds the browser-bound graph computation below,
-  // avoiding a duplicate appDir walk at boot.
-  const components = await scanComponents(appDir);
-  await primeComponentRegistry(appDir, components);
-
-  const routeTable = await buildRouteTable(appDir);
-
-  // Determine which component modules are display-only and which page/layout
-  // route modules are inert, so both can be elided from the browser (no JS
-  // download). Static analysis only; the sets bias conservatively toward
-  // shipping. See component-elision.js. The project-level `webjs.elide: false`
-  // switch in package.json skips the analysis entirely (empty sets, so nothing
-  // is stripped and the importmap keeps every vendor dep).
-  const elideEnabled = await readElideEnabled(appDir);
-  const { elidableComponents, inertRouteModules } = elideEnabled
-    ? await analyzeElision(
-        components,
-        collectRouteModules(routeTable),
-        moduleGraph,
-        (f) => readFile(f, 'utf8'),
-        appDir,
-      )
-    : { elidableComponents: new Set(), inertRouteModules: new Set() };
-
-  // Scan for bare npm imports and register vendor import map entries.
-  // Runs AFTER elision so vendor deps reachable only through display-only
-  // components are excluded from the importmap.
-  const bareImports = await scanBareImports(appDir, new Set([...elidableComponents, ...inertRouteModules]));
-  const initialVendor = await resolveVendorImports(bareImports, appDir);
-  await setVendorEntries(initialVendor.imports, initialVendor.integrity);
-
-  // Dev-time guardrail: warn about any class extending WebComponent
-  // that isn't registered via customElements.define() in its own
-  // module. Without registration, <my-tag> elements silently stay as
-  // HTMLUnknownElement in the browser: a common early-stage footgun.
-  if (dev) {
-    const orphans = await findOrphanComponents(appDir);
-    for (const { className, file } of orphans) {
-      logger.warn?.(
-        `[webjs] ${className} extends WebComponent but has no customElements.define(...) call in ${file}. ` +
-          `Add \`customElements.define('<tag-name>', ${className});\` at the bottom of the file ` +
-          `or <${kebab(className)}> tags won't upgrade in the browser.`,
-      );
+  // When an app commits a vendor pin (.webjs/vendor/importmap.json) it carries a
+  // deterministic vendor map that is cheap to read (one file, no analysis, no
+  // network). Resolve it AT BOOT and publish the build id immediately so the
+  // process advertises a stable, non-empty id from its very first response: a
+  // freshly-deployed pinned process is detected as a new deploy by old-deploy
+  // clients with zero warmup window. Mirrors Rails importmap (committed pins
+  // rendered deterministically at runtime). Pinning stays optional; an unpinned
+  // app does no vendor work at boot and publishes its id after the first
+  // successful resolve instead. Either way the EXPENSIVE analysis (graph, scan,
+  // gate, elision) and the UNPINNED jspm resolve stay deferred to the first
+  // request, so #143's win is intact; only the cheap committed-file read moves
+  // back to boot, and only when a VALID pin exists. A committed pin file is
+  // served as-is (elision never prunes it), so the boot-resolved map equals the
+  // final served map and the published id is authoritative.
+  //
+  // Validate the pin with readPinFile BEFORE treating the app as pinned-at-boot.
+  // hasVendorPin is a cheap existence check; a malformed pin (exists but
+  // unparseable) must NOT short-circuit here, because resolveVendorImports would
+  // then fall through to its bare-import scan thunk, and the boot-time thunk is
+  // empty (the real scan is part of the deferred analysis). A broken pin instead
+  // falls through to the normal deferred resolve, which carries the real scan
+  // thunk and degrades gracefully, exactly as an unpinned app does.
+  let bootVendorPinned = false;
+  if (hasVendorPin(appDir) && (await readPinFile(appDir))) {
+    try {
+      const v = await resolveVendorImports(appDir, () => new Set());
+      await setVendorEntries(v.imports, v.integrity);
+      publishBuildId();
+      bootVendorPinned = true;
+    } catch (e) {
+      // An unexpected failure applying a VALID pin (e.g. setVendorEntries
+      // throwing) is non-fatal: leave bootVendorPinned false so the deferred
+      // resolve re-attempts on the first request. Boot stays resilient.
+      logger.error?.(`[webjs] applying the committed vendor pin at boot failed (will retry on the first request):`, e);
     }
   }
 
+  // Whole-app analysis (module graph, component scan, browser-bound gate,
+  // action index, middleware, elision, vendor) is NOT run at boot. It is
+  // computed on the first request via ensureReady() below and memoized, so the
+  // server starts without walking or reading the app's source, executing any
+  // server module, or hitting the network. Only the route table is built
+  // eagerly: it is a cheap directory scan (no code reads), and routing, Early
+  // Hints, and WebSocket lookups need it available before the first request.
+  const routeTable = await buildRouteTable(appDir);
+
   const state = {
     routeTable,
-    actionIndex: await buildActionIndex(appDir, dev),
-    middleware: await loadMiddleware(appDir, dev, logger),
+    actionIndex: null,
+    middleware: null,
     logger,
-    bareImports,
-    moduleGraph,
-    elidableComponents,
-    inertRouteModules,
-    browserBoundFiles: computeBrowserBoundFiles(routeTable, moduleGraph, components, appDir),
+    moduleGraph: null,
+    elidableComponents: new Set(),
+    inertRouteModules: new Set(),
+    browserBoundFiles: null,
   };
 
-  // Rebuilds are serialized so a slow rebuild #1 (e.g. waiting on a
-  // jspm.io fetch) cannot overwrite a fresher rebuild #2's
-  // setVendorEntries / route table when it finally finishes. Without
-  // this, two file edits inside one fs.watch debounce window could
-  // produce a permanently-stale importmap until the next rebuild.
-  // Each rebuild also gets a monotonic token; setVendorEntries is only
-  // applied if its token still matches the latest scheduled rebuild.
+  // All whole-app analysis is built lazily on the first request, memoized so
+  // boot does none of it. It runs in two stages. The deterministic analysis
+  // (module graph, component scan + prime, browser-bound gate, action index,
+  // middleware, elision) is network-free and, once built, never re-runs unless
+  // a rebuild invalidates it; readiness gates on it. Vendor resolution is a
+  // SEPARATE, best-effort stage: a pinned app reads a committed importmap file,
+  // an unpinned app auto-fetches from jspm. It does NOT gate readiness, so an
+  // offline or partially-unresolvable app still boots. A transient vendor
+  // failure is re-attempted on the NEXT ensureReady call (driven by an incoming
+  // request, a readiness probe, or the warm-up), with no background timer: the
+  // platform's traffic and probes are the retry loop. `readyError` holds a
+  // propagating analysis failure so /__webjs/ready can report it.
+  let analysisDone = false;        // deterministic analysis complete (readiness gate)
+  // A pinned app already resolved + published its vendor map at boot (above), so
+  // the deferred vendor stage is a no-op from the start; an unpinned app starts
+  // false and resolves on the first request.
+  let vendorResolved = bootVendorPinned;      // vendor map fully resolved (or permanently tolerated)
+  let vendorAttemptedOnce = bootVendorPinned; // the first (blocking) vendor attempt has run
+  let vendorGen = 0;               // bumped on rebuild; a stale resolve cannot flip vendorResolved
+  let readyDone = false;           // mirrors analysisDone; the /__webjs/ready gate
+  /** @type {unknown} */
+  let readyError = null;
+  /** @type {Promise<void> | null} */
+  let readyInFlight = null;
+  async function ensureReady() {
+    // Fully warm: analysis done and vendor resolved. Nothing to do.
+    if (analysisDone && vendorResolved) return;
+    // A warm pass is in flight (the analysis and/or the FIRST vendor attempt).
+    // Await it rather than serving past it: a concurrent early request must get
+    // the FINAL importmap, never a half-resolved one. This is what makes the
+    // unpinned warmup flawless. The first attempt's jspm resolve is
+    // timeout-bounded (vendor.js), so an offline app cannot hang here: on
+    // timeout the resolve returns and the response is served with an empty,
+    // reload-safe build id, then the retry below completes it. Without this
+    // wait, a request arriving mid-resolve would serve a partial map and an
+    // empty-then-changing build id, the exact warmup drift that hard-reloads
+    // and wipes a half-filled form.
+    if (readyInFlight) { await readyInFlight; return; }
+    // Analysis warm but the first vendor attempt already completed and failed:
+    // re-attempt WITHOUT blocking this request. The single-flight dedupes
+    // concurrent attempts; success flips the flag AND publishes the build id.
+    // This is the request/probe-driven retry (no timer). Until it succeeds the
+    // served build id stays empty (reload-safe), so no navigation hard-reloads.
+    if (analysisDone && vendorAttemptedOnce) {
+      const gen = vendorGen;
+      resolveAndApplyVendor().then((ok) => { if (ok && gen === vendorGen) { vendorResolved = true; publishBuildId(); } }).catch(() => {});
+      return;
+    }
+    // Otherwise run the (single-flighted) full warm: the analysis, then the
+    // first vendor attempt, awaited so the first response carries the import map.
+    if (!readyInFlight) {
+      readyInFlight = (async () => {
+        /** @type {Record<string, number>} */
+        const t = {};
+        let ranAnalysis = false, ranVendor = false;
+        const now = () => performance.now();
+        try {
+          if (!analysisDone) {
+            let m = now();
+            state.moduleGraph = await buildModuleGraph(appDir);
+            t.graph = now() - m; m = now();
+            const components = await scanComponents(appDir);
+            await primeComponentRegistry(appDir, components);
+            t.scan = now() - m; m = now();
+            state.browserBoundFiles = computeBrowserBoundFiles(state.routeTable, state.moduleGraph, components, appDir);
+            t.gate = now() - m; m = now();
+            state.actionIndex = await buildActionIndex(appDir, dev);
+            t.actions = now() - m; m = now();
+            state.middleware = await loadMiddleware(appDir, dev, logger);
+            t.middleware = now() - m; m = now();
+            const r = (await readElideEnabled(appDir))
+              ? await analyzeElision(components, collectRouteModules(state.routeTable),
+                  state.moduleGraph, (f) => readFile(f, 'utf8'), appDir)
+              : { elidableComponents: new Set(), inertRouteModules: new Set() };
+            state.elidableComponents = r.elidableComponents;
+            state.inertRouteModules = r.inertRouteModules;
+            t.elision = now() - m;
+            if (dev) {
+              for (const { className, file } of await findOrphanComponents(appDir)) {
+                logger.warn?.(
+                  `[webjs] ${className} extends WebComponent but has no customElements.define(...) call in ${file}. ` +
+                    `Add \`customElements.define('<tag-name>', ${className});\` or <${kebab(className)}> tags won't upgrade.`,
+                );
+              }
+            }
+            analysisDone = true;
+            ranAnalysis = true;
+          }
+          readyError = null;
+          if (!vendorResolved) {
+            const m = now();
+            const gen = vendorGen;
+            vendorAttemptedOnce = true;
+            const ok = await resolveAndApplyVendor();
+            t.vendor = now() - m;
+            ranVendor = true;
+            // Only memoize success (and only if a rebuild didn't intervene). A
+            // transient failure leaves vendorResolved false; the next ensureReady
+            // call re-attempts it non-blocking. A permanent unresolvable (jspm
+            // 401) reports ok and is tolerated, so it does not loop. On success
+            // the importmap is now authoritatively final, so publish the build
+            // id: from here every response advertises the same stable value and
+            // the client router's deploy detection works without warmup drift.
+            if (ok && gen === vendorGen) { vendorResolved = true; publishBuildId(); }
+          }
+          // Readiness reflects a FULLY warm instance: the deterministic analysis
+          // AND the first vendor attempt have both completed (note: completed,
+          // not necessarily succeeded). A readiness-gated platform (Railway
+          // healthcheckPath, k8s readinessProbe) therefore admits traffic only
+          // AFTER the build id is published (vendor resolved) or definitively
+          // empty (a bounded vendor failure), never DURING the vendor-resolution
+          // window. This is what makes warm-up actually protect users: the prior
+          // instance keeps serving until the new one is fully warm, so a real
+          // request lands on a warm instance with a stable build id instead of
+          // racing the resolve. The first vendor attempt is bounded (the jspm
+          // fetch timeout in vendor.js), so an offline / CDN-degraded app still
+          // becomes ready shortly after that timeout, degraded but reload-safe,
+          // which preserves the boot resilience #143 introduced. The gate is the
+          // FIRST attempt only: a transient failure still flips readyDone here,
+          // so a later non-blocking retry never has to re-open the readiness gate.
+          readyDone = true;
+          if (ranAnalysis) {
+            const ms = (x) => Math.round(x || 0);
+            const total = ms(t.graph) + ms(t.scan) + ms(t.gate) + ms(t.actions) + ms(t.middleware) + ms(t.elision) + ms(t.vendor);
+            logger.info?.(
+              `[webjs] analysis warm in ${total}ms (graph ${ms(t.graph)}, scan ${ms(t.scan)}, ` +
+                `gate ${ms(t.gate)}, actions ${ms(t.actions)}, middleware ${ms(t.middleware)}, ` +
+                `elision ${ms(t.elision)}, vendor ${ms(t.vendor)})`,
+            );
+          } else if (ranVendor && vendorResolved) {
+            logger.info?.(`[webjs] vendor resolved in ${Math.round(t.vendor || 0)}ms`);
+          }
+        } catch (e) {
+          readyError = e;
+          throw e;
+        } finally {
+          readyInFlight = null;
+        }
+      })();
+    }
+    await readyInFlight;
+  }
+
+  // All vendor resolves funnel through one single-flight so two never overlap
+  // (resolveVendorImports reports a transient failure via a module-global flag
+  // that only one in-flight resolve may safely touch). Never rejects; returns
+  // the resolve's ok flag (false on a transient failure, applying whatever
+  // partial map resolved so the app is no worse off).
+  /** @type {Promise<boolean> | null} */
+  let vendorResolveInFlight = null;
+  function resolveAndApplyVendor() {
+    if (vendorResolveInFlight) return vendorResolveInFlight;
+    vendorResolveInFlight = (async () => {
+      try {
+        const v = await resolveVendorImports(appDir,
+          () => scanBareImports(appDir, new Set([...state.elidableComponents, ...state.inertRouteModules])));
+        await setVendorEntries(v.imports, v.integrity);
+        return v.ok;
+      } catch (e) {
+        logger.error?.(`[webjs] vendor resolve failed (will retry on the next request):`, e);
+        return false;
+      }
+    })().finally(() => { vendorResolveInFlight = null; });
+    return vendorResolveInFlight;
+  }
+
+  // Optional app-level readiness check. A `readiness.{js,ts}` file at the app
+  // root may default-export an async function; /__webjs/ready runs it once the
+  // analysis is warm, so readiness can reflect LIVE dependency health (a DB
+  // ping, a queue connection) that the static analysis cannot see. Returning
+  // false or throwing reports the instance not ready (503), so a readinessProbe
+  // holds traffic off an instance whose deps are down. Absent file => analysis-
+  // warm is the only gate. The module is cached per build (cleared on rebuild);
+  // the function itself runs on every probe so it reflects current state.
+  let readinessFn; // undefined = unloaded, null = no file, function = loaded
+  async function getReadinessCheck() {
+    if (readinessFn !== undefined) return readinessFn;
+    let file = null;
+    for (const name of ['readiness.ts', 'readiness.js', 'readiness.mts', 'readiness.mjs']) {
+      const p = join(appDir, name);
+      if (await exists(p)) { file = p; break; }
+    }
+    if (!file) { readinessFn = null; return null; }
+    try {
+      const url = pathToFileURL(file).toString();
+      const bust = dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
+      const mod = await import(url + bust);
+      readinessFn = typeof mod.default === 'function' ? mod.default : null;
+    } catch (e) {
+      logger.error?.(`[webjs] failed to load readiness.{js,ts}`, { err: String(e) });
+      readinessFn = null;
+    }
+    return readinessFn;
+  }
+
+  // Rebuilds are serialized so a slow rebuild #1 cannot overwrite a fresher
+  // rebuild #2's route table when it finally finishes. Without this, two file
+  // edits inside one fs.watch debounce window could produce a permanently
+  // stale state until the next rebuild.
   let rebuildInFlight = Promise.resolve();
-  let latestRebuildToken = 0;
 
   async function rebuild() {
-    const token = ++latestRebuildToken;
-    rebuildInFlight = rebuildInFlight.then(() => doRebuild(token)).catch((e) => {
+    rebuildInFlight = rebuildInFlight.then(() => doRebuild()).catch((e) => {
       logger.error?.(`[webjs] rebuild failed:`, e);
     });
     return rebuildInFlight;
   }
 
-  async function doRebuild(token) {
+  async function doRebuild() {
+    // The route table is the only eager artifact (cheap directory scan); rebuild
+    // it so routing reflects added/removed route files immediately.
     state.routeTable = await buildRouteTable(appDir);
-    state.actionIndex = await buildActionIndex(appDir, dev);
-    state.middleware = await loadMiddleware(appDir, dev, logger);
     clearVendorCache();
-    state.moduleGraph = await buildModuleGraph(appDir);
-    // Re-scan components in case a new file was added or a tag renamed.
-    // Share the scan with the browser-bound graph computation so we
-    // don't walk appDir twice per rebuild.
-    const components = await scanComponents(appDir);
-    await primeComponentRegistry(appDir, components);
-    // Recompute which components are elidable and which route modules are
-    // inert. A dependency's edit can flip a verdict WITHOUT changing an
-    // importer's mtime, so the TS transform cache (keyed by mtime) must be
-    // dropped or it would serve a stale strip decision for the unchanged
-    // importer.
-    {
-      const r = (await readElideEnabled(appDir))
-        ? await analyzeElision(
-            components,
-            collectRouteModules(state.routeTable),
-            state.moduleGraph,
-            (f) => readFile(f, 'utf8'),
-            appDir,
-          )
-        : { elidableComponents: new Set(), inertRouteModules: new Set() };
-      state.elidableComponents = r.elidableComponents;
-      state.inertRouteModules = r.inertRouteModules;
-    }
     TS_CACHE.clear();
-    // Re-scan bare imports AFTER elision so the importmap drops vendor
-    // deps reachable only through display-only components.
-    state.bareImports = await scanBareImports(appDir, new Set([...state.elidableComponents, ...state.inertRouteModules]));
-    const v = await resolveVendorImports(state.bareImports, appDir);
-    // Defensive: if a newer rebuild has been queued while we were
-    // awaiting resolveVendorImports, drop our result. The newer one
-    // will overwrite anyway, but checking the token here avoids a
-    // brief window of stale entries.
-    if (token === latestRebuildToken) {
-      await setVendorEntries(v.imports, v.integrity);
-    }
-    // Recompute the browser-bound file set: the page / layout / error /
-    // loading / not-found / component entries plus their transitive imports.
-    // This drives the dev server's "is this file allowed to be served as
-    // source?" gate at the file-extension catch-all branch below.
-    state.browserBoundFiles = computeBrowserBoundFiles(state.routeTable, state.moduleGraph, components, appDir);
-    if (dev) {
-      const orphans = await findOrphanComponents(appDir);
-      for (const { className, file } of orphans) {
-        logger.warn?.(
-          `[webjs] ${className} extends WebComponent but has no customElements.define(...) call in ${file}. ` +
-            `Add \`customElements.define('<tag-name>', ${className});\` or <${kebab(className)}> tags won't upgrade.`,
-        );
-      }
-    }
+    // Invalidate the lazy analysis; the next request rebuilds the graph,
+    // component scan, gate, action index, middleware, elision, and vendor map.
+    // Wait out any in-flight build first so it cannot commit stale results
+    // after the reset. A dependency edit can flip an elision verdict without
+    // changing an importer's mtime, hence the TS_CACHE.clear above.
+    if (readyInFlight) { try { await readyInFlight; } catch {} }
+    // Bump the vendor generation so a vendor resolve still in flight from the
+    // previous build cannot flip vendorResolved against the fresh state.
+    vendorGen++;
+    analysisDone = false;
+    vendorResolved = false;
+    vendorAttemptedOnce = false;
+    readyDone = false;
+    readyError = null;
+    readinessFn = undefined; // reload readiness.{js,ts} after a rebuild
     opts.onReload?.();
   }
 
   /** @param {Request} req */
   function handle(req) {
     return withRequest(req, async () => {
+      // Health and readiness probes are answered BEFORE ensureReady so a probe
+      // never blocks on the analysis. `/__webjs/health` is liveness (the
+      // process is up and accepting connections). `/__webjs/ready` is 503 until
+      // the instance is FULLY warm (the deterministic analysis AND the first
+      // vendor attempt have both completed, so the importmap build id is
+      // settled), then 200 unless an optional app readiness check
+      // (readiness.{js,ts}) reports a dependency down. So a readinessProbe holds
+      // traffic off a not-yet-warm or dependency-unhealthy instance, and admits
+      // it only once the build id is stable, never mid vendor-resolution.
+      // Probing `/__webjs/ready` also kicks off the warm in the background, so
+      // an embedder that never called warmup() still warms. The first vendor
+      // attempt is bounded (the jspm fetch timeout), so a vendor CDN failure
+      // delays readiness only briefly and then admits the instance (degraded but
+      // reload-safe); a transient failure is re-attempted on the next request.
+      let probePath;
+      try { probePath = new URL(req.url).pathname; } catch { probePath = ''; }
+      if (probePath === '/__webjs/health') {
+        return Response.json({ status: 'ok' }, { headers: { 'cache-control': 'no-store' } });
+      }
+      if (probePath === '/__webjs/ready') {
+        const noStore = { 'cache-control': 'no-store' };
+        if (!readyDone) {
+          ensureReady().catch(() => {}); // drive the warm; never block the probe
+          const body = readyError
+            ? { status: 'error', error: String((readyError && readyError.message) || readyError) }
+            : { status: 'pending' };
+          return Response.json(body, { status: 503, headers: noStore });
+        }
+        // Analysis is warm. Consult the optional app readiness check (live
+        // dependency health, e.g. a DB ping) if the app provides one.
+        const check = await getReadinessCheck();
+        if (check) {
+          try {
+            if ((await check()) === false) {
+              return Response.json({ status: 'unready' }, { status: 503, headers: noStore });
+            }
+          } catch (e) {
+            return Response.json(
+              { status: 'unready', error: String((e && e.message) || e) },
+              { status: 503, headers: noStore },
+            );
+          }
+        }
+        return Response.json({ status: 'ok' }, { headers: noStore });
+      }
+      // Build all whole-app analysis on the first request (memoized), before
+      // any SSR, module serve, gate check, action dispatch, or middleware runs.
+      await ensureReady();
       const next = () => handleCore(req, { state, appDir, coreDir, dev });
       if (state.middleware) {
         try {
@@ -389,6 +586,21 @@ export async function createRequestHandler(opts) {
     handle,
     rebuild,
     routeFor,
+    /**
+     * Proactively run the first-request analysis (module graph, component
+     * scan, gate, action index, middleware, elision, vendor map) in the
+     * background, so a real first request finds it already memoized. Safe to
+     * call any number of times and concurrently: the work is single-flighted,
+     * so this never duplicates it or races a real request. It is a single
+     * best-effort kick: errors are caught and logged rather than thrown (a
+     * background warm-up must not crash the process), and whatever failed simply
+     * re-runs on the next request or readiness probe (the platform's traffic and
+     * probes are the retry loop, so there is no internal backoff). `startServer`
+     * calls this once the HTTP server is listening; embedders can call it after
+     * their own listen.
+     * @returns {Promise<void>}
+     */
+    warmup: () => ensureReady().catch((e) => logger.error?.(`[webjs] background warm-up failed (will retry on the next request):`, e)),
     /** current route table getter: used by the WebSocket subsystem */
     getRouteTable: () => state.routeTable,
     appDir,
@@ -533,6 +745,11 @@ export async function startServer(opts) {
 
   server.listen(port, () => {
     logger.info(`webjs ${dev ? 'dev' : 'prod'} server ready on http://localhost:${port}`);
+    // The server is now accepting connections; warm the first-request analysis
+    // in the background so a real first request finds it memoized. Fire-and-
+    // forget: listening (and thus readiness probes / load-balancer health) does
+    // not wait on it, and a failure here does not bring the process down.
+    app.warmup();
   });
 
   const shutdown = gracefulShutdown(server, sseClients, logger);
@@ -571,10 +788,8 @@ async function handleCore(req, ctx) {
   try { path = decodeURIComponent(url.pathname); } catch { path = url.pathname; }
   const method = req.method.toUpperCase();
 
-  // Health / readiness probes for orchestrators (k8s, fly, etc.)
-  if (path === '/__webjs/health' || path === '/__webjs/ready') {
-    return Response.json({ status: 'ok' }, { headers: { 'cache-control': 'no-store' } });
-  }
+  // Health / readiness probes (`/__webjs/health`, `/__webjs/ready`) are handled
+  // in `handle()` BEFORE ensureReady, so they are not repeated here.
 
   // Dev live-reload client
   if (path === '/__webjs/reload.js') {
@@ -712,8 +927,9 @@ async function handleCore(req, ctx) {
       // Server-file guardrail: a file matching `.server.{js,ts,mjs,mts}`
       // MUST NEVER be served as source to the browser. The extension is
       // the path-level boundary; we re-verify it on every request (not
-      // just the action-index snapshot taken at boot) so files created
-      // after boot, FS races, or developer error never punch through.
+      // just rely on the action-index snapshot, which is built on the first
+      // request and refreshed on rebuild) so files created later, FS races,
+      // or developer error never punch through.
       //
       // What the browser gets depends on the file's `'use server'` status:
       //   - With `'use server'` => server action: a generated RPC stub
@@ -1224,8 +1440,8 @@ function debounce(fn, ms) {
  * module graph into the full transitive closure.
  *
  * This is webjs's equivalent of Next.js's bundler-produced page
- * manifest, applied at boot time (and on every rebuild) instead of
- * compile time. The dev server's source-file branch uses the returned
+ * manifest, derived lazily on the first request (and re-derived on every
+ * rebuild) instead of at compile time. The dev server's source-file branch uses the returned
  * Set as an authorization gate: in-set → served (subject to the
  * .server.{js,ts} stub guardrail); out-of-set → 404.
  *
@@ -1245,7 +1461,7 @@ function debounce(fn, ms) {
  *
  * Components are passed in (rather than rescanned) so the caller can
  * share one scan with `primeComponentRegistry`. Saves a full
- * appDir walk at boot and on every rebuild.
+ * appDir walk on each analysis (the first request and every rebuild).
  *
  * @param {Awaited<ReturnType<typeof buildRouteTable>>} routeTable
  * @param {Awaited<ReturnType<typeof buildModuleGraph>>} moduleGraph

package/src/importmap.js

@@ -17,7 +17,8 @@ function escapeAttr(s) {
  * scanner discovers npm packages used by client code. The resolution
  * happens via `vendor.js`'s `resolveVendorImports`, which reads the
  * committed `.webjs/vendor/importmap.json` if present, else calls
- * `api.jspm.io/generate` once at boot. Browser fetches vendor packages
+ * `api.jspm.io/generate` once on the first request (memoized), never at
+ * boot. Browser fetches vendor packages
  * directly from jspm.io's CDN (default) or from local `/__webjs/vendor/`
  * paths (after `webjs vendor pin --download`).
  */
@@ -36,8 +37,8 @@ let _vendorIntegrity = {};
 /**
  * Merge additional vendor entries into the import map and precompute
  * the importmap-hash so `importMapHash()` can stay synchronous on the
- * per-request SSR hot path. Called by the dev server at boot and on
- * every vendor rebuild.
+ * per-request SSR hot path. Called from `ensureReady()` on the first
+ * request and on every vendor rebuild.
  *
  * @param {Record<string, string>} entries
  * @param {Record<string, string>} [integrity]  SRI hashes keyed by URL
@@ -64,8 +65,8 @@ export async function setVendorEntries(entries, integrity) {
  * the change and hard-reload before applying the swap.
  *
  * Synchronous accessor. The hash is precomputed eagerly inside
- * `setVendorEntries` (which the dev server `await`s during boot and
- * on every rebuild) so the per-request SSR hot path can return the
+ * `setVendorEntries` (which `ensureReady()` `await`s on the first request
+ * and on every rebuild) so the per-request SSR hot path can return the
  * cached string without crossing a Promise boundary.
  *
  * Returns an empty string if `setVendorEntries` has never run; the
@@ -80,6 +81,46 @@ export function importMapHash() {
   return _importMapHash;
 }
 
+/**
+ * The published, client-facing build id: the value stamped into the
+ * `data-webjs-build` attribute and the `X-Webjs-Build` header that the
+ * client router compares across navigations to detect a real deploy.
+ *
+ * Distinct from `importMapHash()` (the live hash of the current map).
+ * The published id is advertised ONLY once the importmap is
+ * authoritatively final, so the warmup window never advertises a value
+ * that later changes. Runtime-first boot resolves an unpinned app's
+ * vendor map over the first request; while that is in flight the live
+ * hash mutates (empty, then partial, then complete), but the published
+ * id stays `''` until the map is final. The router treats an empty
+ * build id as "version unknown" and never hard-reloads against it, so a
+ * not-yet-final response is reload-safe by construction and cannot wipe
+ * a half-filled form.
+ *
+ * Promoted by `publishBuildId()`: at boot for a pinned app (the
+ * committed map is deterministic), or after the first successful vendor
+ * resolve for an unpinned app.
+ *
+ * @returns {string}  the advertised build id, or `''` until final
+ */
+let _publishedBuildId = '';
+export function publishedBuildId() {
+  return _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).
+ */
+export function publishBuildId() {
+  _publishedBuildId = _importMapHash;
+}
+
 /**
  * Look up the SRI integrity hash for a vendor URL, or empty string if
  * none. Used by ssr.js to add `integrity="..."` to modulepreload tags
@@ -228,8 +269,11 @@ export function buildCoreEntries(coreDir, distMode) {
     // The check is deliberately broad: `..` substring catches both
     // `../etc/passwd` and `./foo/../bar`.
     if (targetRel.includes('..')) continue;
-    // `./directives` → `@webjsdev/core/directives`,
-    // `./dist/webjs-core-directives.js` → `/__webjs/core/dist/webjs-core-directives.js`.
+    // `./lazy-loader` → `@webjsdev/core/lazy-loader`,
+    // `./dist/webjs-core-lazy-loader.js` → `/__webjs/core/dist/webjs-core-lazy-loader.js`.
+    // The browser-surface subpaths (`./directives`, `./context`, `./task`,
+    // `./client-router`) point their `default` at `webjs-core-browser.js`, so in
+    // dist mode they all collapse onto that one URL (the bundle re-exports them).
     out['@webjsdev/core' + subpath.slice(1)] = '/__webjs/core/' + targetRel.slice(2);
   }
   return out;
@@ -294,9 +338,12 @@ export function importMapTag(opts = {}) {
   // base64-ish. A misconfigured upstream emitting `nonce-<bad>` should
   // not get its `<` rendered raw into our HTML.
   const n = opts.nonce ? ` nonce="${escapeAttr(opts.nonce)}"` : '';
-  // Stamp the build hash so the client router can detect post-deploy
-  // importmap changes on intra-shell partial-response navigations.
-  // See importMapHash() above for the rationale.
-  const b = ` data-webjs-build="${importMapHash()}"`;
+  // Stamp the published build id so the client router can detect
+  // post-deploy importmap changes on intra-shell partial-response
+  // navigations. Uses publishedBuildId() (empty until the map is
+  // authoritatively final), NOT the live importMapHash(), so the warmup
+  // 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>`;
 }

package/src/module-graph.js

@@ -1,7 +1,7 @@
 /**
  * Lightweight module dependency graph.
  *
- * At startup, scans the app directory and builds an in-memory map of
+ * On the first request (lazily, via `ensureReady`), scans the app directory and builds an in-memory map of
  * `file → Set<imported files>`. The SSR pipeline queries this graph to
  * emit *complete* modulepreload hints: including transitive dependencies
  * of components: so the browser can fetch the entire tree in parallel
@@ -13,7 +13,7 @@
 
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join, resolve, dirname, extname } from 'node:path';
+import { join, resolve, dirname, extname, sep } from 'node:path';
 
 /** @type {RegExp} match static `import … from '…'` and `import '…'` */
 const IMPORT_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/g;
@@ -53,7 +53,18 @@ const EXPORT_FROM_RE = /\bexport\b[^'";]+?\sfrom\s+['"]([^'"]+)['"]/g;
 export async function buildModuleGraph(appDir) {
   /** @type {ModuleGraph} */
   const graph = new Map();
-  await walk(appDir, appDir, graph);
+  /** @type {Set<string>} every file walked this build (graph holds only files
+   * with deps, so a separate set is needed to know what is still live). */
+  const seen = new Set();
+  await walk(appDir, appDir, 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)
+  // keeps other apps' entries.
+  const prefix = appDir.endsWith(sep) ? appDir : appDir + sep;
+  for (const key of PARSE_CACHE.keys()) {
+    if ((key === appDir || key.startsWith(prefix)) && !seen.has(key)) PARSE_CACHE.delete(key);
+  }
   return graph;
 }
 
@@ -173,7 +184,7 @@ export function reachableFromEntries(graph, entryFiles, appDir) {
  * @param {string} appDir
  * @param {ModuleGraph} graph
  */
-async function walk(dir, appDir, graph) {
+async function walk(dir, appDir, graph, seen) {
   let entries;
   try { entries = await readdir(dir, { withFileTypes: true }); }
   catch { return; }
@@ -191,13 +202,28 @@ async function walk(dir, appDir, graph) {
     if (e.name.startsWith('.')) continue;
     const full = join(dir, e.name);
     if (e.isDirectory()) {
-      await walk(full, appDir, graph);
+      await walk(full, appDir, graph, seen);
     } else if (/\.(js|ts|mjs|mts)$/.test(e.name)) {
-      await parseFile(full, appDir, graph);
+      await parseFile(full, appDir, graph, seen);
     }
   }
 }
 
+/**
+ * mtime-keyed parse cache so a rebuild re-reads only files that actually
+ * changed. `buildModuleGraph` re-walks the (cheap) directory tree on every
+ * rebuild, but reading + regex-parsing each file is the cost; on an unchanged
+ * file the cached import set is reused after a single `stat`. This makes
+ * rebuilds incremental for large apps without restructuring the caller.
+ * Keyed by mtime AND size: a same-tick edit that also changes the file length
+ * is caught even on coarse-resolution filesystems where mtime alone could miss.
+ * @type {Map<string, { mtimeMs: number, size: number, deps: Set<string> }>}
+ */
+const PARSE_CACHE = new Map();
+
+/** Introspection for tests/ops: is `file` currently in the parse cache? */
+export function _parseCacheHas(file) { return PARSE_CACHE.has(file); }
+
 /**
  * Parse a single file's imports and add them to the graph.
  * Only resolves relative imports (bare specifiers are npm deps, not in the graph).
@@ -206,7 +232,17 @@ async function walk(dir, appDir, graph) {
  * @param {string} appDir
  * @param {ModuleGraph} graph
  */
-async function parseFile(file, appDir, graph) {
+async function parseFile(file, appDir, graph, seen) {
+  let mtimeMs, size;
+  try { const st = await stat(file); mtimeMs = st.mtimeMs; size = st.size; }
+  catch { return; }
+  seen?.add(file); // mark live (both cache-hit and miss paths) for cache eviction
+  const cached = PARSE_CACHE.get(file);
+  if (cached && cached.mtimeMs === mtimeMs && cached.size === size) {
+    if (cached.deps.size) graph.set(file, cached.deps);
+    return;
+  }
+
   let src;
   try { src = await readFile(file, 'utf8'); }
   catch { return; }
@@ -221,6 +257,7 @@ async function parseFile(file, appDir, graph) {
       if (resolved) deps.add(resolved);
     }
   }
+  PARSE_CACHE.set(file, { mtimeMs, size, deps });
   if (deps.size) graph.set(file, deps);
 }
 

package/src/ssr.js

@@ -1,7 +1,7 @@
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { renderToString, isNotFound, isRedirect, lookupModuleUrl, isLazy } from '@webjsdev/core';
-import { importMapTag, vendorIntegrityFor, importMapHash } from './importmap.js';
+import { importMapTag, vendorIntegrityFor, publishedBuildId } from './importmap.js';
 import { jsonForScriptTag } from './script-tag-json.js';
 import { readToken, newToken, cookieHeader } from './csrf.js';
 import { transitiveDeps } from './module-graph.js';
@@ -174,11 +174,13 @@ function htmlResponse(html, status, req, url, metadata) {
   // Default: no caching. Pages are dynamic by default: the developer
   // opts in to caching explicitly via metadata.cacheControl.
   headers.set('cache-control', metadata?.cacheControl || 'no-store');
-  // X-Webjs-Build carries the current importmap hash so the client
+  // X-Webjs-Build carries the published build id so the client
   // router can detect post-deploy importmap changes on EVERY
   // response, including the X-Webjs-Have partial responses that
-  // omit the head entirely. See router-client.js applySwap.
-  headers.set('x-webjs-build', importMapHash());
+  // omit the head entirely. Empty until the map is authoritatively
+  // final, so a warming response is reload-safe. See router-client.js
+  // applySwap and publishedBuildId() in importmap.js.
+  headers.set('x-webjs-build', publishedBuildId());
   if (req && !readToken(req)) {
     const secure = url ? url.protocol === 'https:' : false;
     headers.append('set-cookie', cookieHeader(newToken(), { secure }));
@@ -1189,9 +1191,9 @@ function streamingHtmlResponse(prefix, bodyHtml, closer, ctx, status, req, url,
   // Default: no caching. Pages are dynamic by default: the developer
   // opts in to caching explicitly via metadata.cacheControl.
   headers.set('cache-control', metadata?.cacheControl || 'no-store');
-  // See htmlResponse: build hash on every response for the client
-  // router's importmap-mismatch detection on partial swaps.
-  headers.set('x-webjs-build', importMapHash());
+  // 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());
   if (req && !readToken(req)) {
     const secure = url ? url.protocol === 'https:' : false;
     headers.append('set-cookie', cookieHeader(newToken(), { secure }));

package/src/vendor.js

@@ -25,11 +25,12 @@
  * returns metadata, not JavaScript. The correct entry file (e.g.,
  * `/dayjs.min.js`, `/index.js`) varies per package and must be
  * resolved from the JSPM Generator API. The Generator is called once
- * per server boot for the full set of bare imports; results are
+ * on the first request for the full set of bare imports; results are
  * cached in-memory for the process lifetime.
  *
- * Server boot connectivity: the Generator API call happens during
- * `setVendorEntries` at boot. If api.jspm.io is unreachable, the
+ * Connectivity: the Generator API call happens on the first request,
+ * inside `ensureReady` via `setVendorEntries`, never at boot. If
+ * api.jspm.io is unreachable, the
  * importmap will be missing vendor entries and the browser will
  * report "unresolved bare specifier" errors. The server itself still
  * boots and serves user routes; only vendor-importing pages break
@@ -269,6 +270,14 @@ export function getPackageVersion(pkgName, appDir) {
  */
 const jspmCache = new Map();
 
+// Set by jspmResolveOne whenever a LIVE resolution attempt fails (network
+// error, timeout, or a non-ok jspm response). resolveVendorImports resets it
+// before a scan and reads it after, so a caller can tell "resolved cleanly"
+// from "served a partial map because the CDN was unreachable" and avoid
+// memoizing the failure as done. Safe under the single-flighted ensureReady
+// (one live resolve at a time); the vendor CLI does not run alongside a server.
+let lastLiveResolveFailed = false;
+
 const JSPM_GENERATE_ENDPOINT = 'https://api.jspm.io/generate';
 const JSPM_GENERATE_TIMEOUT_MS = 10_000;
 
@@ -362,6 +371,13 @@ async function jspmResolveOne(install, provider = 'jspm') {
           `[webjs] could not vendor '${install}' via ${provider} (status ${response.status})${detail}`,
         );
         jspmCache.delete(cacheKey);
+        // A 5xx/429 is a transient jspm problem worth retrying. A 401/4xx means
+        // the install is genuinely unresolvable (jspm uses 401 for that): a
+        // private / workspace / server-only package (e.g. @webjsdev/server,
+        // @prisma/client) the browser never fetches anyway. That is tolerated
+        // exactly as before and must NOT block readiness, or an app with any
+        // such dep would never become ready.
+        if (response.status >= 500 || response.status === 429) lastLiveResolveFailed = true;
         return {};
       }
       const result = await response.json();
@@ -372,6 +388,7 @@ async function jspmResolveOne(install, provider = 'jspm') {
         : `${e && e.message}`;
       console.error(`[webjs] could not vendor '${install}' via ${provider}: ${msg}`);
       jspmCache.delete(cacheKey);
+      lastLiveResolveFailed = true;
       return {};
     } finally {
       clearTimeout(timer);
@@ -411,7 +428,8 @@ export async function jspmGenerate(installs, provider = 'jspm') {
  * api.jspm.io/generate for the full importmap fragment.
  *
  * Async because the Generator API call is networked. Called from
- * `setVendorEntries` during server boot and rebuild; not per request.
+ * `resolveVendorImports` on the first request (and after a rebuild),
+ * inside `ensureReady`; never at boot, and not on every request.
  *
  * @param {Set<string>} bareImports  from scanBareImports()
  * @param {string} appDir
@@ -462,6 +480,21 @@ function pinFilePath(appDir) {
   return join(pinDir(appDir), PIN_FILE);
 }
 
+/**
+ * True when the app commits a vendor pin file (`.webjs/vendor/importmap.json`).
+ * A pinned app's importmap is deterministic and cheap to read, so `dev.js`
+ * resolves it AT BOOT (no analysis, no network) and publishes the build id
+ * immediately, giving the recommended posture a stable id from the first
+ * response with zero warmup exposure. An unpinned app returns false and keeps
+ * its vendor resolution deferred to the first request.
+ *
+ * @param {string} appDir
+ * @returns {boolean}
+ */
+export function hasVendorPin(appDir) {
+  return existsSync(pinFilePath(appDir));
+}
+
 /**
  * Filesystem-safe filename for a downloaded bundle. Encodes the full
  * specifier (which may include a subpath) into a flat filename:
@@ -1257,8 +1290,8 @@ function maxSemverVersion(versions) {
 
 /**
  * Resolve the vendor importmap fragment for runtime use. Prefers the
- * committed pin file over a live api.jspm.io call. Called by dev.js
- * at server boot.
+ * committed pin file over a live api.jspm.io call. Called from
+ * `ensureReady()` in dev.js on the first request, never at boot.
  *
  * Order of preference:
  *   1. `.webjs/vendor/importmap.json` (committed; no network needed)
@@ -1270,17 +1303,29 @@ function maxSemverVersion(versions) {
  * hash, defeating the live-mode speed advantage. Users who want SRI
  * run `webjs vendor pin`).
  *
- * @param {Set<string>} bareImports
  * @param {string} appDir
+ * @param {() => Promise<Set<string>>} getBareImports lazy scan, invoked ONLY
+ *   on the unpinned path (so a pinned app never pays the whole-app walk).
  * @returns {Promise<{ imports: Record<string, string>, integrity: Record<string, string> }>}
  */
-export async function resolveVendorImports(bareImports, appDir) {
+export async function resolveVendorImports(appDir, getBareImports) {
   const file = await readPinFile(appDir);
+  // A committed pin file IS the import map. The whole-app bare-import scan is
+  // discarded in that case, so it must never run (runtime-first boot: no
+  // static analysis when pinned). The scan is supplied as a thunk and invoked
+  // solely here, only when there is no pin file.
   if (file) {
-    return { imports: file.imports, integrity: file.integrity || {} };
+    // A pin file is a deterministic disk read: always "ok" (no live CDN call
+    // that could partially fail). This is the recommended prod posture.
+    return { imports: file.imports, integrity: file.integrity || {}, ok: true };
   }
+  lastLiveResolveFailed = false;
+  const bareImports = await getBareImports();
   const imports = await vendorImportMapEntries(bareImports, appDir);
-  return { imports, integrity: {} };
+  // ok=false means at least one install could not be resolved (CDN unreachable
+  // / timeout / non-ok), so `imports` is partial. The caller must not memoize
+  // this as done; it should retry once the CDN recovers.
+  return { imports, integrity: {}, ok: !lastLiveResolveFailed };
 }
 
 /**