@webjsdev/server 0.8.13 → 0.8.14

package/package.json

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

package/src/actions.js

@@ -301,7 +301,8 @@ export function serveServerOnlyStub(relPath) {
     `Cannot import "${relPath}" from browser code. ` +
     `This file is server-only (a .server.{js,ts} file with no 'use server' directive). ` +
     `Either add 'use server' at the top of the file to expose its exports as RPC, ` +
-    `or wrap the server-only logic in a separate *.server.{js,ts} action and import that instead.`;
+    `or wrap the server-only logic in a separate *.server.{js,ts} action and import that instead. ` +
+    `Docs: https://docs.webjs.com/docs/server-actions`;
   return `// webjs: server-only module stub for ${relPath} (no 'use server' directive)
 throw new Error(${JSON.stringify(msg)});
 `;

package/src/asset-hash.js

@@ -0,0 +1,266 @@
+/**
+ * Content-hash asset URLs for immutable caching (issue #243, feature 1).
+ *
+ * The problem: every served app module (`.js` / `.ts`) and `public/` asset
+ * ships `Cache-Control: public, max-age=3600` because its URL is
+ * un-versioned. The framework cannot serve them `immutable` (1 year) without
+ * a per-file fingerprint, because a deploy that changes a module's bytes
+ * keeps the SAME url, so a year-long immutable copy at an edge CDN would
+ * silently brick the next deploy (a real regression, see the core-serve note
+ * in `dev.js`). The importmap build id (`publishedBuildId`) does NOT change
+ * on an app-module byte change, so it cannot be the per-asset fingerprint.
+ *
+ * The fix: a PER-FILE content hash computed at serve time (no build step).
+ *
+ *   1. `withAssetHash(url)` appends `?v=<hash>` to a framework-emitted
+ *      SAME-ORIGIN absolute url (the importmap targets, the modulepreload
+ *      hrefs, the boot script specifiers). It is a NO-OP in DEV (so dev
+ *      output is byte-identical to before), a NO-OP for a CROSS-ORIGIN url
+ *      (a `https://` jspm vendor target, which jspm already versions and
+ *      which carries SRI keyed by the un-hashed url), and for a same-origin
+ *      `/`-rooted url it resolves the underlying file, looks up its hash, and
+ *      appends `?v=<hash>`.
+ *
+ *   2. The serve path (`dev.js`) serves any request carrying a `?v` query
+ *      `Cache-Control: public, max-age=31536000, immutable`. An un-fingerprinted
+ *      request keeps the 1h fallback. Dev stays `no-cache` regardless.
+ *
+ * Deploy-busts invariant: a deploy that changes a module's bytes changes its
+ * hash, so its emitted url changes, so a returning client fetches the new url
+ * instead of serving the stale immutable copy.
+ *
+ * The hash is a short prefix of a sha-256 over the file BYTES, computed
+ * synchronously (so the emit hot path stays sync) and memoized in a
+ * `Map<absPath, hash>`. The cache is cleared on the fs.watch rebuild (dev) so
+ * a changed file re-hashes, wired next to `clearVendorCache` in `dev.js`.
+ *
+ * @module asset-hash
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+
+/**
+ * Length of the emitted hex hash. 12 hex chars (48 bits) is plenty to
+ * distinguish builds of one file while keeping the url short. Collisions
+ * across DIFFERENT bytes of the SAME url are the only failure mode, and at
+ * 48 bits that is astronomically unlikely; a same-bytes-same-hash is exactly
+ * the desired behaviour.
+ *
+ * @type {number}
+ */
+const HASH_LEN = 12;
+
+/**
+ * Whether fingerprinting is active. Off in dev (so dev output is
+ * byte-identical to before this feature) and off until `setAssetRoots`
+ * binds the app + core roots. Both gates make `withAssetHash` a pure
+ * pass-through, which is what keeps the inert case byte-identical.
+ *
+ * @type {boolean}
+ */
+let _enabled = false;
+
+/** @type {string} */
+let _appDir = '';
+/** @type {string} */
+let _coreDir = '';
+
+/**
+ * A fingerprint of the current elision verdict (the elidable-component +
+ * inert-route set), folded into an APP MODULE's hash. An app module's SERVED
+ * body is not its raw source: `dev.js` runs `elideImportsFromSource` over it,
+ * stripping a side-effect import of a display-only component. That strip is a
+ * property of the IMPORTED component's verdict, not of the importer's own
+ * bytes, so when a component flips display-only <-> interactive the importer's
+ * served body changes while its source is byte-identical. Hashing the source
+ * alone would keep the same `?v`, and a returning client would hold the stale
+ * immutable copy (the now-interactive component never imported, so never
+ * hydrated) for the full immutable TTL. Folding the verdict fingerprint into
+ * the hash busts every app module's url on a verdict change, so the stale-copy
+ * window cannot open. Empty when no module is elidable (then an app module's
+ * hash is exactly `sha256(bytes)`), and only mixed for files under `_appDir`
+ * (core / public assets are never elision-transformed). Set by `dev.js`'s
+ * `ensureReady` after `analyzeElision`, re-set on every rebuild.
+ *
+ * @type {string}
+ */
+let _elisionFp = '';
+
+/**
+ * Memoized per-file content hash. Keyed by absolute path. Cleared on the
+ * fs.watch rebuild so a changed file re-hashes.
+ *
+ * @type {Map<string, string>}
+ */
+const _hashCache = new Map();
+
+/**
+ * Bind the asset-hash module to the app + core install roots and enable
+ * fingerprinting. Called once at boot by `dev.js` for a PROD server only
+ * (`dev === false`); a dev server never calls this, so `_enabled` stays
+ * false and `withAssetHash` is a pure no-op.
+ *
+ * @param {{ appDir: string, coreDir: string, enabled: boolean }} opts
+ * @returns {void}
+ */
+export function setAssetRoots(opts) {
+  _appDir = opts.appDir || '';
+  _coreDir = opts.coreDir || '';
+  _enabled = !!opts.enabled && !!_appDir && !!_coreDir;
+}
+
+/**
+ * Set the elision-verdict fingerprint folded into app-module hashes (see
+ * `_elisionFp`). A no-op when the value is unchanged; on a change it clears the
+ * hash cache so every app module re-hashes against the new verdict. `dev.js`
+ * calls this from `ensureReady` after `analyzeElision` (and again on each
+ * rebuild), passing a stable digest of the elidable-component + inert-route set
+ * (or `''` when nothing is elidable).
+ *
+ * @param {string} fp
+ * @returns {void}
+ */
+export function setElisionFingerprint(fp) {
+  const next = fp || '';
+  if (next === _elisionFp) return;
+  _elisionFp = next;
+  _hashCache.clear();
+}
+
+/**
+ * Clear the per-file hash cache. Wired into the dev rebuild path next to
+ * `clearVendorCache` so a changed file re-hashes (dev never fingerprints,
+ * but a future serve that re-derives the map after a rebuild stays correct,
+ * and tests rely on the clear to observe a re-hash after a byte change).
+ *
+ * @returns {void}
+ */
+export function clearAssetHashCache() {
+  _hashCache.clear();
+}
+
+/**
+ * Compute (and memoize) the short content hash for an absolute file path.
+ * Returns `''` when the file cannot be read, so the caller emits the url
+ * UNCHANGED (no `?v`), failing safe to the 1h fallback rather than breaking
+ * the url.
+ *
+ * @param {string} absPath
+ * @returns {string} the short hex hash, or `''` on a read failure
+ */
+export function assetHashFor(absPath) {
+  const cached = _hashCache.get(absPath);
+  if (cached !== undefined) return cached;
+  try {
+    const bytes = readFileSync(absPath);
+    const h = createHash('sha256').update(bytes);
+    // An app module's served body is elision-transformed, so fold the verdict
+    // fingerprint in (see `_elisionFp`). Core / public files are never
+    // transformed, so they hash over their bytes alone. Empty fp leaves an app
+    // module's hash at exactly `sha256(bytes)`.
+    if (_elisionFp && _appDir && absPath.startsWith(_appDir + sep)) {
+      h.update('\0');
+      h.update(_elisionFp);
+    }
+    const hash = h.digest('hex').slice(0, HASH_LEN);
+    _hashCache.set(absPath, hash);
+    return hash;
+  } catch {
+    // A transient read failure is NOT memoized (returning '' fails safe to the
+    // 1h fallback), so a later emit re-attempts instead of pinning the file to
+    // the fallback for the process lifetime.
+    return '';
+  }
+}
+
+/**
+ * Resolve a framework-emitted same-origin absolute url to the absolute file
+ * path it serves, or `null` when the url does not map to a fingerprintable
+ * same-origin file. Mirrors the serve-path resolution in `dev.js`:
+ *   - `/__webjs/core/<rel>`  -> `<coreDir>/<rel>`  (the core runtime)
+ *   - any other `/<rel>`     -> `<appDir>/<rel>`   (app modules + public/)
+ *
+ * Containment-checked against the respective root (the same trailing-separator
+ * boundary guard the serve path uses), so a `..`-laden url that escapes the
+ * root resolves to `null` and is emitted unchanged.
+ *
+ * The `?v` query / `#hash` are stripped before resolution (a freshly-emitted
+ * url never carries one, but stay robust). A cross-origin / protocol-relative
+ * / relative url is NOT a `/`-rooted same-origin path and returns `null`.
+ *
+ * @param {string} url
+ * @returns {string | null}
+ */
+function resolveUrlToFile(url) {
+  // Only a single-leading-slash same-origin path. A protocol-relative
+  // `//host` or an absolute `scheme://` url (a vendor CDN target) is not ours.
+  if (typeof url !== 'string' || url[0] !== '/' || url[1] === '/') return null;
+  // Strip any query / hash before mapping to a file.
+  let pathname = url;
+  const q = pathname.indexOf('?');
+  if (q !== -1) pathname = pathname.slice(0, q);
+  const h = pathname.indexOf('#');
+  if (h !== -1) pathname = pathname.slice(0, h);
+  let decoded = pathname;
+  try { decoded = decodeURIComponent(pathname); } catch { /* keep raw */ }
+
+  const CORE_PREFIX = '/__webjs/core/';
+  if (decoded.startsWith(CORE_PREFIX)) {
+    const rel = decoded.slice(CORE_PREFIX.length);
+    const abs = resolve(_coreDir, rel);
+    if (abs !== _coreDir && !abs.startsWith(_coreDir + sep)) return null;
+    return abs;
+  }
+  // A `/__webjs/*` path that is not a core module (e.g. a downloaded
+  // `/__webjs/vendor/<pkg>@<ver>.js` bundle) is already version-named, so it
+  // does not need fingerprinting and is left unchanged.
+  if (decoded.startsWith('/__webjs/')) return null;
+
+  const abs = join(_appDir, decoded);
+  if (abs !== _appDir && !abs.startsWith(_appDir + sep)) return null;
+  return abs;
+}
+
+/**
+ * Append `?v=<content-hash>` to a framework-emitted same-origin absolute url
+ * for immutable caching. Composes with `withBasePath`: call ORDER is basePath
+ * then `withAssetHash` (the `?v` is a query the ingress base-path strip never
+ * touches, and the file resolution here works on the post-basePath url because
+ * a `<basePath>/app/foo.js` still resolves under `_appDir` only after the
+ * basePath is stripped, so callers apply `withAssetHash` to the ALREADY
+ * base-path-prefixed url and pass the base path so we strip it for resolution).
+ *
+ * No-op when:
+ *   - fingerprinting is disabled (dev, or roots unset) -> byte-identical output;
+ *   - the url is cross-origin / protocol-relative / relative (a vendor CDN
+ *     target keeps its exact url, so its SRI key, computed over the un-hashed
+ *     url in #235, still matches, and jspm already versions it);
+ *   - the url does not resolve to a readable same-origin file (fail-safe to the
+ *     1h fallback).
+ *
+ * @param {string} url   the (possibly base-path-prefixed) same-origin url
+ * @param {string} [basePath]  the active base path, stripped before file resolution
+ * @returns {string}
+ */
+export function withAssetHash(url, basePath = '') {
+  if (!_enabled) return url;
+  if (typeof url !== 'string' || url[0] !== '/' || url[1] === '/') return url;
+  // Resolve against the file system using the base-path-stripped url, so a
+  // sub-path-deployed `<basePath>/app/foo.js` maps to `<appDir>/app/foo.js`.
+  let forResolve = url;
+  if (basePath && url.startsWith(basePath + '/')) {
+    forResolve = url.slice(basePath.length);
+  } else if (basePath && url === basePath) {
+    forResolve = '/';
+  }
+  const abs = resolveUrlToFile(forResolve);
+  if (!abs) return url;
+  const hash = assetHashFor(abs);
+  if (!hash) return url;
+  // The freshly-emitted url never already carries a query, but stay robust:
+  // merge with `&` if one is somehow present.
+  const sepChar = url.includes('?') ? '&' : '?';
+  return `${url}${sepChar}v=${hash}`;
+}

package/src/dev.js

@@ -115,6 +115,7 @@ function shouldAccessLog(pathname) {
 }
 import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
+import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
 import {
@@ -472,6 +473,15 @@ export async function createRequestHandler(opts) {
     existsSync(join(distDir, 'webjs-core-browser.js'));
   await setCoreInstall(coreDir, distComplete);
 
+  // Content-hash asset URLs for immutable caching (issue #243). Bind the
+  // asset-hash module to the app + core roots and enable fingerprinting in
+  // PROD only. In dev `withAssetHash` stays a pure no-op (never enabled), so
+  // the dev importmap / boot / preload output is byte-identical to before.
+  // This runs AFTER setBasePath / setCoreInstall, but those recompute the
+  // importmap hash with `{ fingerprint: false }`, so the boot-published build
+  // id is a stable deploy fingerprint independent of per-file content hashes.
+  setAssetRoots({ appDir, coreDir, enabled: !dev });
+
   // When an app commits a vendor pin (.webjs/vendor/importmap.json) it carries a
   // deterministic vendor map that is cheap to read (one file, no analysis, no
   // network). Resolve it AT BOOT and publish the build id immediately so the
@@ -678,6 +688,25 @@ export async function createRequestHandler(opts) {
               : { elidableComponents: new Set(), inertRouteModules: new Set() };
             state.elidableComponents = r.elidableComponents;
             state.inertRouteModules = r.inertRouteModules;
+            // Fold the elision verdict into app-module content hashes (#243): an
+            // app module's served body is elision-transformed, so a verdict flip
+            // must bust its `?v` even when its source is byte-identical. A stable
+            // string of the sorted elidable + inert paths, RELATIVIZED to appDir
+            // so the fingerprint is a property of the app's STRUCTURE, not its
+            // filesystem location (two deploys at different absolute paths, or
+            // two identical apps, produce the same fingerprint). asset-hash
+            // digests it into each app-module hash; '' when nothing is elidable,
+            // so a no-elision app's hash stays exactly `sha256(bytes)`.
+            {
+              // `appDir + sep` boundary (matches asset-hash's containment guard)
+              // so a sibling-prefix dir cannot be mis-relativized.
+              const rel = (p) => (p.startsWith(appDir + sep) ? p.slice(appDir.length) : p);
+              const elidedPaths = [
+                ...state.elidableComponents,
+                ...state.inertRouteModules,
+              ].map(rel).sort();
+              setElisionFingerprint(elidedPaths.length ? elidedPaths.join('\n') : '');
+            }
             t.elision = now() - m;
             if (dev) {
               for (const { className, file } of await findOrphanComponents(appDir)) {
@@ -834,6 +863,11 @@ export async function createRequestHandler(opts) {
     // best-effort (see emitRouteTypes).
     if (dev) void emitRouteTypes();
     clearVendorCache();
+    // Content-hash asset cache (#243): clear so a changed file re-hashes and
+    // its emitted `?v` busts the stale immutable copy. A no-op in dev (the
+    // module is never enabled there), kept for correctness + the deploy-busts
+    // regression test, which clears + re-hashes to observe a changed `?v`.
+    clearAssetHashCache();
     state.tsCache.clear();
     // Invalidate the lazy analysis; the next request rebuilds the graph,
     // component scan, gate, action index, middleware, elision, and vendor map.
@@ -1131,7 +1165,12 @@ export async function createRequestHandler(opts) {
       // interactivity site-wide. Matched on the decoded path, like handleCore.
       let assetPath = probePath;
       try { assetPath = decodeURIComponent(probePath); } catch { /* keep raw on malformed escape */ }
-      const staticResp = await tryServeFrameworkStatic(assetPath, req.method.toUpperCase(), { coreDir, appDir, dev });
+      // Content-hash fingerprint (#243): a `?v=` query means an immutable,
+      // content-addressed asset url. Detected off the raw request url here
+      // (probePath was parsed from it above).
+      let assetVersioned = false;
+      try { assetVersioned = new URL(req.url).searchParams.has('v'); } catch { /* none */ }
+      const staticResp = await tryServeFrameworkStatic(assetPath, req.method.toUpperCase(), { coreDir, appDir, dev, versioned: assetVersioned });
       if (staticResp) return staticResp;
       // Build all whole-app analysis on the first request (memoized), before
       // any SSR, module serve, gate check, action dispatch, or middleware runs.
@@ -1173,7 +1212,14 @@ export async function createRequestHandler(opts) {
     const moduleUrls = [page.route.file, ...page.route.layouts].map((f) => {
       let rel = f.startsWith(appDir) ? f.slice(appDir.length) : f;
       const url = rel.split('\\').join('/').replace(/^\/?/, '/');
-      return withBasePath(url, basePathValue);
+      // Mirror ssr.js's emit (basePath THEN `?v`) so the 103 Early Hints preload
+      // the SAME url the body's modulepreload + boot specifiers request (#243).
+      // A bare url would warm a different url and waste the hint. No-op in dev.
+      // Best-effort: a request landing in the narrow pre-warm window (before the
+      // elision verdict is set) hashes against an empty fingerprint, so the hint
+      // can mismatch the post-warm body for that one request, only a wasted
+      // speculative preload, never a stale body (the body url is authoritative).
+      return withAssetHash(withBasePath(url, basePathValue), basePathValue);
     });
     return { moduleUrls };
   }
@@ -1415,11 +1461,15 @@ export async function startServer(opts) {
  *
  * @param {string} path decoded pathname
  * @param {string} method upper-cased HTTP method
- * @param {{ coreDir: string, appDir: string, dev: boolean }} ctx
+ * @param {{ coreDir: string, appDir: string, dev: boolean, versioned?: boolean }} ctx
+ *   `versioned` is true when the request carried a `?v=` query (a
+ *   content-hash-fingerprinted url, issue #243); the core module is then served
+ *   `immutable` (1 year) instead of the 1h fallback, since the hash in the url
+ *   busts the cache on the next deploy.
  * @returns {Promise<Response|null>} a Response, or null when path is not one of these assets
  */
 async function tryServeFrameworkStatic(path, method, ctx) {
-  const { coreDir, appDir, dev } = ctx;
+  const { coreDir, appDir, dev, versioned } = ctx;
 
   // Dev live-reload client.
   if (path === '/__webjs/reload.js') {
@@ -1451,7 +1501,11 @@ async function tryServeFrameworkStatic(path, method, ctx) {
     if (abs !== coreDir && !abs.startsWith(coreDir + sep)) {
       return new Response('forbidden', { status: 403 });
     }
-    return fileResponse(abs, { dev, immutable: false });
+    // A `?v=<hash>` request is content-addressed, so serve it `immutable` (#243):
+    // the hash busts the cache on the next core bump, so the regression the
+    // un-versioned 1h cap guards against (a stale immutable core after a bump)
+    // cannot recur. An un-fingerprinted request keeps the 1h fallback.
+    return fileResponse(abs, { dev, immutable: !!versioned });
   }
 
   // Vendor URL handler for `webjs vendor pin --download` mode only. In default
@@ -1494,6 +1548,11 @@ async function handleCore(req, ctx) {
   let path;
   try { path = decodeURIComponent(url.pathname); } catch { path = url.pathname; }
   const method = req.method.toUpperCase();
+  // Content-hash fingerprint (#243): a `?v=` query marks a content-addressed
+  // asset url that may be served `immutable` (the hash busts the cache on a
+  // byte change). The pathname (query stripped by `url.pathname`) resolves the
+  // file as today; only the cache header changes when `?v` is present.
+  const versioned = url.searchParams.has('v');
 
   // Health / readiness probes (`/__webjs/health`, `/__webjs/ready`) and the
   // framework-internal static assets (`/__webjs/core/*`, `/__webjs/reload.js`,
@@ -1501,7 +1560,7 @@ async function handleCore(req, ctx) {
   // so they are not repeated here. This fallback covers the (currently
   // unreachable) case of handleCore being entered for one of those assets, so
   // the routing stays correct if a future caller bypasses the early path.
-  const frameworkStatic = await tryServeFrameworkStatic(path, method, { coreDir, appDir, dev });
+  const frameworkStatic = await tryServeFrameworkStatic(path, method, { coreDir, appDir, dev, versioned });
   if (frameworkStatic) return frameworkStatic;
 
   // Internal server-action RPC endpoint
@@ -1559,7 +1618,8 @@ async function handleCore(req, ctx) {
     if (!abs.startsWith(publicRoot)) {
       return new Response(null, { status: 404 });
     }
-    if (await exists(abs)) return fileResponse(abs, { dev, immutable: false });
+    // A `?v=<hash>` public asset is content-addressed -> immutable (#243).
+    if (await exists(abs)) return fileResponse(abs, { dev, immutable: versioned });
   }
 
   // User source modules (served as ES modules, with action-file rewriting).
@@ -1631,13 +1691,15 @@ async function handleCore(req, ctx) {
         elidableComponents: state.elidableComponents,
         appDir,
       };
+      // A `?v=<hash>` app-module request is content-addressed -> immutable
+      // (#243); an un-fingerprinted request keeps the 1h fallback.
       if (/\.m?ts$/.test(abs)) {
-        return tsResponse(abs, dev, elideOpts, state.tsCache);
+        return tsResponse(abs, dev, elideOpts, state.tsCache, versioned);
       }
       if (/\.m?js$/.test(abs)) {
-        return jsModuleResponse(abs, dev, elideOpts);
+        return jsModuleResponse(abs, dev, elideOpts, versioned);
       }
-      return fileResponse(abs, { dev, immutable: false });
+      return fileResponse(abs, { dev, immutable: versioned });
     }
   }
 
@@ -1991,8 +2053,10 @@ async function fileResponse(abs, opts) {
  * @param {string} abs
  * @param {boolean} dev
  * @param {{ moduleGraph: any, elidableComponents: Set<string>|undefined, appDir: string }} elideOpts
+ * @param {boolean} [immutable]  true for a `?v=<hash>` content-addressed request (#243):
+ *   serve `immutable` (1 year) instead of the 1h fallback. Dev stays `no-cache`.
  */
-async function jsModuleResponse(abs, dev, elideOpts) {
+async function jsModuleResponse(abs, dev, elideOpts, immutable) {
   let source;
   try { source = await readFile(abs, 'utf8'); }
   catch { return new Response('Not found', { status: 404 }); }
@@ -2003,7 +2067,7 @@ async function jsModuleResponse(abs, dev, elideOpts) {
   // weak ETag + 304 (see fileResponse).
   const headers = {
     'content-type': 'application/javascript; charset=utf-8',
-    'cache-control': dev ? 'no-cache' : 'public, max-age=3600',
+    'cache-control': dev ? 'no-cache' : immutable ? 'public, max-age=31536000, immutable' : 'public, max-age=3600',
     [BUFFERED_MARKER]: '1',
   };
   return new Response(code, { status: 200, headers });
@@ -2049,15 +2113,21 @@ async function stripTs(source, _abs) {
  * @param {boolean} dev
  * @param {{ moduleGraph: any, elidableComponents: Set<string>|undefined, appDir: string }} [elideOpts]
  * @param {Map<string, { mtimeMs: number, code: string, map: string | null }>} cache the handler's `state.tsCache`
+ * @param {boolean} [immutable]  true for a `?v=<hash>` content-addressed request (#243):
+ *   serve `immutable` (1 year) instead of the 1h fallback. The cached BODY is
+ *   the same bytes regardless; only the cache header varies. Dev stays `no-cache`.
  */
-async function tsResponse(abs, dev, elideOpts, cache) {
+async function tsResponse(abs, dev, elideOpts, cache, immutable) {
+  // The body bytes are identical with or without `?v`; only the cache header
+  // changes, so the per-mtime cache stays a single entry.
+  const cacheControl = dev ? 'no-cache' : immutable ? 'public, max-age=31536000, immutable' : 'public, max-age=3600';
   const st = await stat(abs);
   const cached = cache.get(abs);
   if (cached && cached.mtimeMs === st.mtimeMs) {
     return new Response(cached.code, {
       headers: {
         'content-type': 'application/javascript; charset=utf-8',
-        'cache-control': dev ? 'no-cache' : 'public, max-age=3600',
+        'cache-control': cacheControl,
         [BUFFERED_MARKER]: '1',
       },
     });
@@ -2088,7 +2158,8 @@ async function tsResponse(abs, dev, elideOpts, cache) {
           `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).`
+          `Run \`webjs check\` for guidance (no-non-erasable-typescript rule). ` +
+          `Docs: https://docs.webjs.com/docs/typescript`
         // Prod: terse, no path leak, no Node-message leak (Node's
         // message can include source snippets). Operators get the
         // detail in server logs above.
@@ -2114,7 +2185,7 @@ async function tsResponse(abs, dev, elideOpts, cache) {
   return new Response(code, {
     headers: {
       'content-type': 'application/javascript; charset=utf-8',
-      'cache-control': dev ? 'no-cache' : 'public, max-age=3600',
+      'cache-control': cacheControl,
       [BUFFERED_MARKER]: '1',
     },
   });

package/src/importmap.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { digestHex } from './crypto-utils.js';
 import { jsonForScriptTag } from './script-tag-json.js';
 import { withBasePath } from './base-path.js';
+import { withAssetHash } from './asset-hash.js';
 
 // Local attribute escaper. Matches ssr.js's escapeAttr (the source
 // of truth for HTML attribute escaping in this package). Kept inline
@@ -53,7 +54,7 @@ let _basePath = '';
  */
 export async function setBasePath(basePath) {
   _basePath = basePath || '';
-  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap()));
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap({ fingerprint: false })));
 }
 
 /**
@@ -87,7 +88,7 @@ let _vendorIntegrity = {};
 export async function setVendorEntries(entries, integrity) {
   _extraEntries = entries;
   _vendorIntegrity = integrity || {};
-  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap()));
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap({ fingerprint: false })));
 }
 
 /**
@@ -228,7 +229,7 @@ let _coreEntries = {
  */
 export async function setCoreInstall(coreDir, distMode) {
   _coreEntries = buildCoreEntries(coreDir, !!distMode);
-  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap()));
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap({ fingerprint: false })));
 }
 
 /**
@@ -319,7 +320,21 @@ export function buildCoreEntries(coreDir, distMode) {
   return out;
 }
 
-export function buildImportMap() {
+/**
+ * Build the import map object.
+ *
+ * @param {{ fingerprint?: boolean }} [opts]  When `fingerprint` is true (the
+ *   default, used by the SERVED map in `importMapTag`), same-origin targets
+ *   get a `?v=<content-hash>` suffix for immutable caching (issue #243); a
+ *   cross-origin CDN target is left untouched (`withAssetHash` skips it, so
+ *   its SRI key is unchanged). When false (used by the internal
+ *   `importMapHash()` computation), no `?v` is appended, so the published
+ *   build id stays a STABLE deploy fingerprint independent of per-file
+ *   content hashes (the build id only needs to be stable within a deploy).
+ *   In dev, `withAssetHash` is a no-op regardless, so both forms are equal.
+ */
+export function buildImportMap(opts = {}) {
+  const fingerprint = opts.fingerprint !== false;
   const merged = {
     ..._coreEntries,
     ..._extraEntries,
@@ -333,11 +348,18 @@ export function buildImportMap() {
   /** @type {Record<string, string>} */
   const imports = {};
   // Prefix every same-origin absolute target with the sub-path base
-  // (issue #256). `withBasePath` is a no-op when the base path is empty
-  // (so a root-mounted app's map is byte-identical) and leaves a
-  // cross-origin `https://` CDN vendor target untouched (only the
-  // framework's own `/__webjs/*` and same-origin vendor targets move).
-  for (const k of Object.keys(merged).sort()) imports[k] = withBasePath(merged[k], _basePath);
+  // (issue #256), THEN (issue #243) append `?v=<content-hash>` to a
+  // same-origin target for immutable caching. The order is basePath then
+  // `?v`, so a sub-path app emits `<basePath>/app/foo.js?v=hash`.
+  // `withBasePath` is a no-op when the base path is empty and leaves a
+  // cross-origin `https://` CDN vendor target untouched; `withAssetHash`
+  // is a no-op in dev / when disabled and also leaves a cross-origin target
+  // untouched (only the framework's own `/__webjs/*` core + same-origin
+  // app/public targets get a `?v`).
+  for (const k of Object.keys(merged).sort()) {
+    const based = withBasePath(merged[k], _basePath);
+    imports[k] = fingerprint ? withAssetHash(based, _basePath) : based;
+  }
 
   // Emit `integrity` per the importmap-integrity spec (Chrome 132+,
   // Safari 18.4+, Firefox flagged). Browsers without support ignore
@@ -366,6 +388,43 @@ export function buildImportMap() {
   return out;
 }
 
+/**
+ * Derive the cross-origin vendor CDN origins from the resolved vendor
+ * importmap, most-common first (issue #243, auto vendor preconnect). For an
+ * UNPINNED app resolving vendors live from a cross-origin CDN (ga.jspm.io,
+ * or jsdelivr / unpkg / skypack with `--from`), this returns that origin so
+ * the head can warm DNS + TLS + TCP before the importmap resolves. A
+ * same-origin PINNED app (vendors served from `/__webjs/vendor/*` on the
+ * app's own origin), or an app with no cross-origin vendors, returns `[]`.
+ *
+ * Derived from the resolved targets (`_extraEntries`, the vendor map), NOT a
+ * hardcoded string, so a `--from jsdelivr` app preconnects to jsdelivr. The
+ * origins are deduped + sorted by frequency (the primary CDN first) and the
+ * list is bounded so a map spanning several CDNs cannot emit an unbounded
+ * preconnect set.
+ *
+ * @param {number} [max]  cap on the number of origins returned (default 2)
+ * @returns {string[]}  e.g. `['https://ga.jspm.io']`
+ */
+export function vendorPreconnectOrigins(max = 2) {
+  /** @type {Map<string, number>} */
+  const counts = new Map();
+  for (const target of Object.values(_extraEntries)) {
+    if (typeof target !== 'string') continue;
+    // Only an absolute `scheme://host` cross-origin url has an origin to
+    // preconnect. A same-origin `/__webjs/vendor/*` (downloaded-pin) target
+    // is `/`-rooted and skipped (no cross-origin to warm).
+    if (!/^https?:\/\//i.test(target)) continue;
+    let origin;
+    try { origin = new URL(target).origin; } catch { continue; }
+    counts.set(origin, (counts.get(origin) || 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, Math.max(0, max))
+    .map(([origin]) => origin);
+}
+
 /**
  * Serialise the import map to an HTML script tag string.
  *

package/src/ssr.js

@@ -1,8 +1,9 @@
 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 } from './importmap.js';
+import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath, vendorPreconnectOrigins } from './importmap.js';
 import { withBasePath } from './base-path.js';
+import { withAssetHash } from './asset-hash.js';
 import { jsonForScriptTag } from './script-tag-json.js';
 import { readToken, newToken, cookieHeader } from './csrf.js';
 import { transitiveDeps } from './module-graph.js';
@@ -786,8 +787,14 @@ function wrapHead(opts) {
   // (read from importmap.js's module state), the same value the importmap
   // targets were prefixed with, so the boot specifiers and the map agree.
   const bp = basePath();
+  // Content-hash asset URLs (issue #243): after base-path-prefixing, append
+  // `?v=<hash>` to a same-origin module specifier for immutable caching. A
+  // no-op in dev (so the boot script is byte-identical) and for a bare/
+  // cross-origin specifier; same compose order as the importmap targets
+  // (basePath then `?v`).
+  const fp = (u) => withAssetHash(withBasePath(u, bp), bp);
   const imports = opts.moduleUrls
-    .map((u) => `import ${jsonForScriptTag(withBasePath(u, bp))};`)
+    .map((u) => `import ${jsonForScriptTag(fp(u))};`)
     .join('\n');
   const rawLazyEntries = opts.lazyComponents && Object.keys(opts.lazyComponents).length
     ? opts.lazyComponents
@@ -795,9 +802,14 @@ function wrapHead(opts) {
   // The lazy map's values are same-origin module URLs `observeLazy` will
   // dynamically import, so prefix them with the base path too (no-op when
   // empty).
-  const lazyEntries = rawLazyEntries && bp
+  // The lazy map's values are same-origin module URLs `observeLazy` will
+  // dynamically import, so base-path-prefix AND content-hash them (#243), the
+  // same as the eager boot specifiers. `fp` is a pure no-op in dev and at the
+  // root mount with fingerprinting off, so the mapped map equals the raw one
+  // byte-for-byte there; only prod fingerprinting / a sub-path mount changes it.
+  const lazyEntries = rawLazyEntries
     ? Object.fromEntries(
-        Object.entries(rawLazyEntries).map(([tag, u]) => [tag, withBasePath(u, bp)]),
+        Object.entries(rawLazyEntries).map(([tag, u]) => [tag, fp(u)]),
       )
     : rawLazyEntries;
   const lazyBoot = lazyEntries
@@ -1102,16 +1114,20 @@ function wrapHead(opts) {
   // decided on the ORIGINAL url, so the integrity lookup still keys on the
   // unprefixed map url and a cross-origin CDN url (never prefixed) keeps its
   // crossorigin attribute.
-  const bpPreload = basePath();
+  // Content-hash (#243): the href additionally gets a `?v=<hash>` after the
+  // base-path prefix (a no-op in dev / for a cross-origin url), but
+  // `crossorigin` / `integrity` are still decided on the ORIGINAL url, so the
+  // integrity lookup keys on the unprefixed/unhashed map url and a cross-origin
+  // CDN url (never prefixed, never hashed) keeps its crossorigin attribute.
   for (const url of opts.moduleUrls) {
     linkTags.push(
-      `<link rel="modulepreload" href="${escapeAttr(withBasePath(url, bpPreload))}"` +
+      `<link rel="modulepreload" href="${escapeAttr(fp(url))}"` +
       `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
     );
   }
   for (const url of opts.preloads || []) {
     linkTags.push(
-      `<link rel="modulepreload" href="${escapeAttr(withBasePath(url, bpPreload))}"` +
+      `<link rel="modulepreload" href="${escapeAttr(fp(url))}"` +
       `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
     );
   }
@@ -1125,6 +1141,58 @@ function wrapHead(opts) {
     }
   }
 
+  // preconnect / dns-prefetch hints (issue #243). `metadata.preconnect` and
+  // `metadata.dnsPrefetch` each take a URL string, `{ url, crossorigin? }`, or
+  // an array of those. A preconnect warms DNS + TLS + TCP; dns-prefetch only
+  // resolves DNS (no crossorigin). The framework ALSO auto-emits ONE preconnect
+  // to the resolved vendor CDN origin for an unpinned cross-origin app, so the
+  // browser warms that connection before the importmap resolves. The author's
+  // declared origins are tracked so the auto one is not a duplicate.
+  /** @type {Set<string>} the origins the author already declared a preconnect to */
+  const declaredPreconnectOrigins = new Set();
+  /** @param {unknown} hint @returns {{ url: string, crossorigin?: string|boolean } | null} */
+  const normalizeHint = (hint) => {
+    if (typeof hint === 'string') return hint ? { url: hint } : null;
+    if (hint && typeof hint === 'object' && typeof (/** @type {any} */ (hint).url) === 'string') {
+      return /** @type {any} */ (hint);
+    }
+    return null;
+  };
+  /** @param {unknown} value @returns {Array<{ url: string, crossorigin?: string|boolean }>} */
+  const toHints = (value) => {
+    if (value == null) return [];
+    const list = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const h of list) {
+      const n = normalizeHint(h);
+      if (n) out.push(n);
+    }
+    return out;
+  };
+  /** @param {string|boolean|undefined} co @returns {string} */
+  const crossoriginAttr = (co) => {
+    if (co === undefined || co === false) return '';
+    if (co === true || co === '') return ' crossorigin';
+    return ` crossorigin="${escapeAttr(String(co))}"`;
+  };
+  for (const h of toHints(m.preconnect)) {
+    try { declaredPreconnectOrigins.add(new URL(h.url).origin); } catch { /* relative / opaque; track by raw href instead */ declaredPreconnectOrigins.add(h.url); }
+    linkTags.push(`<link rel="preconnect" href="${escapeAttr(h.url)}"${crossoriginAttr(h.crossorigin)}>`);
+  }
+  for (const h of toHints(m.dnsPrefetch)) {
+    // dns-prefetch never carries crossorigin (it only resolves DNS).
+    linkTags.push(`<link rel="dns-prefetch" href="${escapeAttr(h.url)}">`);
+  }
+  // Auto vendor preconnect: warm the cross-origin vendor CDN connection for an
+  // unpinned app. Deduped against an author-declared preconnect to the same
+  // origin; emits none for a same-origin pinned app or one with no cross-origin
+  // vendors (vendorPreconnectOrigins returns []). crossorigin is required (the
+  // importmap fetches the module as a CORS request).
+  for (const origin of vendorPreconnectOrigins()) {
+    if (declaredPreconnectOrigins.has(origin)) continue;
+    linkTags.push(`<link rel="preconnect" href="${escapeAttr(origin)}" crossorigin>`);
+  }
+
   // icons: { icon, apple, shortcut, other }. Each entry can be a string
   // (URL), an object { url, sizes?, type? }, or an array of those.
   //   - icon    → <link rel="icon">