@webjsdev/server 0.7.3 → 0.8.0

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,21 +182,72 @@ 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);
-
-  // Scan for bare npm imports and register vendor import map entries.
-  const bareImports = await scanBareImports(appDir);
-  setVendorEntries(vendorImportMapEntries(bareImports));
+  // 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);
 
   // 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.
-  await primeComponentRegistry(appDir);
+  // 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
@@ -156,25 +265,81 @@ export async function createRequestHandler(opts) {
   }
 
   const state = {
-    routeTable: await buildRouteTable(appDir),
+    routeTable,
     actionIndex: await buildActionIndex(appDir, dev),
     middleware: await loadMiddleware(appDir, dev, logger),
     logger,
     bareImports,
     moduleGraph,
+    elidableComponents,
+    inertRouteModules,
+    browserBoundFiles: computeBrowserBoundFiles(routeTable, moduleGraph, components, appDir),
   };
 
+  // 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.
+  let rebuildInFlight = Promise.resolve();
+  let latestRebuildToken = 0;
+
   async function rebuild() {
+    const token = ++latestRebuildToken;
+    rebuildInFlight = rebuildInFlight.then(() => doRebuild(token)).catch((e) => {
+      logger.error?.(`[webjs] rebuild failed:`, e);
+    });
+    return rebuildInFlight;
+  }
+
+  async function doRebuild(token) {
     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);
+    // 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) {
@@ -267,16 +432,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.
@@ -354,7 +544,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());
+    }),
+  };
 }
 
 /**
@@ -408,12 +604,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 +665,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,7 +703,12 @@ 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
@@ -484,7 +726,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 +741,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 +799,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 +947,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 +1065,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 +1077,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 +1154,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 +1218,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, applied at boot time (and on every rebuild) instead of
+ * 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 at boot and on 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 +1331,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());