@webjsdev/server 0.8.39 → 0.8.41

package/src/module-graph.js

@@ -101,10 +101,87 @@ const IMPORT_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/g;
  */
 const EXPORT_FROM_RE = /\bexport\b[^'";]+?\sfrom\s+['"]([^'"]+)['"]/g;
 
+/**
+ * @type {RegExp} match a dynamic `import('…')` with a STRING-LITERAL specifier
+ * only (`import('./x.ts')`, `await import("#lib/y.ts")`). A computed specifier
+ * (`import(expr)`) cannot be captured and is intentionally left out: it stays a
+ * documented limitation (and `webjs check` warns on it), not a phantom edge.
+ *
+ * Unlike the static `IMPORT_RE` (which requires `\s+` after `import`), this
+ * matches `import` immediately or with whitespace before the `(`, so the two
+ * never overlap. `m.index` is the `import` keyword start, so the same
+ * redaction-mask guard (keyword-in-code-position) applies.
+ *
+ * The specifier may be followed by `)` OR `,` so the import-attributes form
+ * `import('./data.json', { with: { type: 'json' } })` (a JSON / CSS module
+ * import) is captured too. A computed specifier still falls out: in
+ * `import('./pages/' + name)` the char after the closing quote is `+`, neither
+ * `,` nor `)`, so it does not match.
+ */
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*[,)]/g;
+
 /**
  * @typedef {Map<string, Set<string>>} ModuleGraph
- * A map of absolute file path → Set of absolute file paths it imports.
+ * A map of absolute file path → Set of absolute file paths it STATICALLY imports.
+ */
+
+/**
+ * Dynamic-import edges (string-literal `import('…')` only), kept SEPARATE from
+ * the static graph and keyed by it in a WeakMap. The authorization gate
+ * (`reachableFromEntries`) unions these in so a lazily-imported app module is
+ * servable instead of 404ing, but the preload walk (`transitiveDeps`) and the
+ * elision analysis stay on the static graph ONLY: a dynamic import is lazy by
+ * author intent, so eagerly preloading its target would over-fetch on every
+ * page load, and feeding dynamic edges into elision could flip a verdict. The
+ * module is fetched at call time, now served correctly by the gate.
+ * @type {WeakMap<ModuleGraph, ModuleGraph>}
+ */
+const DYNAMIC_EDGES = new WeakMap();
+
+/**
+ * The dynamic-import edges discovered for a built graph (string-literal targets
+ * only), or an empty map if none. Exposed for tests/ops.
+ * @param {ModuleGraph} graph
+ * @returns {ModuleGraph}
+ */
+export function dynamicEdges(graph) {
+  return DYNAMIC_EDGES.get(graph) || new Map();
+}
+
+/**
+ * Bare (npm vendor) import specifiers per file, kept SEPARATE from the static
+ * app graph (which only tracks relative + `#`-alias edges) and keyed by the
+ * graph in a WeakMap. Records the EXACT specifier as written (`dayjs`,
+ * `dayjs/plugin/utc`) so SSR can look it up in the vendor importmap and emit a
+ * `modulepreload` for the reached vendor URL (#754), flattening the vendor CDN
+ * waterfall. Excludes `node:` builtins and protocol specifiers.
+ * @type {WeakMap<ModuleGraph, Map<string, Set<string>>>}
+ */
+const BARE_EDGES = new WeakMap();
+
+/**
+ * The bare (npm vendor) import specifiers per file for a built graph, or an
+ * empty map if none. The values are specifiers (not resolved URLs); the caller
+ * maps them through the vendor importmap.
+ * @param {ModuleGraph} graph
+ * @returns {Map<string, Set<string>>}
  */
+export function bareImports(graph) {
+  return BARE_EDGES.get(graph) || new Map();
+}
+
+/**
+ * True for a bare npm vendor specifier (`dayjs`, `@scope/pkg/sub`), excluding
+ * relative / absolute / `#`-alias paths and `node:` / protocol specifiers.
+ * Inlined here (not imported from vendor.js) to avoid a module cycle.
+ * @param {string} spec
+ * @returns {boolean}
+ */
+function isVendorSpecifier(spec) {
+  if (!spec || spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('#') || spec.startsWith('__')) return false;
+  if (spec.startsWith('node:') || /^[a-z][a-z0-9+.-]*:/.test(spec)) return false;
+  return true;
+}
 
 /**
  * Build the module graph for all source files under `appDir`.
@@ -118,10 +195,16 @@ export async function buildModuleGraph(appDir) {
   IMPORTS_CACHE.delete(appDir);
   /** @type {ModuleGraph} */
   const graph = new Map();
