@webjsdev/server 0.7.3 → 0.8.1

package/src/dev.js

@@ -1,6 +1,7 @@
 import { createServer as createHttp1Server } from 'node:http';
-import { stat, readFile } from 'node:fs/promises';
-import { createHash } from 'node:crypto';
+import { stat, readFile, watch as fsWatch } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { digestHex } from './crypto-utils.js';
 import { createGzip, createBrotliCompress, constants as zlibConstants } from 'node:zlib';
 import { join, extname, resolve, dirname, relative, sep } from 'node:path';
 import { createRequire, stripTypeScriptTypes } from 'node:module';
@@ -19,7 +20,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 // equivalent built-in, we will need to install `amaro` directly (or
 // an equivalent: Sucrase preserves lines but not columns; SWC's
 // strip-only also works). The fast-path `stripTs` helper would
-// change one import line; the fallback path (esbuild) stays.
+// change one import line.
 //
 // Suppress the one-shot ExperimentalWarning that Node prints the
 // first time `stripTypeScriptTypes` is called. The API is committed
@@ -57,15 +58,16 @@ import {
 import { defaultLogger } from './logger.js';
 import { withRequest } from './context.js';
 import { attachWebSocket } from './websocket.js';
-import { scanBareImports, vendorImportMapEntries, serveVendorBundle, clearVendorCache } from './vendor.js';
-import { buildModuleGraph, transitiveDeps } from './module-graph.js';
-import { primeComponentRegistry, findOrphanComponents } from './component-scanner.js';
+import { scanBareImports, resolveVendorImports, serveDownloadedBundle, clearVendorCache } 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';
 
 /** PascalCase → kebab-case for a helpful diagnostic example tag name. */
 function kebab(name) {
   return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 }
-import { setVendorEntries } from './importmap.js';
+import { setVendorEntries, setCoreInstall } from './importmap.js';
 import { urlFromRequest } from './forwarded.js';
 
 const MIME = {
@@ -92,23 +94,79 @@ const MIME = {
  * Capped at 500 entries to prevent unbounded memory growth in
  * long-running production servers.
  *
- * Primary stripper: `module.stripTypeScriptTypes` (Node 24+ built-in).
+ * Stripper: `module.stripTypeScriptTypes` (Node 24+ built-in).
  * Position-preserving whitespace replacement. No sourcemap is
  * emitted because every (line, column) maps to itself in the source.
  *
- * Fallback stripper: `esbuild.transform`. Triggered only when the
- * primary path throws `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX` (the file
- * uses `enum`, `namespace`, parameter properties, or legacy
- * decorators). Emits an inline sourcemap so DevTools can still
- * resolve source positions for the regenerated JS. Mostly fires for
- * third-party `.ts` files; user code is enforced erasable by
- * `webjs check`.
+ * Only erasable TypeScript is supported. Non-erasable syntax (`enum`,
+ * `namespace` with values, parameter properties, legacy decorators
+ * with `emitDecoratorMetadata`, `import = require`) throws at strip
+ * time. The `erasable-typescript-only` and `no-non-erasable-typescript`
+ * lint rules catch these at edit time. webjs is buildless end-to-end:
+ * there is no bundler fallback.
  *
  * @type {Map<string, { mtimeMs: number, code: string, map: string | null }>}
  */
 const TS_CACHE_MAX = 500;
 const TS_CACHE = new Map();
 
+/**
+ * Auto-load `<appDir>/.env` into `process.env` once at boot. Mirrors
+ * what Rails / Next / Astro do out of the box: a scaffolded app with
+ * a committed `.env.example` and a developer-copied `.env` should
+ * "just work" without the user having to add a dotenv import or set
+ * the file path on the CLI.
+ *
+ * Uses Node 24+'s built-in `process.loadEnvFile`, which is dotenv-
+ * compatible and DOES NOT override pre-existing `process.env` values.
+ * Calls that hit a missing file or parse error are silenced; the
+ * server should still come up cleanly when there's no `.env`.
+ *
+ * Idempotent: re-running is a no-op for any env var the user already
+ * exported (e.g. via the host shell or a process manager). That
+ * keeps the "shell-set wins over file" precedence Rails users
+ * expect.
+ *
+ * Must run before any server-only module is loaded by
+ * buildActionIndex, since module-init code in `lib/*.server.ts`
+ * (e.g. `createAuth({ secret: process.env.AUTH_SECRET })`) reads
+ * process.env at import time. createRequestHandler is the
+ * single entry point where this is guaranteed.
+ *
+ * @param {string} appDir
+ */
+function loadAppEnv(appDir) {
+  try {
+    if (typeof process.loadEnvFile === 'function') {
+      process.loadEnvFile(join(appDir, '.env'));
+    }
+  } catch {
+    // No .env file, malformed file, or Node version without
+    // loadEnvFile. Either way, fall through silently: the user
+    // may not need any env vars, or they may set them via shell.
+  }
+}
+
+/**
+ * Read the project-level elision switch from `package.json`.
+ * `{ "webjs": { "elide": false } }` disables display-only and inert-route
+ * elision app-wide (everything ships, like before the feature existed).
+ * Any other value, or an absent key, leaves elision enabled (the default).
+ * Re-read on every rebuild so toggling the switch takes effect without a
+ * server restart.
+ * @param {string} appDir
+ * @returns {Promise<boolean>}
+ */
+async function readElideEnabled(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    if (pkg && pkg.webjs && pkg.webjs.elide === false) return false;
+  } catch {
+    // No package.json, malformed JSON, or unreadable. Keep the default.
+  }
+  return true;
+}
+
 /**
  * Create a reusable, framework-agnostic request handler for a webjs app.
  * The returned `handle(req)` takes a standard `Request` and resolves to a
@@ -124,72 +182,301 @@ const TS_CACHE = new Map();
  */
 export async function createRequestHandler(opts) {
   const appDir = resolve(opts.appDir);
+  // Load <appDir>/.env into process.env BEFORE anything else.
+  // buildActionIndex below imports server-only files (lib/*.server.ts,
+  // modules/**/*.server.ts), some of which read process.env at module
+  // init (e.g. createAuth reads AUTH_SECRET). Without this call,
+  // scaffolded apps with a committed .env.example + .env would fail
+  // to boot until the user discovered the missing env-load. See
+  // tracker #37.
+  loadAppEnv(appDir);
   const dev = !!opts.dev;
   const logger = opts.logger || defaultLogger({ dev });
   const coreDir = locateCoreDir(appDir);
+  // Switch the importmap between dist/ bundles and src/ per-file
+  // URLs depending on whether the resolved @webjsdev/core install
+  // has built bundles on disk. npm-installed copies always do;
+  // workspace dev does only after `npm run build:dist`. Without
+  // a built dist the server falls back to the historical per-file
+  // src/ URLs so dev iteration does not require a build step.
+  //
+  // Both required bundles must exist. An older @webjsdev/core
+  // install built BEFORE the browser-entry split (#119/#128) has
+  // `webjs-core.js` but no `webjs-core-browser.js`. Enabling dist
+  // mode in that case would route the bare `@webjsdev/core`
+  // specifier at a 404 on every page. Require both so a partial
+  // dist transparently degrades to src/ mode instead.
+  const distDir = join(coreDir, 'dist');
+  const distComplete =
+    existsSync(join(distDir, 'webjs-core.js')) &&
+    existsSync(join(distDir, 'webjs-core-browser.js'));
+  await setCoreInstall(coreDir, distComplete);
+
+  // 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);
 
-  // Scan for bare npm imports and register vendor import map entries.
-  const bareImports = await scanBareImports(appDir);
-  setVendorEntries(vendorImportMapEntries(bareImports));
+  const state = {
+    routeTable,
+    actionIndex: null,
+    middleware: null,
+    logger,
+    moduleGraph: null,
+    elidableComponents: new Set(),
+    inertRouteModules: new Set(),
+    browserBoundFiles: null,
+  };
 
-  // Build module dependency graph for transitive preload hints.
-  const moduleGraph = await buildModuleGraph(appDir);
+  // 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)
+  let vendorResolved = false;      // vendor map fully resolved (or permanently tolerated)
+  let vendorAttemptedOnce = false; // 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;
+    // Analysis warm but a prior vendor attempt failed: re-attempt WITHOUT
+    // blocking this request. The single-flight dedupes concurrent attempts;
+    // success flips the flag. This is the request/probe-driven retry (no timer).
+    if (analysisDone && vendorAttemptedOnce) {
+      const gen = vendorGen;
+      resolveAndApplyVendor().then((ok) => { if (ok && gen === vendorGen) vendorResolved = true; }).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;
+          }
+          // Readiness gates on the analysis only; vendor is best-effort below.
+          readyDone = 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.
+            if (ok && gen === vendorGen) vendorResolved = 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;
+  }
 
-  // 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.
-  await primeComponentRegistry(appDir);
+  // 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;
+  }
 
-  // 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.`,
-      );
+  // 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;
   }
 
