@timber-js/app 0.2.0-alpha.145 → 0.2.0-alpha.147

package/dist/index.js

@@ -1,17 +1,17 @@
 import { n as setViteServer } from "./_chunks/warnings-CNPXaypM.js";
 import { a as isDynamicMetadataExtension, o as isMetadataRouteServePath } from "./_chunks/metadata-routes-BjepjefT.js";
 import { h as swallow } from "./_chunks/logger-Dt-jQaBO.js";
-import { c as loadTimberConfigFile, d as resolveBuildDir, f as resolveClientJavascript, l as mergeFileConfig, m as scanRoutes, o as DEFAULT_BUILD_DIR, p as createNoopTimer, s as createPluginContext, u as resolveAppDir } from "./_chunks/cli-schema-sync-D2IpXicg.js";
-import { a as generateRouteMap, i as collectInterceptionRewrites, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "./_chunks/walkers-7FBPM-hX.js";
+import { c as loadTimberConfigFile, d as resolveBuildDir, f as resolveClientJavascript, l as mergeFileConfig, m as scanRoutes, o as DEFAULT_BUILD_DIR, p as createNoopTimer, s as createPluginContext, u as resolveAppDir } from "./_chunks/cli-schema-sync-CQaxupHv.js";
+import { a as generateRouteMap, i as collectInterceptionRewrites, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "./_chunks/walkers-Ck4Y45XN.js";
 import { t as fnv1aHash } from "./_chunks/fast-hash-D6hIVt1Y.js";
 import { t as formatSize } from "./_chunks/format-CfwjgPz9.js";
 import { basename, dirname, extname, join, normalize, relative, resolve } from "node:path";
-import { createRequire } from "node:module";
+import { builtinModules, createRequire } from "node:module";
 import react, { reactCompilerPreset } from "@vitejs/plugin-react";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { constants, createGzip, gzipSync } from "node:zlib";
-import { Readable } from "node:stream";
+import { Readable, pipeline } from "node:stream";
 import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import { parseAst } from "vite";
@@ -42,10 +42,6 @@ var __copyProps = (to, from, except, desc) => {
 	return to;
 };
 var __toCommonJS = (mod) => __hasOwnProp.call(mod, "module.exports") ? mod["module.exports"] : __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
-	if (typeof require !== "undefined") return require.apply(this, arguments);
-	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
-});
 //#endregion
 //#region src/plugins/content.ts
 var CONFIG_FILE_NAMES$1 = [
@@ -592,6 +588,211 @@ function escapeHtml(str) {
 	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 //#endregion
+//#region src/dev-tools/dev-page-shell.ts
+/**
+* Shared scaffold for dev-mode HTML pages (dev error page, dev 404 page).
+*
+* Both pages are self-contained HTML documents served when the normal
+* render pipeline can't produce a page. They share:
+* - The document scaffold (head, container, footer)
+* - Base CSS (layout, light/dark variables, common components)
+* - The HMR auto-reload script that watches Vite's WebSocket and reloads
+*   when the developer fixes the error / adds the missing route
+*
+* Dev-only: this module is only imported by dev-mode code paths. It is
+* never included in production builds.
+*
+* Design doc: 21-dev-server.md §"Error Overlay", §"Dev 404 Page"
+*/
+/**
+* Extract HMR connection options from a Vite resolved config.
+* Used by the dev server to pass HMR config to the dev page generators
+* so the auto-reload WebSocket connects to the correct endpoint.
+*/
+function extractHmrOptions(config) {
+	const hmr = config.server?.hmr;
+	if (hmr === false) return void 0;
+	const hmrOpts = typeof hmr === "object" ? hmr : {};
+	const opts = {
+		protocol: hmrOpts.protocol,
+		host: hmrOpts.host,
+		port: hmrOpts.port,
+		path: hmrOpts.path,
+		token: config.webSocketToken
+	};
+	if (!opts.protocol && !opts.host && !opts.port && !opts.path && !opts.token) return;
+	return opts;
+}
+/**
+* Build the inline auto-reload script for dev pages.
+*
+* The page is static HTML, not a Vite-managed module, so the normal HMR
+* update flow can't reach it. Instead we connect to Vite's HMR WebSocket
+* directly and reload on any update event.
+*
+* URL construction mirrors Vite's own client.mjs: explicitly configured
+* values win, and the browser's location fills any gaps at runtime. This
+* matters because Vite 8 requires a `?token=` on browser WS upgrades in
+* every config — a config with only a token still needs the host and port
+* from `location` (TIM-1067).
+*/
+function buildReloadScript(hmrOptions) {
+	return `    (function() {
+      try {
+        var o = ${JSON.stringify(hmrOptions ?? {}).replace(/</g, "\\u003c")};
+        var protocol = o.protocol || (location.protocol === 'https:' ? 'wss' : 'ws');
+        var host = o.host || location.hostname;
+        var port = o.port || location.port;
+        var url = protocol + '://' + host + (port ? ':' + port : '') + (o.path || '')
+          + (o.token ? '?token=' + encodeURIComponent(o.token) : '');
+        var ws = new WebSocket(url, 'vite-hmr');
+        ws.addEventListener('message', function(e) {
+          try {
+            var data = JSON.parse(e.data);
+            if (data.type === 'full-reload' || data.type === 'update') {
+              location.reload();
+            }
+          } catch (ex) {}
+        });
+      } catch (ex) {}
+    })();`;
+}
+/**
+* Render a self-contained dev page: scaffold + shared CSS + footer +
+* HMR auto-reload script.
+*/
+function renderDevPageShell(opts) {
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(opts.title)}</title>
+  <style>${SHARED_CSS}${opts.extraCss ?? ""}</style>
+</head>
+<body>
+  <div class="container">
+    ${opts.bodyHtml}
+
+    <footer class="footer">
+      <span class="timber-logo">🪵 timber.js</span>
+      <span class="footer-hint">${opts.footerHint}</span>
+    </footer>
+  </div>
+
+  <script>
+${opts.extraScript ?? ""}
+    // Auto-reload when Vite HMR signals an update (file fixed, route added).
+${buildReloadScript(opts.hmrOptions)}
+  <\/script>
+</body>
+</html>`;
+}
+/**
+* Base CSS shared by all dev pages. Pages override the --badge-* variables
+* (and add their own component styles) via `extraCss`.
+*/
+var SHARED_CSS = `
+  :root {
+    --bg: #fff;
+    --fg: #1a1a1a;
+    --fg-dim: #6b7280;
+    --border: #e5e7eb;
+    --source-bg: #fafafa;
+    --link: #2563eb;
+    --code-bg: #f3f4f6;
+    --btn-bg: #f3f4f6;
+    --btn-fg: #374151;
+    --btn-border: #d1d5db;
+    --code-font: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0a0a0a;
+      --fg: #f5f5f5;
+      --fg-dim: #9ca3af;
+      --border: #27272a;
+      --source-bg: #18181b;
+      --link: #60a5fa;
+      --code-bg: #27272a;
+      --btn-bg: #27272a;
+      --btn-fg: #e5e7eb;
+      --btn-border: #3f3f46;
+    }
+  }
+
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    background: var(--bg);
+    color: var(--fg);
+    line-height: 1.6;
+    padding: 2rem;
+  }
+
+  .container { max-width: 56rem; margin: 0 auto; }
+  .header { margin-bottom: 1.5rem; }
+
+  .badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.25rem 0.625rem;
+    border-radius: 0.375rem;
+    background: var(--badge-bg);
+    color: var(--badge-fg);
+    border: 1px solid var(--badge-border);
+    margin-bottom: 0.75rem;
+  }
+
+  .message {
+    font-size: 1.375rem;
+    font-weight: 600;
+    line-height: 1.3;
+    word-break: break-word;
+  }
+
+  .hint {
+    margin-top: 0.5rem;
+    color: var(--fg-dim);
+    font-size: 0.875rem;
+  }
+
+  .section {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .section-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.5rem 0.75rem;
+    background: var(--source-bg);
+    border-bottom: 1px solid var(--border);
+    color: var(--fg-dim);
+  }
+
+  .footer {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--border);
+    font-size: 0.75rem;
+    color: var(--fg-dim);
+  }
+
+  .timber-logo { font-weight: 600; white-space: nowrap; }
+`;
+//#endregion
 //#region src/dev-tools/error-page.ts
 /**
 * Dev error page — self-contained HTML error page for dev server 500s.
@@ -603,8 +804,9 @@ function escapeHtml(str) {
 * This is NOT a replacement for Vite's error overlay — it's the fallback
 * for when the overlay's transport (WebSocket) isn't available yet.
 *
-* Dev-only: this module is only imported by dev-server.ts (apply: 'serve').
-* It is never included in production builds.
+* Dev-only: this module is only imported by dev-server.ts (apply: 'serve')
+* and via dynamic import from fallback-error.ts in dev mode. It is never
+* included in production builds.
 *
 * Design doc: 21-dev-server.md §"Error Overlay"
 */
@@ -627,10 +829,13 @@ var PHASE_HINTS = {
 /**
 * Try to read a few lines of source code around the error location.
 * Returns null if the file can't be read (e.g., virtual modules).
+*
+* Uses a top-level `node:fs` import — this module is dev-server-only and
+* Node-only. A bare `require()` here would throw in the ESM build and the
+* code frame would silently never render (TIM-1067, B48).
 */
 function readSourceContext(filePath, line, contextLines = 3) {
 	try {
-		const { readFileSync } = __require("node:fs");
 		const allLines = readFileSync(filePath, "utf-8").split("\n");
 		const start = Math.max(0, line - 1 - contextLines);
 		const end = Math.min(allLines.length, line + contextLines);
@@ -653,8 +858,9 @@ var esc = escapeHtml;
 *
 * `JSON.stringify` does not escape `<\/script>`, so error text containing
 * that sequence breaks out of the script block — an XSS vector.
-* We replace all `<` with `\u003c` which is valid in JSON strings and
-* prevents the HTML parser from seeing a closing `<\/script>` tag.
+* We replace all `<` with the equivalent unicode escape, which is valid in
+* JSON strings and prevents the HTML parser from seeing a closing
+* `<\/script>` tag.
 *
 * Security: TIM-788
 */
@@ -662,32 +868,6 @@ function escJsonForScript(json) {
 	return json.replace(/</g, "\\u003c");
 }
 /**
-* Build a WebSocket URL from Vite HMR options.
-* Mirrors the logic in Vite's client.mjs for constructing the WS connection URL.
-*/
-function buildWsUrl(opts) {
-	return `${opts.protocol ?? "ws"}://${opts.host ?? "localhost"}${opts.port ? `:${opts.port}` : ""}${opts.path ?? ""}${opts.token ? `?token=${opts.token}` : ""}`;
-}
-/**
-* Extract HMR connection options from a Vite resolved config.
-* Used by the dev server to pass HMR config to the error page generator
-* so the auto-reload WebSocket connects to the correct endpoint.
-*/
-function extractHmrOptions(config) {
-	const hmr = config.server?.hmr;
-	if (hmr === false) return void 0;
-	const hmrOpts = typeof hmr === "object" ? hmr : {};
-	const opts = {
-		protocol: hmrOpts.protocol,
-		host: hmrOpts.host,
-		port: hmrOpts.port,
-		path: hmrOpts.path,
-		token: config.webSocketToken
-	};
-	if (!opts.protocol && !opts.host && !opts.port && !opts.path && !opts.token) return;
-	return opts;
-}
-/**
 * Generate a self-contained HTML error page for dev server 500 responses.
 *
 * The page includes:
@@ -711,17 +891,7 @@ function generateDevErrorPage(error, phase, projectRoot, hmrOptions) {
 	let sourceContext = null;
 	if (loc) sourceContext = readSourceContext(loc.file, loc.line);
 	const relPath = loc?.file.startsWith(projectRoot) ? loc.file.slice(projectRoot.length + 1) : loc?.file;
-	return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Error — ${esc(phaseLabel)} | timber.js</title>
-  <style>${CSS}</style>
-</head>
-<body>
-  <div class="container">
-    <header class="header">
+	const bodyHtml = `<header class="header">
       <div class="badge">${esc(phaseLabel)} Error</div>
       <h1 class="message">${esc(message)}</h1>
       ${phaseHint ? `<p class="hint">${esc(phaseHint)}</p>` : ""}
@@ -730,7 +900,7 @@ function generateDevErrorPage(error, phase, projectRoot, hmrOptions) {
     ${relPath ? `<div class="location">${esc(relPath)}${loc ? `:${loc.line}:${loc.column}` : ""}</div>` : ""}
 
     ${sourceContext ? `<div class="source-context">
-        <div class="source-header">Source</div>
+        <div class="section-header">Source</div>
         <pre class="source-code"><code>${sourceContext.lines.map((l) => `<span class="source-line${l.highlight ? " source-line-highlight" : ""}"><span class="line-num">${l.num}</span>${esc(l.text)}</span>`).join("\n")}</code></pre>
       </div>` : ""}
 
@@ -751,130 +921,45 @@ function generateDevErrorPage(error, phase, projectRoot, hmrOptions) {
 
     <div class="actions">
       <button class="btn" onclick="copyError()">Copy Error</button>
-    </div>
-
-    <footer class="footer">
-      <span class="timber-logo">🪵 timber.js</span>
-      <span class="footer-hint">Fix the error and save — the page will reload automatically via HMR.</span>
-    </footer>
-  </div>
-
-  <script>
-    function copyError() {
+    </div>`;
+	const copyScript = `    function copyError() {
       var text = ${escJsonForScript(JSON.stringify(`${phaseLabel} Error: ${message}\n\n` + (relPath ? `File: ${relPath}${loc ? `:${loc.line}:${loc.column}` : ""}\n\n` : "") + (componentStack ? `Component Stack:\n${componentStack.trim()}\n\n` : "") + `Stack Trace:\n${error.stack ?? ""}`))};
       navigator.clipboard.writeText(text).then(function() {
         var btn = document.querySelector('.btn');
         if (btn) { btn.textContent = 'Copied!'; setTimeout(function() { btn.textContent = 'Copy Error'; }, 1500); }
       });
     }
-
-    // Auto-reload when Vite HMR reconnects.
-    // When the developer fixes the error and saves, Vite's module graph
-    // invalidates. We can't rely on the normal HMR update flow (the page
-    // is a static error page, not a Vite-managed module), so we connect
-    // to Vite's WebSocket and reload on any update event.
-    (function() {
-      try {
-        var wsUrl = ${hmrOptions ? escJsonForScript(JSON.stringify(buildWsUrl(hmrOptions))) : "'ws://' + location.host"};
-        var ws = new WebSocket(wsUrl, 'vite-hmr');
-        ws.addEventListener('message', function(e) {
-          try {
-            var data = JSON.parse(e.data);
-            if (data.type === 'full-reload' || data.type === 'update' || data.type === 'connected') {
-              if (data.type !== 'connected') location.reload();
-            }
-          } catch(ex) {}
-        });
-      } catch(ex) {}
-    })();
-  <\/script>
-</body>
-</html>`;
+`;
+	return renderDevPageShell({
+		title: `Error — ${phaseLabel} | timber.js`,
+		extraCss: ERROR_CSS,
+		bodyHtml,
+		footerHint: "Fix the error and save — the page will reload automatically via HMR.",
+		extraScript: copyScript,
+		hmrOptions
+	});
 }
-var CSS = `
+var ERROR_CSS = `
   :root {
-    --bg: #fff;
-    --fg: #1a1a1a;
-    --fg-dim: #6b7280;
-    --border: #e5e7eb;
     --badge-bg: #fef2f2;
     --badge-fg: #991b1b;
     --badge-border: #fecaca;
-    --source-bg: #fafafa;
     --highlight-bg: #fef2f2;
     --highlight-border: #ef4444;
     --line-num: #9ca3af;
-    --btn-bg: #f3f4f6;
-    --btn-fg: #374151;
-    --btn-border: #d1d5db;
-    --link: #2563eb;
-    --code-font: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
   }
 
   @media (prefers-color-scheme: dark) {
     :root {
-      --bg: #0a0a0a;
-      --fg: #f5f5f5;
-      --fg-dim: #9ca3af;
-      --border: #27272a;
       --badge-bg: #450a0a;
       --badge-fg: #fca5a5;
       --badge-border: #7f1d1d;
-      --source-bg: #18181b;
       --highlight-bg: #450a0a;
       --highlight-border: #dc2626;
       --line-num: #6b7280;
-      --btn-bg: #27272a;
-      --btn-fg: #e5e7eb;
-      --btn-border: #3f3f46;
-      --link: #60a5fa;
     }
   }
 
-  * { margin: 0; padding: 0; box-sizing: border-box; }
-
-  body {
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
-    background: var(--bg);
-    color: var(--fg);
-    line-height: 1.6;
-    padding: 2rem;
-  }
-
-  .container {
-    max-width: 56rem;
-    margin: 0 auto;
-  }
-
-  .header { margin-bottom: 1.5rem; }
-
-  .badge {
-    display: inline-block;
-    font-size: 0.75rem;
-    font-weight: 600;
-    text-transform: uppercase;
-    letter-spacing: 0.05em;
-    padding: 0.25rem 0.625rem;
-    border-radius: 0.375rem;
-    background: var(--badge-bg);
-    color: var(--badge-fg);
-    border: 1px solid var(--badge-border);
-    margin-bottom: 0.75rem;
-  }
-
-  .message {
-    font-size: 1.375rem;
-    font-weight: 600;
-    line-height: 1.3;
-    word-break: break-word;
-  }
-
-  .hint {
-    margin-top: 0.5rem;
-    color: var(--fg-dim);
-    font-size: 0.875rem;
-  }
-
   .location {
     font-family: var(--code-font);
     font-size: 0.8125rem;
@@ -893,17 +978,6 @@ var CSS = `
     overflow: hidden;
   }
 
-  .source-header, .section-header {
-    font-size: 0.75rem;
-    font-weight: 600;
-    text-transform: uppercase;
-    letter-spacing: 0.05em;
-    padding: 0.5rem 0.75rem;
-    background: var(--source-bg);
-    border-bottom: 1px solid var(--border);
-    color: var(--fg-dim);
-  }
-
   .source-code {
     overflow-x: auto;
     font-family: var(--code-font);
@@ -937,13 +1011,6 @@ var CSS = `
     user-select: none;
   }
 
-  .section {
-    margin-bottom: 1rem;
-    border: 1px solid var(--border);
-    border-radius: 0.5rem;
-    overflow: hidden;
-  }
-
   .clickable { cursor: pointer; }
   .clickable:hover { background: var(--btn-bg); }
 
@@ -977,21 +1044,6 @@ var CSS = `
   }
 
   .btn:hover { opacity: 0.85; }
-
-  .footer {
-    display: flex;
-    align-items: center;
-    gap: 0.75rem;
-    padding-top: 1rem;
-    border-top: 1px solid var(--border);
-    font-size: 0.75rem;
-    color: var(--fg-dim);
-  }
-
-  .timber-logo {
-    font-weight: 600;
-    white-space: nowrap;
-  }
 `;
 //#endregion
 //#region src/config-validation.ts
@@ -1331,7 +1383,7 @@ function compressResponse(request, response) {
 */
 function compressWithGzip(body) {
 	const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
-	Readable.fromWeb(body).pipe(gzip);
+	pipeline(Readable.fromWeb(body), gzip, () => {});
 	return Readable.toWeb(gzip);
 }
 //#endregion