+  /** @type {ModuleGraph} dynamic-import edges, keyed to `graph` below */
+  const dynamic = new Map();
+  /** @type {Map<string, Set<string>>} bare vendor specifiers per file (#754) */
+  const bare = new Map();
   /** @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);
+  await walk(appDir, appDir, graph, seen, dynamic, bare);
+  if (dynamic.size) DYNAMIC_EDGES.set(graph, dynamic);
+  if (bare.size) BARE_EDGES.set(graph, bare);
   // 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)
@@ -226,6 +309,13 @@ const SERVER_FILE_RE = /\.server\.m?[jt]s$/;
  * @returns {Set<string>}
  */
 export function reachableFromEntries(graph, entryFiles, appDir) {
+  // The gate unions in dynamic-import edges (#751) so a lazily-imported app
+  // module (`await import('./widget.ts')`) is servable instead of 404ing. A
+  // dynamically-imported module's OWN static imports are then walked normally
+  // (it joins the queue), so its subtree is servable too. The `.server.*`
+  // boundary still holds: a dynamic `import('./x.server.ts')` is admitted (a
+  // stub is served) but, like any server file, not traversed into.
+  const dynamic = DYNAMIC_EDGES.get(graph);
   /** @type {Set<string>} */
   const visited = new Set();
   /** @type {string[]} */
@@ -242,13 +332,17 @@ export function reachableFromEntries(graph, entryFiles, appDir) {
     // time), but we don't add its imports because the browser never
     // sees them.
     if (SERVER_FILE_RE.test(file)) continue;
-    const deps = graph.get(file);
-    if (!deps) continue;
-    for (const dep of deps) {
-      if (visited.has(dep)) continue;
-      if (!dep.startsWith(appDir)) continue;
-      visited.add(dep);
-      queue.push(dep);
+    const staticDeps = graph.get(file);
+    const dynDeps = dynamic && dynamic.get(file);
+    if (!staticDeps && !dynDeps) continue;
+    for (const set of [staticDeps, dynDeps]) {
+      if (!set) continue;
+      for (const dep of set) {
+        if (visited.has(dep)) continue;
+        if (!dep.startsWith(appDir)) continue;
+        visited.add(dep);
+        queue.push(dep);
+      }
     }
   }
   return visited;
@@ -260,7 +354,7 @@ export function reachableFromEntries(graph, entryFiles, appDir) {
  * @param {string} appDir
  * @param {ModuleGraph} graph
  */
-async function walk(dir, appDir, graph, seen) {
+async function walk(dir, appDir, graph, seen, dynamic, bare) {
   let entries;
   try { entries = await readdir(dir, { withFileTypes: true }); }
   catch { return; }
@@ -278,9 +372,9 @@ async function walk(dir, appDir, graph, seen) {
     if (e.name.startsWith('.')) continue;
     const full = join(dir, e.name);
     if (e.isDirectory()) {
-      await walk(full, appDir, graph, seen);
+      await walk(full, appDir, graph, seen, dynamic, bare);
     } else if (/\.(js|ts|mjs|mts)$/.test(e.name)) {
-      await parseFile(full, appDir, graph, seen);
+      await parseFile(full, appDir, graph, seen, dynamic, bare);
     }
   }
 }
@@ -308,7 +402,7 @@ export function _parseCacheHas(file) { return PARSE_CACHE.has(file); }
  * @param {string} appDir
  * @param {ModuleGraph} graph
  */
-async function parseFile(file, appDir, graph, seen) {
+async function parseFile(file, appDir, graph, seen, dynamic, bare) {
   let mtimeMs, size;
   try { const st = await stat(file); mtimeMs = st.mtimeMs; size = st.size; }
   catch { return; }
@@ -316,6 +410,8 @@ async function parseFile(file, appDir, graph, seen) {
   const cached = PARSE_CACHE.get(file);
   if (cached && cached.mtimeMs === mtimeMs && cached.size === size) {
     if (cached.deps.size) graph.set(file, cached.deps);
+    if (cached.dynDeps && cached.dynDeps.size && dynamic) dynamic.set(file, cached.dynDeps);
+    if (cached.bareDeps && cached.bareDeps.size && bare) bare.set(file, cached.bareDeps);
     return;
   }
 
@@ -343,24 +439,72 @@ async function parseFile(file, appDir, graph, seen) {
   // code-example `import` string never becomes an edge.
   const masked = redactStringsAndTemplates(src, true);
   const deps = new Set();
+  /** @type {Set<string>} bare npm vendor specifiers imported by this file (#754) */
+  const bareDeps = new Set();
   for (const re of [IMPORT_RE, EXPORT_FROM_RE]) {
     for (const m of src.matchAll(re)) {
       // m.index is the keyword start (`\bimport` / `\bexport`). If that
       // position is blanked in the mask, the match lives inside a literal
       // and is not a real import edge.
       if (masked[m.index] === ' ') continue;
+      // A statement-leading `import type { X }` / `import type * as X` /
+      // `import type Foo` (default type import) / `export type { X }` /
+      // `export type *` is fully erased by the TS stripper, so it never becomes
+      // a browser fetch or a runtime edge. Skip it, so a type-only import of a
+      // `.server.ts` (a common, correct way to share a derived row type) is not
+      // mistaken for a runtime dependency by the gate / elision / the
+      // no-server-import check. Two carve-outs keep this from over-dropping:
+      //   - `import type from '...'` is a VALUE default import whose binding is
+      //     literally named `type` (the stripper keeps it), so `type` directly
+      //     followed by `from` is NOT type-only.
+      //   - a MIXED `import { type A, b }` does NOT lead with `type`, so it is
+      //     kept (its `b` binding is a real runtime edge).
+      // #805
+      const lead = m[0];
+      const typeOnly =
+        /^(?:import|export)\s+type\s*[{*]/.test(lead) ||
+        (/^import\s+type\s+[A-Za-z_$]/.test(lead) && !/^import\s+type\s+from\b/.test(lead));
+      if (typeOnly) continue;
       const spec = m[1];
+      // Guard a match whose `from '<spec>'` tail reaches INTO a blanked literal:
+      // EXPORT_FROM_RE's lazy `[^'";]+?` can span a template body to a `from`
+      // written inside example code (`export const t = html\`...import x from
+      // 'left-pad'\``), so the KEYWORD is real but the SPECIFIER is not. A real
+      // string keeps its delimiters in the mask (only the body blanks), while a
+      // template body blanks whole, so a blanked opening quote means the
+      // specifier is inside a literal and the match is spurious.
+      const quoteAt = m.index + m[0].length - spec.length - 2;
+      if (masked[quoteAt] === ' ') continue;
       // Only resolve relative imports + `#`-style subpath aliases (#555)
       // within the project. A bare npm specifier (dayjs) has no alias match
-      // and is skipped; an aliased `#lib/x.server.ts` IS followed so the
-      // graph / auth gate / elision see the real path through the alias.
-      if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) continue;
+      // and is skipped FROM THE GRAPH, but recorded as a vendor edge so SSR
+      // can emit a modulepreload for the reached vendor URL (#754); an aliased
+      // `#lib/x.server.ts` IS followed so the graph / auth gate / elision see
+      // the real path through the alias.
+      if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) {
+        if (isVendorSpecifier(spec)) bareDeps.add(spec);
+        continue;
+      }
       const resolved = resolveImport(spec, file, appDir);
       if (resolved) deps.add(resolved);
     }
   }
-  PARSE_CACHE.set(file, { mtimeMs, size, deps });
+  // Dynamic `import('…')` with a string-literal specifier (#751): a separate
+  // edge class so the gate admits the lazily-loaded module (no 404) without
+  // preloading it. Same redaction-mask + alias rules as the static scan. A
+  // target already statically imported is not duplicated as a dynamic edge.
+  const dynDeps = new Set();
+  for (const m of src.matchAll(DYNAMIC_IMPORT_RE)) {
+    if (masked[m.index] === ' ') continue;
+    const spec = m[1];
+    if (!spec.startsWith('.') && !spec.startsWith('/') && !expandImportAlias(spec, appDir)) continue;
+    const resolved = resolveImport(spec, file, appDir);
+    if (resolved && !deps.has(resolved)) dynDeps.add(resolved);
+  }
+  PARSE_CACHE.set(file, { mtimeMs, size, deps, dynDeps, bareDeps });
   if (deps.size) graph.set(file, deps);
+  if (dynDeps.size && dynamic) dynamic.set(file, dynDeps);
+  if (bareDeps.size && bare) bare.set(file, bareDeps);
 }
 
 /**

package/src/page-action.js

@@ -2,6 +2,7 @@ import { isNotFound, isRedirect } from '@webjsdev/core';
 import { ssrPage, ssrNotFound, loadModule } from './ssr.js';
 import { readBytesBounded, payloadTooLarge, DEFAULT_MAX_MULTIPART_BYTES } from './body-limit.js';
 import { getBodyLimits } from './context.js';
+import { propagateTrustedRemoteIp } from './rate-limit.js';
 
 /**
  * Page server actions: a `page.{js,ts}` may export an `action` function that
@@ -133,12 +134,20 @@ async function parseFormBody(req) {
   if (tooLarge) return { tooLarge: true, formData: new FormData(), request: req };
 
   // Rebuild a fresh Request from the bytes so the action can re-read the body.
+  // SECURITY (#756): strip any inbound `x-webjs-remote-ip` the copy carried so a
+  // client cannot spoof it through the rebuild, and carry the FRAMEWORK-trusted
+  // remote IP forward out of band (the rebuild is a new object, so the listener's
+  // WeakMap stamp on `req` does not follow it). Without this, `clientIp` inside a
+  // page `action` (the no-JS form write path, e.g. login throttling) would read
+  // the spoofable header on Bun.
   const headers = new Headers(req.headers);
+  headers.delete('x-webjs-remote-ip');
   const rebuilt = new Request(req.url, {
     method: req.method,
     headers,
     body: bytes && bytes.byteLength ? bytes : undefined,
   });
+  propagateTrustedRemoteIp(req, rebuilt);
 
   const isForm = /multipart\/form-data|application\/x-www-form-urlencoded/i.test(ct);
   let formData = new FormData();

package/src/rate-limit.js

@@ -89,13 +89,68 @@ export function rateLimit(opts = {}) {
  */
 const REMOTE_IP_HEADER = 'x-webjs-remote-ip';
 
+/**
+ * Out-of-band trusted remote IP (#756). A listener shell that already holds the
+ * socket IP can stamp it here instead of reallocating a whole `Request` just to
+ * set the `x-webjs-remote-ip` header (the Bun hot path). When an entry exists
+ * for a request it is AUTHORITATIVE: `trustedRemoteIp` returns it and ignores
+ * the inbound header entirely, so a client-spoofed `x-webjs-remote-ip` is never
+ * trusted even though the original (unmodified) request still carries it.
+ * @type {WeakMap<Request, string>}
+ */
+const trustedIpMap = new WeakMap();
+
+/**
+ * Stamp the trusted remote IP for a request out-of-band (no Request clone).
+ * Pass `''` (or a falsy value) to mark the request as listener-stamped with no
+ * known IP, which still makes the inbound header untrusted (resolves to the
+ * anon fallback rather than a spoofable header value).
+ * @param {Request} req
+ * @param {string | null | undefined} ip
+ */
+export function setTrustedRemoteIp(req, ip) {
+  trustedIpMap.set(req, ip || '');
+}
+
+/**
+ * The framework-trusted remote IP for a request: the out-of-band WeakMap value
+ * when a listener stamped it (authoritative, header ignored), else the
+ * framework-stamped `x-webjs-remote-ip` header (the node / embedded path).
+ * @param {Request} req
+ * @returns {string}
+ */
+function trustedRemoteIp(req) {
+  if (trustedIpMap.has(req)) return trustedIpMap.get(req) || '';
+  return req.headers.get(REMOTE_IP_HEADER) || '';
+}
+
+/**
+ * Carry the trusted remote IP from `src` to a freshly-rebuilt `dst` Request
+ * (#756). When the framework re-wraps a request (the page-action body rebuild in
+ * `page-action.js`), the out-of-band WeakMap key is a new object, so the trusted
+ * IP would be lost and `clientIp(dst)` would fall back to the (spoofable) header
+ * the rebuild copied over. Propagating the trusted value via the WeakMap keeps
+ * `dst` authoritative on BOTH runtimes (it reads `trustedRemoteIp(src)`, which is
+ * the WeakMap value on Bun and the framework-stamped header on Node). The caller
+ * must ALSO strip the inbound `x-webjs-remote-ip` header from `dst` so a client
+ * copy can never win. Idempotent and safe to call on any rebuild.
+ * @param {Request} src
+ * @param {Request} dst
+ */
+export function propagateTrustedRemoteIp(src, dst) {
+  setTrustedRemoteIp(dst, trustedRemoteIp(src));
+}
+
 /**
  * Resolve the client IP for rate-limit bucket keying.
  *
  * `trustProxy: false` (default, safe everywhere): read ONLY the
- * framework-stamped `x-webjs-remote-ip` header. Under `startServer`
- * the framework derives it from the actual TCP socket and strips
- * any inbound copy via `toWebRequest`, so clients cannot spoof it.
+ * framework-trusted remote IP. Under `startServer` the framework derives it from
+ * the actual TCP socket: the node shell stamps the `x-webjs-remote-ip` header
+ * (stripping any inbound copy via `toWebRequest`), and the Bun shell stamps it
+ * OUT OF BAND via `setTrustedRemoteIp` (a WeakMap, no per-request Request clone,
+ * #756) which `trustedRemoteIp` reads in preference to (and to the exclusion of)
+ * the header, so a client cannot spoof it either way.
  * Under `createRequestHandler` (embedded use) the host adapter MUST
  * call `stampRemoteIp(req, remoteAddress)` first, otherwise the
  * adapter may pass forged inbound headers straight through and the
@@ -122,11 +177,11 @@ export function clientIp(req, opts = {}) {
       req.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
       req.headers.get('cf-connecting-ip') ||
       req.headers.get('x-real-ip') ||
-      req.headers.get(REMOTE_IP_HEADER) ||
+      trustedRemoteIp(req) ||
       '_anon_'
     );
   }
-  return req.headers.get(REMOTE_IP_HEADER) || '_anon_';
+  return trustedRemoteIp(req) || '_anon_';
 }
 
 /**

package/src/router.js

@@ -158,7 +158,7 @@ export async function buildRouteTable(appDir) {
     a.middlewares = chainDirs.map((d) => middlewares.get(d)).filter(Boolean);
   }
 
-  pages.sort((a, b) => dynScore(a) - dynScore(b));
+  pages.sort(compareSpecificity);
   return { pages, apis, notFound, notFounds, metadataRoutes, appDir };
 }
 
@@ -191,11 +191,68 @@ function isUrlSegment(seg) {
   return true;
 }
 
-/** @param {PageRoute} r */
-function dynScore(r) {
-  if (r.isCatchAll) return 3;
-  if (r.paramNames.length) return 2;
-  return 1;
+/**
+ * Per-URL-segment specificity kind: 0 = static literal, 1 = dynamic `[x]`,
+ * 2 = catch-all `[...x]` / `[[...x]]`. Lower is MORE specific. Checks the
+ * catch-all forms before the bare `[` (a `[[...x]]` also starts with `[`).
+ * @param {string} seg
+ * @returns {0 | 1 | 2}
+ */
+function segKind(seg) {
+  if (seg.startsWith('[[...') || seg.startsWith('[...')) return 2;
+  if (seg.startsWith('[') && seg.endsWith(']')) return 1;
+  return 0;
+}
+
+/**
+ * The ordered URL segments of a route (route groups + private folders removed),
+ * which is the basis for positional specificity.
+ * @param {string} routeDir
+ * @returns {string[]}
+ */
+function urlSegmentsOf(routeDir) {
+  return (routeDir === '.' ? [] : routeDir.split('/')).filter(isUrlSegment);
+}
+
+/**
+ * Deterministic route specificity ordering (#750). Replaces the old coarse
+ * 3-bucket score (static=1 / dynamic=2 / catch-all=3) whose same-bucket ties
+ * resolved by filesystem walk order, so two overlapping dynamic routes
+ * (`/[org]/[repo]` vs `/[user]/settings`) could match the WRONG page depending
+ * on traversal order. Specificity is fully POSITIONAL, like Next.js's router:
+ * compare segment by segment, and the catch-all kind is just the lowest-priority
+ * kind AT ITS POSITION, NOT a global "always last" bucket. The contract, most
+ * specific first:
+ *   1. Compare segment by segment: at the same position a static literal (kind 0)
+ *      outranks a dynamic `[x]` (kind 1), which outranks a catch-all
+ *      `[...x]` / `[[...x]]` (kind 2). So `/[user]/settings` beats `/[org]/[repo]`
+ *      (static tail wins), AND `/docs/[[...slug]]` beats `/[org]/[repo]` (a
+ *      literal first segment outranks a dynamic one, even though the former ends
+ *      in a catch-all). A global catch-all-last rule would wrongly shadow the
+ *      literal-prefixed catch-all behind every all-dynamic route.
+ *   2. With an identical kind prefix, the SHORTER (prefix) route ranks first, so
+ *      an explicit `/docs` beats the optional-catch-all base `/docs/[[...slug]]`
+ *      for `/docs` (the optional catch-all also matches zero trailing segments,
+ *      so the shorter exact route is the more specific match). Standard
+ *      lexicographic order on the kind arrays.
+ *   3. A genuine tie (identical kinds + length, e.g. `/[a]/[b]` vs `/[c]/[d]`)
+ *      resolves by an alphabetical `routeDir` key, NOT walk order, so the match
+ *      is deterministic across environments.
+ *
+ * The result is a valid total order (lexicographic on kind arrays with a unique
+ * final tiebreak), so `Array.sort` is correct and deterministic regardless of
+ * the filesystem traversal order.
+ * @param {PageRoute} a
+ * @param {PageRoute} b
+ * @returns {number}
+ */
+export function compareSpecificity(a, b) {
+  const sa = urlSegmentsOf(a.routeDir).map(segKind);
+  const sb = urlSegmentsOf(b.routeDir).map(segKind);
+  const n = Math.min(sa.length, sb.length);
+  for (let i = 0; i < n; i++) if (sa[i] !== sb[i]) return sa[i] - sb[i];
+  if (sa.length !== sb.length) return sa.length - sb.length; // shorter (prefix) first
+  return a.routeDir < b.routeDir ? -1 : a.routeDir > b.routeDir ? 1 : 0;
 }
 
 /**

package/src/ssr.js

@@ -1,11 +1,11 @@
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { renderToString, isNotFound, isRedirect, lookupModuleUrl, isLazy, cspNonce } from '@webjsdev/core';
-import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath, vendorPreconnectOrigins } from './importmap.js';
+import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath, vendorPreconnectOrigins, vendorPreloadTargets } from './importmap.js';
 import { withBasePath } from './base-path.js';
 import { withAssetHash } from './asset-hash.js';
 import { jsonForScriptTag } from './script-tag-json.js';
-import { transitiveDeps } from './module-graph.js';
+import { transitiveDeps, bareImports } from './module-graph.js';
 import { seedingEnabled, collectSeeds, buildSeedScript } from './action-seed.js';
 import { BUFFERED_MARKER, STREAM_MARKER } from './conditional-get.js';
 import {
@@ -189,6 +189,26 @@ export async function ssrPage(route, params, url, opts) {
       opts.serverFiles,
       opts.elidableComponents,
     );
+    // Vendor modulepreload (#754): flatten the npm CDN waterfall by hinting the
+    // vendor URLs the page's SHIPPED modules actually import, fetched in parallel
+    // instead of discovered level by level. The walk roots are the BOOT's shipped
+    // module set (`moduleUrls`, which already drops inert page/layout modules and
+    // substitutes an import-only page with its components) plus the rendered
+    // components, so a vendor reached ONLY through a dropped module (a page's
+    // SSR-only direct import OR its SSR-only relative helper) is never preloaded
+    // (no over-fetch).
+    const shippedRoots = moduleUrls.map((u) =>
+      resolve(opts.appDir, u.startsWith('/') ? u.slice(1) : u));
+    const vendorPreloads = vendorPreloadTargets(
+      reachedVendorSpecifiers(
+        opts.moduleGraph,
+        shippedRoots,
+        eagerComponents,
+        opts.appDir,
+        opts.elidableComponents,
+        opts.serverFiles,
+      ),
+    );
     // Extract CSP nonce from request headers (if present).
     const nonce = opts.req ? getNonce(opts.req) : undefined;
     const wrapOpts = {
@@ -197,6 +217,7 @@ export async function ssrPage(route, params, url, opts) {
       dev: opts.dev,
       streaming: suspenseCtx.pending.length > 0,
       preloads,
+      vendorPreloads,
       lazyComponents,
       nonce,
     };
@@ -1232,6 +1253,26 @@ function wrapHead(opts) {
       `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
     );
   }
+  // Vendor modulepreload (#754): the npm CDN dependencies the page reaches,
+  // hinted up front to flatten the cross-origin waterfall. The href comes
+  // straight from the importmap target (byte-identical, no `fp()` rewrite, so
+  // the browser does not double-fetch) and carries the importmap's `integrity`.
+  // `preloadCrossOriginAttr` adds `crossorigin` for a cross-origin CDN url (a
+  // same-origin pinned `/__webjs/vendor/*` url gets none). Deduped against the
+  // app module/component preloads already emitted above.
+  const emittedPreloadHrefs = new Set([
+    ...opts.moduleUrls.map((u) => fp(u)),
+    ...(opts.preloads || []).map((u) => fp(u)),
+  ]);
+  for (const v of opts.vendorPreloads || []) {
+    if (emittedPreloadHrefs.has(v.href)) continue;
+    emittedPreloadHrefs.add(v.href);
+    const integrity = v.integrity ? ` integrity="${escapeAttr(v.integrity)}"` : '';
+    linkTags.push(
+      `<link rel="modulepreload" href="${escapeAttr(v.href)}"` +
+      `${preloadCrossOriginAttr(v.href)}${integrity}${noncePreload}>`,
+    );
+  }
   if (Array.isArray(m.preload)) {
     for (const p of m.preload) {
       if (!p || !p.href) continue;
@@ -1493,6 +1534,63 @@ function deduplicatedPreloads(componentUrls, moduleUrls, graph, entryFiles, appD
   return result;
 }
 
+/**
+ * Collect the bare npm vendor specifiers the page's SHIPPED modules import
+ * (#754). The walk ROOTS are the boot's actually-shipped module set: the caller
+ * passes `entryFiles` = the absolute paths of `moduleUrls` (which already drops
+ * inert page/layout modules and substitutes an import-only page with its
+ * components), plus `componentUrls` = the rendered components. From those roots
+ * it walks the transitive app-graph closure (elidable components and the subtree
+ * reachable only through them excluded), and collects each reached file's bare
+ * imports, excluding server files. The specifiers are resolved to `modulepreload`
+ * targets via the vendor importmap; a specifier not in the map (unpinned /
+ * unreached) drops out there.
+ *
+ * Because the roots are the SHIPPED set, a vendor reached ONLY through a module
+ * dropped from the boot, whether a dropped page's SSR-only DIRECT vendor import
+ * or its SSR-only RELATIVE HELPER's vendor, is never collected: the dropped
+ * module is not a root, and nothing that ships imports it (pages/layouts are not
+ * importable). So the canonical SSR-only-dependency pattern (which elision keeps
+ * off the client) is never preloaded (no over-fetch).
+ *
+ * @param {import('./module-graph.js').ModuleGraph | undefined} graph
+ * @param {string[]} entryFiles  absolute paths of the SHIPPED page/layout modules (from `moduleUrls`)
+ * @param {string[]} componentUrls  rendered eager component URL paths
+ * @param {string} appDir
+ * @param {Set<string>} [elidableComponents]
+ * @param {Set<string>} [serverFiles]  the action / server-file index (`'use server'`, incl. no-`.server.` files)
+ * @returns {Set<string>}
+ */
+function reachedVendorSpecifiers(graph, entryFiles, componentUrls, appDir, elidableComponents, serverFiles) {
+  /** @type {Set<string>} */
+  const specs = new Set();
+  if (!graph) return specs;
+  const bare = bareImports(graph);
+  if (!bare.size) return specs;
+  // Roots = the SHIPPED page/layout modules (already inert-dropped + import-only
+  // expanded by the caller) + the rendered components, keyed by the graph's own
+  // absolute paths. Walk their non-elided transitive closure.
+  const allEntries = [...entryFiles];
+  for (const url of componentUrls) {
+    allEntries.push(resolve(appDir, url.startsWith('/') ? url.slice(1) : url));
+  }
+  const files = new Set(allEntries);
+  for (const dep of transitiveDeps(graph, allEntries, appDir, elidableComponents)) files.add(dep);
+  for (const file of files) {
+    // A server file is never served to the browser (its source is an RPC /
+    // throw-at-load stub), so a vendor it imports never ships and must NOT be
+    // preloaded. `transitiveDeps` stops AT a server-file boundary but still
+    // returns the boundary file itself, so filter it: the `.server.*` suffix
+    // AND the action index (a `'use server'` file without the suffix), matching
+    // `deduplicatedPreloads`' `byIndex` filter.
+    if (/\.server\.m?[jt]s$/.test(file)) continue;
+    if (serverFiles && serverFiles.has && serverFiles.has(file)) continue;
+    const fileBare = bare.get(file);
+    if (fileBare) for (const spec of fileBare) specs.add(spec);
+  }
+  return specs;
+}
+
 /**
  * Build a streaming Response. Degrades to a single-flush response when
  * there are no pending Suspense boundaries.

package/src/testing.d.ts

@@ -103,3 +103,13 @@ export declare function rawActionRequest(
     contentType?: string;
   },
 ): Promise<Response>;
+
+/** Browser-test harness (#806): a webjs handler a web-test-runner config
+ * proxies module requests to, so a browser test can import a real `.ts`
+ * component that imports a `'use server'` action. `importmapHtml()` is the
+ * `<script type="importmap">` to inject into the test page (call after warmup). */
+export declare function createBrowserTestHandler(appDir: string): Promise<{
+  handle: Handle;
+  warmup: () => Promise<void>;
+  importmapHtml: () => string;
+}>;

package/src/testing.js

@@ -295,9 +295,13 @@ export async function invokeActionForTest(app, serverFilePath, fnName, args = []
 
   if (!res.ok && throwOnError) {
     const msg = (parsed && parsed.error) || `webjs action ${fnName} -> ${res.status}`;
-    const err = /** @type {Error & { status?: number, response?: Response }} */ (new Error(msg));
+    const err = /** @type {Error & { status?: number, response?: Response, digest?: string }} */ (new Error(msg));
     err.status = res.status;
     err.response = res;
+    // Prod sanitization (#749) returns a generic message + a correlation digest;
+    // surface the digest on the thrown error so a test (or a caller) can map it
+    // to the server log line, mirroring the generated client stub.
+    if (parsed && parsed.digest) err.digest = parsed.digest;
     throw err;
   }
   return parsed;
@@ -344,3 +348,38 @@ export async function rawActionRequest(app, serverFilePath, fnName, args = [], o
 
   return testRequest(handle, endpoint, { method: 'POST', headers, body });
 }
+
+/**
+ * Browser-test harness (#806): build a webjs handler that a `web-test-runner`
+ * config can proxy module requests to, so a `test/**​/browser/*.test.js` file
+ * can import a real `.ts` component that imports a `'use server'` action and it
+ * loads + hydrates in a real browser. Plain WTR serves raw TS with no webjs
+ * transform, so the component (and its `#`-alias / `.server.ts` imports) never
+ * resolves; this handler runs the SAME dev pipeline (TS strip, `.server.ts` ->
+ * RPC stub, `#` alias, `/__webjs/core/*`, the importmap) as `webjs dev`.
+ *
+ * Uses `testMode` so ANY app file under appDir is servable (a component a test
+ * imports is not route-reachable, so it is absent from the browser-bound graph
+ * the normal serve gate requires). The `.server.*` source guardrail is
+ * unchanged, so no server source is exposed. `importmapHtml()` returns the
+ * `<script type="importmap">` to inject into the test page (call after warmup,
+ * so the map is final).
+ *
+ * The dev handler + importmap builder are LAZILY imported so importing the rest
+ * of `@webjsdev/server/testing` stays light (they pull the full server + the
+ * `ws` WebSocket subsystem).
+ *
+ * @param {string} appDir  the webjs app root (usually `process.cwd()`)
+ * @returns {Promise<{ handle: Handle, warmup: () => Promise<void>, importmapHtml: () => string }>}
+ */
+export async function createBrowserTestHandler(appDir) {
+  const { createRequestHandler } = await import('./dev.js');
+  const { importMapTag } = await import('./importmap.js');
+  const app = await createRequestHandler({ appDir, dev: true, testMode: true });
+  if (app.warmup) await app.warmup();
+  return {
+    handle: app.handle,
+    warmup: app.warmup || (async () => {}),
+    importmapHtml: () => importMapTag(),
+  };
+}