-  const state = {
-    routeTable: await buildRouteTable(appDir),
-    actionIndex: await buildActionIndex(appDir, dev),
-    middleware: await loadMiddleware(appDir, dev, logger),
-    logger,
-    bareImports,
-    moduleGraph,
-  };
+  // 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();
 
   async function rebuild() {
+    rebuildInFlight = rebuildInFlight.then(() => doRebuild()).catch((e) => {
+      logger.error?.(`[webjs] rebuild failed:`, e);
+    });
+    return rebuildInFlight;
+  }
+
+  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);
-    // Re-scan bare imports and module graph on rebuild
     clearVendorCache();
-    state.bareImports = await scanBareImports(appDir);
-    setVendorEntries(vendorImportMapEntries(state.bareImports));
-    state.moduleGraph = await buildModuleGraph(appDir);
-    // Re-scan components in case a new file was added or a tag renamed.
-    await primeComponentRegistry(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.`,
-        );
-      }
-    }
+    TS_CACHE.clear();
+    // 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 analysis is warm, 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. Probing
+      // `/__webjs/ready` also kicks off the warm in the background, so an
+      // embedder that never called warmup() still warms. A vendor CDN failure
+      // does NOT block readiness (vendor is best-effort, retried 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 {
@@ -224,6 +511,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,
@@ -267,16 +569,41 @@ export async function startServer(opts) {
     },
   });
 
+  /** @type {AbortController | null} */
+  let watcherAbort = null;
   if (dev) {
-    const { watch } = await import('chokidar').catch(() => ({ watch: null }));
-    if (watch) {
-      const watcher = watch(app.appDir, {
-        ignored: [/node_modules/, /\.git/, /prisma\/(dev|migrations)/],
-        ignoreInitial: true,
-      });
-      const rebuild = debounce(() => app.rebuild(), 80);
-      watcher.on('all', rebuild);
-    }
+    // Watch the app root recursively via Node's built-in
+    // `fs.promises.watch`. Stable on macOS, Windows, and Linux as of
+    // Node 24. No external dep needed.
+    //
+    // fs.watch returns relative paths in event.filename. We apply
+    // the same ignore filter chokidar used before: skip
+    // node_modules, .git, and prisma's dev artefacts (dev.db,
+    // dev.db-journal, migrations/) which the dev server writes
+    // during db:migrate and would otherwise loop.
+    //
+    // The prisma branch uses prefix-only matching (no required
+    // trailing separator) so the SQLite sidecar files like
+    // `prisma/dev.db` and `prisma/dev.db-journal` are ignored too.
+    // node_modules / .git stay separator-anchored so unrelated
+    // names like `node_modules.bak/foo` don't get caught.
+    const IGNORE = /(?:^|[\\/])(?:node_modules|\.git)(?:[\\/]|$)|(?:^|[\\/])prisma[\\/](?:dev|migrations)/;
+    const rebuild = debounce(() => app.rebuild(), 80);
+    watcherAbort = new AbortController();
+    (async () => {
+      try {
+        const events = fsWatch(app.appDir, { recursive: true, signal: watcherAbort.signal });
+        for await (const event of events) {
+          const filename = event.filename || '';
+          if (IGNORE.test(filename)) continue;
+          rebuild();
+        }
+      } catch (err) {
+        if (err && /** @type any */(err).name !== 'AbortError') {
+          logger.warn({ err }, 'file watcher exited');
+        }
+      }
+    })();
   }
 
   // SSE keepalive: send a comment frame every 25s to defeat proxy idle timeouts.
@@ -343,6 +670,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);
@@ -354,7 +686,13 @@ export async function startServer(opts) {
   // corrupted, so log + start an orderly shutdown rather than continuing.
   installProcessHandlers(logger, () => shutdown('uncaughtException'));
 
-  return { server, close: () => new Promise((r) => server.close(() => r())) };
+  return {
+    server,
+    close: () => new Promise((r) => {
+      if (watcherAbort) watcherAbort.abort();
+      server.close(() => r());
+    }),
+  };
 }
 
 /**
@@ -375,10 +713,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') {
@@ -408,12 +744,31 @@ async function handleCore(req, ctx) {
     return fileResponse(abs, { dev, immutable: false });
   }
 
-  // Vendor bundles: /__webjs/vendor/<pkg>.js: generic auto-bundler
-  // (Vite-style optimizeDeps) for any bare npm import that webjs can't
-  // serve directly as ESM.
+  // Vendor URL handler for `webjs vendor pin --download` mode only.
+  // In default pin mode (or no-pin mode) the importmap routes bare
+  // imports straight to ga.jspm.io URLs and the browser bypasses this
+  // server entirely. When the user ran `webjs vendor pin --download`,
+  // the importmap has local `/__webjs/vendor/<file>.js` URLs and this
+  // handler serves the committed bundle files from `.webjs/vendor/`.
   if (path.startsWith('/__webjs/vendor/') && path.endsWith('.js')) {
-    const pkgName = decodeURIComponent(path.slice('/__webjs/vendor/'.length, -'.js'.length));
-    return serveVendorBundle(pkgName, appDir, dev);
+    // Vendor bundles are read-only static content. Allow GET/HEAD for
+    // the normal fetch, OPTIONS for any cross-origin preflight (we
+    // return 204 with the same Allow header rather than 405, which
+    // some intermediaries treat as a hard failure even for a CORS
+    // probe), and 405 everything else.
+    if (method === 'OPTIONS') {
+      return new Response(null, { status: 204, headers: { allow: 'GET, HEAD, OPTIONS' } });
+    }
+    if (method !== 'GET' && method !== 'HEAD') {
+      return new Response(null, { status: 405, headers: { allow: 'GET, HEAD, OPTIONS' } });
+    }
+    const filename = path.slice('/__webjs/vendor/'.length);
+    const resp = await serveDownloadedBundle(filename, appDir, dev);
+    if (method === 'HEAD') {
+      // HEAD must return same headers as GET with no body.
+      return new Response(null, { status: resp.status, headers: resp.headers });
+    }
+    return resp;
   }
 
   // Internal server-action RPC endpoint
@@ -450,10 +805,32 @@ async function handleCore(req, ctx) {
   if (path.startsWith('/public/') || path === '/favicon.ico') {
     const p = path === '/favicon.ico' ? '/public/favicon.ico' : path;
     const abs = join(appDir, p);
+    // Containment check. `join` normalises `..` segments, so a path
+    // like `/public/%2E%2E/secret/x.svg` decodes (after URL parsing,
+    // which doesn't touch `%2E`) to `/public/../secret/x.svg` and
+    // `join(appDir, ...)` resolves it to `appDir/secret/x.svg`. The
+    // resulting `abs` could be inside `appDir` but OUTSIDE `appDir/
+    // public/`, exposing files the user reasonably thought were
+    // private under their non-public directories. Reject anything
+    // that doesn't stay under `appDir/public/` (and the favicon
+    // exception, which is already validated above).
+    const publicRoot = join(appDir, 'public') + sep;
+    if (!abs.startsWith(publicRoot)) {
+      return new Response(null, { status: 404 });
+    }
     if (await exists(abs)) return fileResponse(abs, { dev, immutable: false });
   }
 