@@ -1434,9 +1486,12 @@ function createTimberMiddleware(server, projectRoot) {
 			const rscModule = await rscEnv.runner.import(RSC_ENTRY_ID);
 			handler = rscModule.default;
 			const config = rscModule.pipelineConfig;
-			if (config) config.devPipelineErrorHandler = (error, _phase, debugComponents) => {
-				sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot, debugComponents);
-			};
+			if (config) {
+				config.devPipelineErrorHandler = (error, _phase, debugComponents) => {
+					sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot, debugComponents);
+				};
+				config.devHmrOptions = hmrOptions;
+			}
 			const setSourceMap = rscModule.setDevSourceMapHandler;
 			if (typeof setSourceMap === "function") setSourceMap((error) => {
 				fixErrorStacktrace(server, error);
@@ -1506,15 +1561,27 @@ function addTimberContext(error) {
 *
 * Constructs the full URL from the Host header and request URL,
 * and forwards the method, headers, and body.
+*
+* The scheme comes from the socket's TLS state — with `server.https` the
+* browser sends `Origin: https://host`, and a hardcoded `http://` would
+* fail CSRF origin comparison on every POST. X-Forwarded-Proto is NOT
+* consulted: dev connections are direct, so the header would be
+* attacker-controlled. (TIM-1067, B32)
+*
+* Exported for tests.
 */
 function toWebRequest(nodeReq) {
-	const url = `http://${nodeReq.headers.host ?? "localhost"}${nodeReq.url}`;
+	const protocol = nodeReq.socket?.encrypted ? "https" : "http";
+	const host = nodeReq.headers.host ?? nodeReq.headers[":authority"] ?? "localhost";
+	const url = `${protocol}://${host}${nodeReq.url}`;
 	const headers = new Headers();
 	for (const [key, value] of Object.entries(nodeReq.headers)) {
 		if (value === void 0) continue;
+		if (key.startsWith(":")) continue;
 		if (Array.isArray(value)) for (const v of value) headers.append(key, v);
 		else headers.set(key, value);
 	}
+	if (!headers.has("host")) headers.set("host", host);
 	const method = nodeReq.method ?? "GET";
 	const hasBody = method !== "GET" && method !== "HEAD";
 	return new Request(url, {
@@ -2811,18 +2878,57 @@ var CLIENT_ONLY_VIRTUAL = "\0timber:client-only";
 *
 * Used by the catch-all resolveId rule to remap subpath imports to src/
 * in server environments. When adding a new subpath export to package.json,
-* add it here too. See TIM-568.
+* add it here too — tests/shims-drift.test.ts enumerates package.json
+* exports and fails if an entry is missing. See TIM-568.
+*
+* Exported for the drift test.
 */
 var SUBPATH_SRC_MAP = {
 	"cache": "cache/index.ts",
+	"codec": "codec.ts",
 	"cookies": "cookies/index.ts",
+	"params": "params/index.ts",
 	"search-params": "search-params/index.ts",
 	"segment-params": "segment-params/index.ts",
 	"adapters/cloudflare": "adapters/cloudflare.ts",
+	"adapters/cloudflare/cache": "adapters/cloudflare-kv-cache.ts",
 	"adapters/cloudflare/dev": "adapters/cloudflare-dev.ts",
 	"adapters/nitro": "adapters/nitro.ts"
 };
 /**
+* Runtime value exports of @timber-js/app/server, stubbed in the client
+* (browser) environment so a stray client-side import fails with a clear
+* call-time error instead of a confusing bundler error.
+*
+* Must stay in sync with the actual runtime exports of server/index.ts —
+* tests/shims-drift.test.ts compares this list against
+* Object.keys(import('../server/index.ts')) and fails on drift.
+* Type-only exports (DenyOptions, AccessContext, …) are erased at runtime
+* and must NOT appear here.
+*/
+var SERVER_STUB_EXPORTS = [
+	"getHeaders",
+	"getSegmentParams",
+	"getCookieJar",
+	"deny",
+	"redirect",
+	"redirectExternal",
+	"RedirectType",
+	"waitUntil",
+	"createActionClient",
+	"ActionError",
+	"validated",
+	"coerce",
+	"parseFormData",
+	"getFormFlash",
+	"revalidatePath",
+	"revalidateTag",
+	"getTraceId",
+	"getSpanId",
+	"withSpan",
+	"addSpanEvent"
+];
+/**
 * Map from next/* import specifiers to shim file paths.
 *
 * The shim map is a separate data structure (not embedded in the plugin)
@@ -2848,6 +2954,15 @@ function stripJsExtension(id) {
 	return id.endsWith(".js") ? id.slice(0, -3) : id;
 }
 /**
+* Read the Vite environment name from a plugin hook's `this` context.
+*
+* Duck-typed because the hook context type doesn't expose `environment`
+* in a way that survives our Plugin typing — see Vite's Environment API.
+*/
+function envName(hookCtx) {
+	return hookCtx.environment?.name;
+}
+/**
 * Create the timber-shims Vite plugin.
 *
 * Hooks: resolveId, load
@@ -2865,45 +2980,47 @@ function timberShims(_ctx) {
 		* 3. Check next/* shim map
 		* 4. Return null (pass through) for everything else
 		*
-		* All @timber-js/app/* subpath imports resolve to dist/ via package.json
-		* exports in all environments. This ensures a single module instance
-		* for each module — the dist/ chunks share code via rollup's code
-		* splitting. No src/ remapping is needed (see TIM-568).
+		* In server environments (RSC + SSR), @timber-js/app/* subpath imports
+		* are remapped to src/ via SUBPATH_SRC_MAP and the explicit branches
+		* below — dist/ chunks miss Vite's RSC transforms and would duplicate
+		* mutable module state (see TIM-568 and the rationale comments below).
 		*
-		* The only exception is @timber-js/app/server in the client (browser)
-		* environment, which returns a virtual stub — server code must never
-		* be bundled into the browser.
+		* In the client (browser) environment, imports resolve to dist/ via
+		* package.json exports — except @timber-js/app/client (remapped to src/
+		* to share module instances with browser-entry) and @timber-js/app/server,
+		* which returns a virtual stub: server code must never be bundled into
+		* the browser.
 		*/
 		resolveId(id) {
 			if (id === "server-only") return SERVER_ONLY_VIRTUAL;
 			if (id === "client-only") return CLIENT_ONLY_VIRTUAL;
 			const cleanId = stripJsExtension(id);
 			if (cleanId in SHIM_MAP) {
-				if (this.environment?.name === "client" && cleanId === "next/navigation") return resolve(SHIMS_DIR, "navigation-client.ts");
+				if (envName(this) === "client" && cleanId === "next/navigation") return resolve(SHIMS_DIR, "navigation-client.ts");
 				return SHIM_MAP[cleanId];
 			}
 			if (cleanId === "#server-internal") {
-				if (this.environment?.name === "client") return "\0timber:server-empty";
+				if (envName(this) === "client") return "\0timber:server-empty";
 				return resolve(PKG_ROOT, "src", "server", "internal.ts");
 			}
 			if (cleanId === "#client-internal") return resolve(PKG_ROOT, "src", "client", "internal.ts");
 			if (cleanId === "#routing") return resolve(PKG_ROOT, "src", "routing", "index.ts");
 			if (cleanId === "@timber-js/app/server/internal") {
-				if (this.environment?.name === "client") return "\0timber:server-empty";
+				if (envName(this) === "client") return "\0timber:server-empty";
 				return resolve(PKG_ROOT, "src", "server", "internal.ts");
 			}
 			if (cleanId === "@timber-js/app/client/internal") return resolve(PKG_ROOT, "src", "client", "internal.ts");
 			if (cleanId === "@timber-js/app/server") {
-				if (this.environment?.name === "client") return "\0timber:server-empty";
+				if (envName(this) === "client") return "\0timber:server-empty";
 				return resolve(PKG_ROOT, "src", "server", "index.ts");
 			}
 			if (cleanId === "@timber-js/app/client") {
-				const envName = this.environment?.name;
-				if (envName === "ssr" || envName === "client") return resolve(PKG_ROOT, "src", "client", "index.ts");
+				const env = envName(this);
+				if (env === "ssr" || env === "client") return resolve(PKG_ROOT, "src", "client", "index.ts");
 				return null;
 			}
 			if (cleanId.startsWith("@timber-js/app/") && cleanId !== "@timber-js/app/package.json") {
-				if (this.environment?.name !== "client") {
+				if (envName(this) !== "client") {
 					const srcPath = SUBPATH_SRC_MAP[cleanId.slice(15)];
 					if (srcPath) return resolve(PKG_ROOT, "src", srcPath);
 				}
@@ -2918,7 +3035,7 @@ function timberShims(_ctx) {
 		* clearly identifies the boundary violation.
 		*/
 		load(id) {
-			const isClient = this.environment?.name === "client";
+			const isClient = envName(this) === "client";
 			if (id === SERVER_ONLY_VIRTUAL) {
 				if (isClient) return `throw new Error(
   "This module cannot be imported from a Client Component module. " +
@@ -2938,34 +3055,7 @@ const msg = "[timber] @timber-js/app/server was imported from client code. " +
   "Server modules (headers, cookies, redirect, deny, etc.) cannot be used in client components. " +
   "If you need these APIs, move the import to a server component or middleware.";
 function stub() { throw new Error(msg); }
-export const headers = stub;
-export const cookies = stub;
-export const getHeaders = stub;
-export const getHeader = stub;
-export const getCookieJar = stub;
-export const getCookie = stub;
-export const getSearchParams = stub;
-export const getSegmentParams = stub;
-export const searchParams = stub;
-export const deny = stub;
-export const notFound = stub;
-export const redirect = stub;
-export const permanentRedirect = stub;
-export const redirectExternal = stub;
-export const waitUntil = stub;
-export const DenyOptions = {};
-export const RedirectType = {};
-export const DenySignal = stub;
-export const RedirectSignal = stub;
-export const createPipeline = stub;
-export const revalidatePath = stub;
-export const revalidateTag = stub;
-export const createActionClient = stub;
-export const ActionError = stub;
-export const validated = stub;
-export const getFormFlash = stub;
-export const parseFormData = stub;
-export const coerce = stub;
+${SERVER_STUB_EXPORTS.map((name) => name === "RedirectType" ? `export const RedirectType = { push: 'push', replace: 'replace' };` : `export const ${name} = stub;`).join("\n")}
 `;
 		}
 	};
@@ -6554,7 +6644,20 @@ function clientChunkGroup(meta, appDir, root) {
 }
 //#endregion
 //#region src/plugins/server-bundle.ts
+/**
+* timber-server-bundle — Bundle all dependencies for server environments.
+*
+* In production builds, sets `resolve.noExternal: true` for the rsc and ssr
+* environments. This ensures all npm dependencies are bundled into the output,
+* which is required for platforms like Cloudflare Workers that don't have
+* access to node_modules at runtime.
+*
+* In dev mode, Vite's default externalization is preserved for fast HMR.
+*
+* Design docs: design/11-platform.md, design/25-production-deployments.md
+*/
 var BUILD_ONLY_EXTERNALS = [
+	...builtinModules.flatMap((m) => [m, `node:${m}`]),
 	"nitro",
 	"rollup",
 	"@mdx-js/rollup",
@@ -6606,8 +6709,13 @@ function timberServerBundle() {
 				if (!code.includes(lazy)) return null;
 				const eager = [
 					"var __esmMin = (fn, res) => {",
-					"  var l = () => { if (fn) { var f = fn; try { res = f(); fn = 0; } catch(e) {} } return res; };",
+					"  var eager = 1;",
+					"  var l = () => {",
+					"    if (fn) { if (eager) { try { res = fn(); fn = 0; } catch(e) {} } else { res = fn(fn = 0); } }",
+					"    return res;",
+					"  };",
 					"  l();",
+					"  eager = 0;",
 					"  return l;",
 					"};"
 				].join(" ");
@@ -6647,9 +6755,36 @@ function timberServerBundle() {
 * The plugin transforms:
 *   cache(fn, opts)  →  cache(fn, opts, "stable-id")
 *
-* where stable-id = fnv1a(relativeModulePath + ":cache:" + callIndex).
-*
-* See TIM-997, design/06-caching.md §"Cache Key Security".
+* where stable-id =
+*   fnv1a(relPath + ":cache:" + fnv1a(stmtText) + ":" + fnv1a(callSpanText) + ":" + occurrence)
+*
+* stmtText is the source text of the enclosing *top-level statement* and
+* callSpanText is the source text of the cache(...) call expression itself.
+*
+* The ID is derived from the *content* of the call, not its ordinal position
+* in the file. A position-based index (the original TIM-997 scheme) was stable
+* within one build but shifted across builds: inserting, deleting, or
+* reordering a cache() call changed the index of every call below it, so with
+* a persistent shared CacheHandler (Redis/KV) a new function could inherit
+* another function's old ID and serve its persisted data — cross-deploy cache
+* poisoning (TIM-1053). Content hashing makes IDs immune to reordering and
+* unrelated edits, while a changed call gets a fresh ID — which is exactly
+* when invalidation is wanted.
+*
+* The enclosing-statement text is included so that byte-identical cache()
+* calls in different scopes — e.g. two factory helpers that each `return
+* cache(fn, { ttl: 60 })` — get distinct, insertion-stable IDs: their
+* enclosing declarations differ by name/body even when the call spans are
+* identical. Without it, a source-order occurrence counter alone would shift
+* when an identical span is inserted above, reassigning IDs across deploys.
+* Calls that are byte-identical INCLUDING their enclosing top-level statement
+* are disambiguated by a source-order occurrence index. That residue is safe:
+* identical top-level declarations are a redeclaration error, so fully
+* identical (statement, call) pairs can only be expression statements
+* referencing the same bindings — the same function, where an ID swap is
+* harmless.
+*
+* See TIM-997, TIM-1053, design/06-caching.md §"Cache Key Security".
 */
 var CACHE_MODULE_SOURCES = new Set(["@timber-js/app/cache", "timber/cache"]);
 /**
@@ -6690,16 +6825,23 @@ function findCacheCallSites(node, cacheBindings, results) {
 	}
 }
 /**
-* Generate a stable callsite ID from a module path and call index.
+* Generate a stable callsite ID from a module path, the source text of the
+* enclosing top-level statement, the source text of the cache(...) call
+* expression, and an occurrence index among fully byte-identical
+* (statement, call) pairs in the same file.
 *
-* The ID is an FNV-1a hash of the relative module path + call index,
-* providing a deterministic identifier that is:
-* - Stable across cold starts of the same build
-* - Unique across different modules
-* - Unique across multiple cache() calls within the same module
+* The ID is deterministic and:
+* - Stable across cold starts AND across builds/deploys for unchanged calls —
+*   inserting, deleting, or reordering other cache() calls does not affect it
+* - Unique across different modules (relPath component)
+* - Unique across distinct cache() calls within a module (statement + span
+*   hashes), with fully identical duplicates disambiguated by source-order
+*   occurrence
+* - Fresh when the wrapped fn, opts, or enclosing statement change, which
+*   intentionally invalidates the old persisted entries
 */
-function generateStableId(relativeModulePath, callIndex) {
-	return fnv1aHash(`${relativeModulePath}:cache:${callIndex}`);
+function generateStableId(relativeModulePath, statementText, callSpanText, occurrence) {
+	return fnv1aHash(`${relativeModulePath}:cache:${fnv1aHash(statementText)}:${fnv1aHash(callSpanText)}:${occurrence}`);
 }
 function timberCacheTransform(ctx) {
 	return {
@@ -6716,16 +6858,28 @@ function timberCacheTransform(ctx) {
 			const cacheBindings = findCacheBindings(program);
 			if (cacheBindings.size === 0) return;
 			const callSites = [];
-			findCacheCallSites(program, cacheBindings, callSites);
+			for (const stmt of program.body) {
+				const calls = [];
+				findCacheCallSites(stmt, cacheBindings, calls);
+				for (const call of calls) callSites.push({
+					call,
+					stmt
+				});
+			}
 			if (callSites.length === 0) return;
-			callSites.sort((a, b) => a.start - b.start);
+			callSites.sort((a, b) => a.call.start - b.call.start);
 			const relPath = relative(ctx.root || process.cwd(), id);
 			const s = new MagicString(code);
-			for (let i = 0; i < callSites.length; i++) {
-				const call = callSites[i];
-				const stableId = generateStableId(relPath, i);
-				const insertPos = call.end - 1;
-				s.appendLeft(insertPos, `, "${stableId}"`);
+			const occurrences = /* @__PURE__ */ new Map();
+			for (const { call, stmt } of callSites) {
+				const stmtText = code.slice(stmt.start, stmt.end);
+				const spanText = code.slice(call.start, call.end);
+				const dupKey = stmtText + String.fromCharCode(0) + spanText;
+				const occurrence = occurrences.get(dupKey) ?? 0;
+				occurrences.set(dupKey, occurrence + 1);
+				const stableId = generateStableId(relPath, stmtText, spanText, occurrence);
+				const lastArg = call.arguments[call.arguments.length - 1];
+				s.appendLeft(lastArg.end, `, "${stableId}"`);
 			}
 			return {
 				code: s.toString(),
@@ -6748,18 +6902,24 @@ function timberCacheTransform(ctx) {
 * 2. Externalizes `.wasm` imports so Rolldown skips them
 * 3. Copies the WASM files to the build output so wrangler can find them
 *
-* Only active for Cloudflare adapter production builds.
+* Only active for Cloudflare adapter production builds — every hook bails
+* unless `isCloudflareBuild` was set in configResolved. In dev and non-CF
+* builds, `.wasm` imports are left to Vite's own handling (?init / ?url or
+* a clear build error), never silently externalized.
 */
 function isCloudflareAdapter(ctx) {
 	return ctx.config.adapter?.name === "cloudflare";
 }
 function timberCloudflareWasm(ctx) {
 	const wasmFiles = /* @__PURE__ */ new Map();
+	const usedBasenames = /* @__PURE__ */ new Set();
+	let isCloudflareBuild = false;
 	return [{
 		name: "timber-cloudflare-wasm",
 		configResolved(resolved) {
 			if (resolved.command !== "build") return;
 			if (!isCloudflareAdapter(ctx)) return;
+			isCloudflareBuild = true;
 			for (const envName of ["rsc", "ssr"]) {
 				const env = resolved.environments[envName];
 				if (!env) continue;
@@ -6767,35 +6927,51 @@ function timberCloudflareWasm(ctx) {
 				if (!conditions.includes("workerd")) conditions.unshift("workerd");
 			}
 		},
+		transform(code, id) {
+			if (!isCloudflareBuild) return;
+			if (!id.includes("takumi")) return;
+			const stripped = code.replaceAll(/\/\*\s*@vite-ignore\s*\*\/\s*\n\s*"@takumi-rs\/wasm"/g, "\"@takumi-rs/wasm\"");
+			if (stripped !== code) return stripped;
+		},
 		resolveId: {
 			order: "pre",
 			async handler(source, importer) {
+				if (!isCloudflareBuild) return;
 				if (!source.endsWith(".wasm")) return;
 				let absolutePath;
 				if (source.startsWith(".") && importer) absolutePath = resolve(dirname(importer), source);
 				else return;
-				const filename = basename(absolutePath);
-				wasmFiles.set(filename, absolutePath);
+				let outputName = wasmFiles.get(absolutePath);
+				if (!outputName) {
+					outputName = basename(absolutePath);
+					if (usedBasenames.has(outputName)) {
+						const hash = createHash("sha256").update(await readFile(absolutePath)).digest("hex").slice(0, 8);
+						outputName = outputName.replace(/\.wasm$/, `.${hash}.wasm`);
+					}
+					usedBasenames.add(outputName);
+					wasmFiles.set(absolutePath, outputName);
+				}
 				return {
-					id: "./" + filename,
+					id: "./" + outputName,
 					external: true
 				};
 			}
 		},
 		async writeBundle(options, bundle) {
+			if (!isCloudflareBuild) return;
 			if (wasmFiles.size === 0) return;
 			const outDir = options.dir;
 			if (!outDir) return;
 			const targetDirs = /* @__PURE__ */ new Set();
 			for (const chunk of Object.values(bundle)) {
 				if (chunk.type !== "chunk") continue;
-				for (const filename of wasmFiles.keys()) if (chunk.code.includes(filename)) targetDirs.add(dirname(resolve(outDir, chunk.fileName)));
+				for (const outputName of wasmFiles.values()) if (chunk.code.includes(outputName)) targetDirs.add(dirname(resolve(outDir, chunk.fileName)));
 			}
 			if (targetDirs.size === 0) return;
 			const copies = [];
 			for (const dir of targetDirs) {
 				await mkdir(dir, { recursive: true });
-				for (const [filename, absolutePath] of wasmFiles) copies.push(copyFile(absolutePath, resolve(dir, filename)));
+				for (const [absolutePath, outputName] of wasmFiles) copies.push(copyFile(absolutePath, resolve(dir, outputName)));
 			}
 			await Promise.all(copies);
 		}
@@ -7623,6 +7799,7 @@ function timber(config) {
 				"@timber-js/app/cache",
 				"@timber-js/app/search-params",
 				"@timber-js/app/segment-params",
+				"@timber-js/app/params",
 				"@timber-js/app/codec"
 			];
 			if (command === "build") return {