@webjsdev/server 0.8.13 → 0.8.15

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/check.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Type overlay for `@webjsdev/server/check` (the convention validator backing
+ * `webjs check`, exported on its own subpath so the CLI can load it without
+ * booting the full server).
+ *
+ * The runtime is packages/server/src/check.js (JSDoc-annotated JavaScript);
+ * this overlay exists so a TypeScript consumer's `import { checkConventions }
+ * from '@webjsdev/server/check'` resolves precise types instead of emitting
+ * TS7016. Zero runtime cost.
+ */
+
+/** A single convention violation reported by `checkConventions`. */
+export interface Violation {
+  /** The rule name that fired (e.g. `no-browser-globals-in-render`). */
+  rule: string;
+  /** The offending file path. */
+  file: string;
+  /** What is wrong. */
+  message: string;
+  /** How to fix it. */
+  fix: string;
+}
+
+/** A rule's name + human description, for help text / docs. */
+export interface RuleDescriptor {
+  name: string;
+  description: string;
+}
+
+/** All available correctness rules with descriptions. */
+export declare const RULES: RuleDescriptor[];
+
+/**
+ * Run every correctness check against an app directory, returning the list of
+ * violations (empty when the app is clean). Correctness-only; report-only, no
+ * autofix.
+ */
+export declare function checkConventions(appDir: string): Promise<Violation[]>;

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',
     },
   });