-  // User source modules (served as ES modules, with action-file rewriting)
+  // User source modules (served as ES modules, with action-file rewriting).
+  //
+  // Authorization gate: only files reachable from a browser-bound entry
+  // (page, layout, error, loading, not-found, component) via the module
+  // graph are servable. Same posture as Next.js, where the bundler's
+  // manifest is the source of truth for what the browser may fetch.
+  // Anything not in the set (node_modules/, top-level package.json,
+  // scripts/, etc.) 404s here regardless of whether the file exists on
+  // disk. The `.server.{js,ts}` stub guardrail runs below as a
+  // defense-in-depth layer.
   if (method === 'GET' && /\.(js|mjs|ts|mts|css|svg|png|jpg|jpeg|gif|webp|json|ico|txt)$/.test(path)) {
     let abs = join(appDir, path);
     // When the browser asks for `.js`, allow falling through to a sibling
@@ -466,12 +843,18 @@ async function handleCore(req, ctx) {
         if (await exists(mtsAbs)) abs = mtsAbs;
       }
     }
-    if (abs.startsWith(appDir) && (await exists(abs))) {
+    // Gate: must be in the browser-bound module graph. Server-action
+    // files (.server.{js,ts}) get a stub via the guardrail below; they
+    // ARE included in browserBoundFiles because client code imports
+    // them by path (the import rewrites to an RPC stub at request time).
+    const inGraph = state.browserBoundFiles && state.browserBoundFiles.has(abs);
+    if (abs.startsWith(appDir) && inGraph && (await exists(abs))) {
       // 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
@@ -484,7 +867,7 @@ async function handleCore(req, ctx) {
           // Lazily ensure the index knows about this file so serveActionStub
           // can mint a stable hash and function list.
           if (!state.actionIndex.fileToHash.has(abs)) {
-            const h = hashFile(abs);
+            const h = await hashFile(abs);
             state.actionIndex.fileToHash.set(abs, h);
             state.actionIndex.hashToFile.set(h, abs);
           }
@@ -499,9 +882,19 @@ async function handleCore(req, ctx) {
           headers: { 'content-type': 'application/javascript; charset=utf-8', 'cache-control': 'no-store' },
         });
       }
-      // TypeScript source: esbuild-strip types, cache by mtime.
+      // TypeScript source: strip types via Node 24+'s built-in, cache by mtime.
+      // Both module paths also strip side-effect imports of display-only
+      // components so the browser never downloads their JS.
+      const elideOpts = {
+        moduleGraph: state.moduleGraph,
+        elidableComponents: state.elidableComponents,
+        appDir,
+      };
       if (/\.m?ts$/.test(abs)) {
-        return tsResponse(abs, dev);
+        return tsResponse(abs, dev, elideOpts);
+      }
+      if (/\.m?js$/.test(abs)) {
+        return jsModuleResponse(abs, dev, elideOpts);
       }
       return fileResponse(abs, { dev, immutable: false });
     }
