@webjsdev/server 0.8.12 → 0.8.14

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/sitemap.js

@@ -0,0 +1,161 @@
+/**
+ * Sitemap helpers (issue #276). Two pure functions that turn an array of
+ * entries into spec-valid XML, so an author of `app/sitemap.{js,ts}` does not
+ * hand-roll the `<urlset>` string (escaping URLs, formatting lastmod dates) and
+ * has a built-in path to shard a large site via a `<sitemapindex>`.
+ *
+ * Both are OPTIONAL and tiny. The dev server serves a STRING returned from a
+ * `sitemap.{js,ts}` default export as `application/xml`, so the author returns
+ * `sitemap([...])` from that function. They can still return a raw Response or a
+ * hand-built string, so this is thin XML serialization, not a sitemap framework.
+ *
+ * Reference: the sitemaps.org 0.9 protocol; Next.js `sitemap.ts` (a typed array
+ * serialized to XML) and `generateSitemaps()` (the index for sharding).
+ */
+
+/** Per-URL entry for {@link sitemap}.
+ * @typedef {object} SitemapEntry
+ * @property {string} url Absolute URL (REQUIRED). XML-escaped on emit.
+ * @property {string|Date} [lastModified] Last-modified time, formatted as W3C
+ *   datetime (ISO 8601). A Date is `toISOString()`'d; a string passes through.
+ * @property {'always'|'hourly'|'daily'|'weekly'|'monthly'|'yearly'|'never'} [changeFrequency]
+ *   How often the page changes. An invalid value is dropped (not emitted).
+ * @property {number} [priority] Priority 0.0..1.0. Out-of-range / non-numeric
+ *   is dropped.
+ */
+
+/** Child-sitemap entry for {@link sitemapIndex}.
+ * @typedef {object} SitemapIndexEntry
+ * @property {string} url Absolute URL of a child sitemap (REQUIRED).
+ * @property {string|Date} [lastModified] Last-modified time (W3C datetime).
+ */
+
+const VALID_CHANGEFREQ = new Set([
+  'always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never',
+]);
+
+const MAX_URLS = 50000;
+
+/**
+ * XML-escape text destined for an element body. This is the security-critical
+ * part: a url derived from author data or a DB can contain `&` or `<`, which
+ * would break the XML document or allow injection if emitted raw. The five
+ * predefined XML entities are replaced (`&` first, so the entities the other
+ * replacements introduce are not double-escaped).
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeXml(value) {
+  return String(value)
+    // Strip the C0 control characters XML 1.0 forbids (everything below 0x20
+    // except tab, newline, and carriage return). A stray one from a corrupt
+    // DB-derived URL would otherwise make the WHOLE sitemap document invalid
+    // and silently rejected by search engines, the exact failure this helper
+    // exists to prevent. Done before entity-escaping so it cannot interfere.
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Format a `lastModified` value as a W3C datetime (ISO 8601) string. A Date
+ * becomes its `toISOString()`; a non-empty string passes through verbatim (the
+ * spec accepts both `YYYY-MM-DD` and a full timestamp). Anything else yields
+ * null so the `<lastmod>` element is omitted rather than emitted broken.
+ * @param {string|Date|undefined} value
+ * @returns {string|null}
+ */
+function formatLastmod(value) {
+  if (value instanceof Date) {
+    const ms = value.getTime();
+    if (Number.isNaN(ms)) return null;
+    return value.toISOString();
+  }
+  if (typeof value === 'string' && value.trim() !== '') return value.trim();
+  return null;
+}
+
+/**
+ * Validate + format a `priority` to one decimal in the 0.0..1.0 range. Returns
+ * null (so the element is dropped) for a non-number or an out-of-range value.
+ * @param {number|undefined} value
+ * @returns {string|null}
+ */
+function formatPriority(value) {
+  if (typeof value !== 'number' || Number.isNaN(value)) return null;
+  if (value < 0 || value > 1) return null;
+  return value.toFixed(1);
+}
+
+/**
+ * Serialize an array of {@link SitemapEntry} into a complete `<urlset>` XML
+ * document. Element order per the protocol is loc, lastmod, changefreq,
+ * priority. A malformed entry (missing / non-string / empty `url`) is skipped so
+ * it cannot produce broken XML. Output is deterministic.
+ * @param {SitemapEntry[]} entries
+ * @returns {string} a `<?xml ?>` + `<urlset>` document
+ */
+export function sitemap(entries) {
+  const list = Array.isArray(entries) ? entries : [];
+  if (list.length > MAX_URLS) {
+    console.warn(
+      `[webjs] sitemap() received ${list.length} URLs, over the ${MAX_URLS} per-file limit. ` +
+      'Shard the site with sitemapIndex() instead. Emitting all URLs anyway.'
+    );
+  }
+  const urls = [];
+  for (const entry of list) {
+    if (!entry || typeof entry.url !== 'string' || entry.url.trim() === '') {
+      console.warn('[webjs] sitemap(): skipping an entry with a missing or invalid url');
+      continue;
+    }
+    const parts = [`    <loc>${escapeXml(entry.url.trim())}</loc>`];
+    const lastmod = formatLastmod(entry.lastModified);
+    if (lastmod !== null) parts.push(`    <lastmod>${escapeXml(lastmod)}</lastmod>`);
+    if (typeof entry.changeFrequency === 'string' && VALID_CHANGEFREQ.has(entry.changeFrequency)) {
+      parts.push(`    <changefreq>${entry.changeFrequency}</changefreq>`);
+    }
+    const priority = formatPriority(entry.priority);
+    if (priority !== null) parts.push(`    <priority>${priority}</priority>`);
+    urls.push(`  <url>\n${parts.join('\n')}\n  </url>`);
+  }
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+    (urls.length ? urls.join('\n') + '\n' : '') +
+    '</urlset>\n'
+  );
+}
+
+/**
+ * Serialize an array of {@link SitemapIndexEntry} into a `<sitemapindex>` XML
+ * document, one `<sitemap>` per child sitemap URL. Same escaping + lastmod rules
+ * and same skip-malformed-entry behavior as {@link sitemap}. Use it from the
+ * root `app/sitemap.{js,ts}` to point at sharded child sitemaps served by
+ * `route.{js,ts}` handlers.
+ * @param {SitemapIndexEntry[]} sitemaps
+ * @returns {string} a `<?xml ?>` + `<sitemapindex>` document
+ */
+export function sitemapIndex(sitemaps) {
+  const list = Array.isArray(sitemaps) ? sitemaps : [];
+  const items = [];
+  for (const entry of list) {
+    if (!entry || typeof entry.url !== 'string' || entry.url.trim() === '') {
+      console.warn('[webjs] sitemapIndex(): skipping an entry with a missing or invalid url');
+      continue;
+    }
+    const parts = [`    <loc>${escapeXml(entry.url.trim())}</loc>`];
+    const lastmod = formatLastmod(entry.lastModified);
+    if (lastmod !== null) parts.push(`    <lastmod>${escapeXml(lastmod)}</lastmod>`);
+    items.push(`  <sitemap>\n${parts.join('\n')}\n  </sitemap>`);
+  }
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+    (items.length ? items.join('\n') + '\n' : '') +
+    '</sitemapindex>\n'
+  );
+}

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">