@@ -547,6 +940,8 @@ async function handleCore(req, ctx) {
       const handler = () => ssrPage(page.route, page.params, url, {
         dev, appDir, req, moduleGraph: state.moduleGraph,
         serverFiles: state.actionIndex.fileToHash,
+        elidableComponents: state.elidableComponents,
+        inertRouteModules: state.inertRouteModules,
       });
       return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
     }
@@ -693,12 +1088,23 @@ function toWebRequest(req, url) {
   /** @type {Record<string,string>} */
   const headers = {};
   for (const [k, v] of Object.entries(req.headers)) {
-    // Drop HTTP/2 pseudo-headers (`:method`, `:path`, `:scheme`, `:authority`) -
-    // they're parsed separately into req.method / req.url and are rejected
+    // Drop HTTP/2 pseudo-headers (`:method`, `:path`, `:scheme`, `:authority`).
+    // They're parsed separately into req.method / req.url and are rejected
     // by the standard Headers class if we pass them through verbatim.
     if (k.startsWith(':')) continue;
+    // Strip any inbound `x-webjs-remote-ip` header so clients cannot
+    // spoof the framework-stamped client IP that rate-limit's
+    // `clientIp(req, { trustProxy: false })` reads. We rewrite it
+    // below from the actual TCP socket. Node's IncomingMessage
+    // always lowercases header keys, so a literal compare is enough.
+    if (k === 'x-webjs-remote-ip') continue;
     headers[k] = Array.isArray(v) ? v.join(',') : String(v ?? '');
   }
+  // Stamp the framework-trusted remote IP from the socket. Read by
+  // `clientIp(req)` (rate-limit.js) as the bucket key when
+  // `trustProxy: false` (the safe default).
+  const remoteIp = req.socket?.remoteAddress;
+  if (remoteIp) headers['x-webjs-remote-ip'] = remoteIp;
   let body;
   if (method !== 'GET' && method !== 'HEAD') {
     body = new ReadableStream({
@@ -800,7 +1206,7 @@ async function fileResponse(abs, opts) {
     if (opts.dev) {
       headers['cache-control'] = 'no-cache';
     } else {
-      const etag = `"${createHash('sha1').update(data).digest('hex').slice(0, 16)}"`;
+      const etag = `"${(await digestHex('SHA-1', data)).slice(0, 16)}"`;
       headers['etag'] = etag;
       headers['cache-control'] = opts.immutable
         ? 'public, max-age=31536000, immutable'
@@ -812,54 +1218,72 @@ async function fileResponse(abs, opts) {
   }
 }
 
+/**
+ * Serve a plain `.js` / `.mjs` browser module, stripping side-effect
+ * imports of display-only components. Mirrors {@link fileResponse}'s
+ * headers but reads as text so the source can be transformed. Used only
+ * for files that exist as `.js` on disk (TS apps usually hit
+ * {@link tsResponse} via the .js to .ts sibling rewrite instead).
+ *
+ * @param {string} abs
+ * @param {boolean} dev
+ * @param {{ moduleGraph: any, elidableComponents: Set<string>|undefined, appDir: string }} elideOpts
+ */
+async function jsModuleResponse(abs, dev, elideOpts) {
+  let source;
+  try { source = await readFile(abs, 'utf8'); }
+  catch { return new Response('Not found', { status: 404 }); }
+  const code = elideImportsFromSource(
+    source, abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
+  );
+  const headers = { 'content-type': 'application/javascript; charset=utf-8' };
+  if (dev) {
+    headers['cache-control'] = 'no-cache';
+  } else {
+    headers['etag'] = `"${(await digestHex('SHA-1', code)).slice(0, 16)}"`;
+    headers['cache-control'] = 'public, max-age=3600';
+  }
+  return new Response(code, { status: 200, headers });
+}
+
 async function exists(p) {
   try { await stat(p); return true; } catch { return false; }
 }
 
 /**
- * Strip TypeScript types from `source`, using Node's built-in
- * `module.stripTypeScriptTypes` first (whitespace replacement,
- * position-preserving, no sourcemap needed) and falling back to
- * esbuild for files using non-erasable syntax (`enum`, `namespace`,
- * parameter properties, legacy decorators).
+ * Strip TypeScript types from `source` via Node's built-in
+ * `module.stripTypeScriptTypes`. Position-preserving whitespace
+ * replacement: no sourcemap is needed because every (line, column)
+ * maps to itself in the source.
  *
- * The framework's own code and the user's app code are kept on
- * erasable TS by the `erasable-typescript-only` convention check.
- * The fallback exists for third-party `.ts` files that the runtime
- * occasionally needs to serve.
+ * Only erasable TypeScript is supported. Non-erasable syntax
+ * (`enum`, `namespace` with values, parameter properties, legacy
+ * decorators with `emitDecoratorMetadata`, `import = require`)
+ * throws `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX` from Node and the
+ * dev server returns the error to the caller. The
+ * `erasable-typescript-only` and `no-non-erasable-typescript` lint
+ * rules catch these at edit time. There is no bundler fallback;
+ * webjs is buildless end-to-end.
  *
  * @param {string} source
- * @param {string} abs
+ * @param {string} _abs  (unused; preserved for symmetry with prior signature)
  * @returns {Promise<string>}
  */
-async function stripTs(source, abs) {
-  try {
-    return stripTypeScriptTypes(source);
-  } catch (err) {
-    if (err && err.code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX') {
-      const { transform: esbuild } = await loadEsbuild();
-      const r = await esbuild(source, {
-        loader: 'ts',
-        format: 'esm',
-        target: 'es2022',
-        sourcemap: 'inline',
-        sourcefile: abs,
-      });
-      return r.code;
-    }
-    throw err;
-  }
+async function stripTs(source, _abs) {
+  return stripTypeScriptTypes(source);
 }
 
 /**
  * Serve a `.ts` / `.mts` source file as JavaScript via {@link stripTs}.
  * Result is cached by mtime so subsequent requests are instant; a
- * file edit invalidates naturally.
+ * file edit invalidates naturally. `elideOpts` additionally strips
+ * side-effect imports of display-only components from the served code.
  *
  * @param {string} abs
  * @param {boolean} dev
+ * @param {{ moduleGraph: any, elidableComponents: Set<string>|undefined, appDir: string }} [elideOpts]
  */
-async function tsResponse(abs, dev) {
+async function tsResponse(abs, dev, elideOpts) {
   const st = await stat(abs);
   const cached = TS_CACHE.get(abs);
   if (cached && cached.mtimeMs === st.mtimeMs) {
@@ -871,7 +1295,48 @@ async function tsResponse(abs, dev) {
     });
   }
   const source = await readFile(abs, 'utf8');
-  const code = await stripTs(source, abs);
+  let code;
+  try {
+    code = await stripTs(source, abs);
+  } catch (err) {
+    // Node's stripTypeScriptTypes throws ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX
+    // for enum, namespace with values, parameter properties, legacy
+    // decorators with emitDecoratorMetadata, and import = require.
+    // Return a clean 500 with the file path and a pointer at the
+    // erasable-typescript-only lint rule rather than letting the
+    // error bubble up unstyled.
+    if (err && err.code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX') {
+      // Log full detail server-side regardless of mode so operators
+      // see what went wrong in their logs.
+      // eslint-disable-next-line no-console
+      console.error(`[webjs] non-erasable TypeScript in ${abs}: ${err.message}`);
+      const msg = dev
+        // Dev: include the file path and Node's error message so the
+        // developer's browser tooling can point them at the offending
+        // construct. Replace `*` + `/` with `*\\/` so a path or
+        // message containing the comment-close sequence cannot
+        // terminate the wrapper comment early.
+        ? `[webjs] non-erasable TypeScript in ${abs}: ${err.message}\n\n` +
+          `webjs is buildless: only erasable TS syntax is supported. ` +
+          `Replace enum / namespace / parameter-property / legacy-decorator / ` +
+          `import = require constructs with their erasable equivalents. ` +
+          `Run \`webjs check\` for guidance (no-non-erasable-typescript rule).`
+        // Prod: terse, no path leak, no Node-message leak (Node's
+        // message can include source snippets). Operators get the
+        // detail in server logs above.
+        : `[webjs] server error transforming a .ts response. Check server logs.`;
+      return new Response(`/* ${msg.replace(/\*\//g, '*\\/')} */`, {
+        status: 500,
+        headers: { 'content-type': 'application/javascript; charset=utf-8' },
+      });
+    }
+    throw err;
+  }
+  if (elideOpts) {
+    code = elideImportsFromSource(
+      code, abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
+    );
+  }
   // Evict oldest entry if cache is full (simple FIFO: Map preserves insertion order).
   if (TS_CACHE.size >= TS_CACHE_MAX) {
     const oldest = TS_CACHE.keys().next().value;
@@ -894,6 +1359,81 @@ function debounce(fn, ms) {
   };
 }
 
+/**
+ * Walk the route table + component scanner to collect every file the
+ * browser may legitimately fetch as an ES module, then expand via the
+ * module graph into the full transitive closure.
+ *
+ * This is webjs's equivalent of Next.js's bundler-produced page
+ * 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.
+ *
+ * Browser-bound entries:
+ *   - page.{js,ts,mjs,mts}        (re-runs on client for hydration)
+ *   - layout.{js,ts,mjs,mts}      (same)
+ *   - error.{js,ts,mjs,mts}       (same)
+ *   - loading.{js,ts,mjs,mts}     (same)
+ *   - not-found.{js,ts,mjs,mts}   (same)
+ *   - component files discovered by the scanner (eager + lazy)
+ *
+ * Server-only entries (NOT in the set):
+ *   - route.{js,ts}   (API handlers, never fetched as JS module)
+ *   - middleware.{js,ts}
+ *   - metadata routes (sitemap.js, robots.js, manifest.js, …)
+ *   - .server.{js,ts} files (browser gets a stub, not the source)
+ *
+ * Components are passed in (rather than rescanned) so the caller can
+ * share one scan with `primeComponentRegistry`. Saves a full
+ * appDir walk on each analysis (the first request and every rebuild).
+ *
+ * @param {Awaited<ReturnType<typeof buildRouteTable>>} routeTable
+ * @param {Awaited<ReturnType<typeof buildModuleGraph>>} moduleGraph
+ * @param {Awaited<ReturnType<typeof scanComponents>>} components
+ * @param {string} appDir
+ * @returns {Set<string>}
+ */
+/**
+ * Collect every page + layout file across the route table. These are the
+ * modules the client boot script imports, and thus the candidates for
+ * inert-route elision (dropping a module that does no client work).
+ * `route.{js,ts}` / middleware / metadata are excluded: they never ship.
+ *
+ * @param {Awaited<ReturnType<typeof buildRouteTable>>} routeTable
+ * @returns {string[]}
+ */
+function collectRouteModules(routeTable) {
+  /** @type {Set<string>} */
+  const mods = new Set();
+  for (const page of routeTable.pages || []) {
+    if (page.file) mods.add(page.file);
+    for (const f of page.layouts || []) mods.add(f);
+  }
+  return [...mods];
+}
+
+function computeBrowserBoundFiles(routeTable, moduleGraph, components, appDir) {
+  /** @type {Set<string>} */
+  const entries = new Set();
+  for (const page of routeTable.pages) {
+    if (page.file) entries.add(page.file);
+    for (const f of page.layouts || []) entries.add(f);
+    for (const f of page.errors || []) entries.add(f);
+    for (const f of page.loadings || []) entries.add(f);
+  }
+  if (routeTable.notFound) entries.add(routeTable.notFound);
+  if (routeTable.notFounds) {
+    for (const f of routeTable.notFounds.values()) entries.add(f);
+  }
+  // Lazy components live in the registry but no page imports their
+  // class directly; the lazy-loader fetches their module URLs on
+  // viewport entry. Add every discovered component file as an entry so
+  // the graph walk covers both eager and lazy paths.
+  for (const c of components) entries.add(c.file);
+  return reachableFromEntries(moduleGraph, [...entries], appDir);
+}
+
 /**
  * Find the absolute directory of the `@webjsdev/core` package, regardless of
  * whether we're running from the monorepo or an installed copy.
@@ -932,20 +1472,6 @@ function locatePackageDir(appDir, pkgName) {
   return null;
 }
 
-/**
- * Load esbuild. Resolved as a real dependency of `@webjsdev/server`,
- * so the bare specifier always resolves regardless of where the cli is
- * installed (global, local, workspace-linked).
- *
- * @returns {Promise<typeof import('esbuild')>}
- */
-let _esbuild = null;
-async function loadEsbuild() {
-  if (_esbuild) return _esbuild;
-  _esbuild = await import('esbuild');
-  return _esbuild;
-}
-
 const RELOAD_CLIENT_JS = `// webjs dev reload client
 const es = new EventSource('/__webjs/events');
 es.addEventListener('reload', () => location.reload());