@timber-js/app 0.2.0-alpha.208 → 0.2.0-alpha.209

package/dist/adapters/nitro.js

@@ -1,7 +1,8 @@
 import { t as RSC_CONTENT_TYPE } from "../_chunks/rsc-media-type-DDc7duTD.js";
-import { a as IMMUTABLE_CACHE, i as writeHeadersFile, n as findUnhashedStaticFiles, r as runSharedBuildSteps, t as buildStaticDirectoryOutput } from "../_chunks/build-output-helper-9dqCv1pZ.js";
+import { a as STATIC_CACHE, i as IMMUTABLE_CACHE, n as runSharedBuildSteps, o as adapterBase, r as writeHeadersFile, t as buildStaticDirectoryOutput } from "../_chunks/build-output-helper-RV_BRcF1.js";
 import { transformWithOxc } from "vite";
-import { basename, dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { existsSync } from "node:fs";
 import { cp, glob, readFile, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 //#region src/server/compress.ts?raw
@@ -55,11 +56,21 @@ var MODULE_SPECIFIERS = [
 function inlineCompressImports(code) {
 	let out = code;
 	for (const { pattern, replacement } of INLINED_IMPORTS) out = out.replace(pattern, replacement);
-	const surviving = MODULE_SPECIFIERS.map((pattern) => pattern.exec(out)).find(Boolean);
-	if (surviving) throw new Error(`[timber] server/compress.ts is emitted as a standalone _compress.mjs (type-stripped, not bundled), so it cannot import anything at runtime. Found: ${surviving[0].trim()}\n  Either inline the value in adapters/compress-module.ts (see INLINED_IMPORTS) or keep the dependency out of server/compress.ts.`);
+	assertStandalone(out, "server/compress.ts", "_compress.mjs");
 	return out;
 }
 /**
+* Throw if type-stripped server source still imports anything but a Node
+* builtin. Such a module is emitted alone into the build output, where no
+* specifier has anything to resolve to.
+*
+* @internal Shared by the standalone-module generators.
+*/
+function assertStandalone(code, source, emitted) {
+	const surviving = MODULE_SPECIFIERS.map((pattern) => pattern.exec(code)).find(Boolean);
+	if (surviving) throw new Error(`[timber] ${source} is emitted as a standalone ${emitted} (type-stripped, not bundled), so it cannot import anything at runtime. Found: ${surviving[0].trim()}\n  Either inline the value in the generator in adapters/ or keep the dependency out of ${source}.`);
+}
+/**
 * Compile server/compress.ts into a standalone ESM module.
 *
 * Uses Vite's OXC transform to strip TypeScript types from the
@@ -72,12 +83,27 @@ async function generateCompressModule() {
 	return "// Generated by @timber-js/app — compiled from server/compress.ts.\n// Do not edit — this file is regenerated on each build.\n" + inlineCompressImports((await transformWithOxc(compress_default, "compress.ts", { lang: "ts" })).code);
 }
 //#endregion
+//#region src/server/canonicalize.ts?raw
+var canonicalize_default = "/**\n * URL canonicalization — runs once at the request boundary.\n *\n * Every layer (proxy.ts, middleware.ts, access.ts, components) sees the same\n * canonical path. No re-decoding occurs at any later stage.\n *\n * See design/07-routing.md §\"URL Canonicalization & Security\"\n */\n\n/** Result of canonicalization — either a clean path or a rejection. */\nexport type CanonicalizeResult = { ok: true; pathname: string } | { ok: false; status: 400 };\n\n/**\n * Encoded separators that produce a 400 rejection.\n * %2f (/) and %5c (\\) cause path-confusion attacks.\n *\n * Shared between the runtime canonicalizer and the build-time route scanner\n * to ensure both enforce identical security rules. See design/13-security.md.\n */\nexport const ENCODED_SEPARATOR_RE = /%2f|%5c/i;\n\n/** Null byte — rejected. Shared with the route scanner. */\nexport const NULL_BYTE_RE = /%00/i;\n\n/**\n * Canonicalize a URL pathname.\n *\n * 1. Reject encoded separators (%2f, %5c) and null bytes (%00)\n * 2. Single percent-decode\n * 3. Collapse // → /\n * 4. Resolve .. segments (reject if escaping root)\n * 5. Strip trailing slash (except root \"/\")\n *\n * @param rawPathname - The raw pathname from the request URL (percent-encoded)\n * @param stripTrailingSlash - Whether to strip trailing slashes. Default: true.\n */\nexport function canonicalize(rawPathname: string, stripTrailingSlash = true): CanonicalizeResult {\n  // Step 1: Reject dangerous encoded sequences BEFORE decoding.\n  // This must happen on the raw input so %252f doesn't bypass after a single decode.\n  if (ENCODED_SEPARATOR_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n  if (NULL_BYTE_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n\n  // Step 2: Single percent-decode.\n  // Double-encoded input (%2561 → %61) stays as %61 — not decoded again.\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(rawPathname);\n  } catch {\n    // Malformed percent-encoding → 400\n    return { ok: false, status: 400 };\n  }\n\n  // Reject null bytes that appeared after decoding (from valid %00-like sequences\n  // that weren't caught above — belt and suspenders).\n  if (decoded.includes('\\0')) {\n    return { ok: false, status: 400 };\n  }\n\n  // Backslash is NOT a path separator — keep as literal character.\n  // But reject if it would create // after normalization (e.g., /\\evil.com).\n  // We do NOT convert \\ to / — it stays as a literal.\n\n  // Step 3: Collapse consecutive slashes.\n  let pathname = decoded.replace(/\\/\\/+/g, '/');\n\n  // Step 4: Resolve .. and . segments.\n  const segments = pathname.split('/');\n  const resolved: string[] = [];\n  for (const seg of segments) {\n    if (seg === '..') {\n      if (resolved.length <= 1) {\n        // Trying to escape root — 400\n        return { ok: false, status: 400 };\n      }\n      resolved.pop();\n    } else if (seg !== '.') {\n      resolved.push(seg);\n    }\n  }\n\n  pathname = resolved.join('/') || '/';\n\n  // Step 5: Strip trailing slash (except root \"/\").\n  if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith('/')) {\n    pathname = pathname.slice(0, -1);\n  }\n\n  return { ok: true, pathname };\n}\n";
+//#endregion
+//#region src/adapters/canonicalize-module.ts
+/**
+* Compile server/canonicalize.ts into a standalone ESM module exporting
+* `canonicalize`.
+*
+* @internal Exported for testing.
+*/
+async function generateCanonicalizeModule() {
+	const result = await transformWithOxc(canonicalize_default, "canonicalize.ts", { lang: "ts" });
+	assertStandalone(result.code, "server/canonicalize.ts", "_canonicalize.mjs");
+	return "// Generated by @timber-js/app — compiled from server/canonicalize.ts.\n// Do not edit — this file is regenerated on each build.\n" + result.code;
+}
+//#endregion
 //#region src/adapters/nitro-presets.ts
 var PRESET_CONFIGS = {
 	"vercel": {
 		nitroPreset: "vercel",
 		outputDir: ".vercel/output",
-		serverBundleDir: "functions/__server.func",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "vercel",
@@ -86,7 +112,6 @@ var PRESET_CONFIGS = {
 	"vercel-edge": {
 		nitroPreset: "vercel-edge",
 		outputDir: ".vercel/output",
-		serverBundleDir: "functions/__server.func",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "vercel-edge"
@@ -94,7 +119,6 @@ var PRESET_CONFIGS = {
 	"netlify": {
 		nitroPreset: "netlify",
 		outputDir: ".netlify/functions-internal",
-		serverBundleDir: "server",
 		supportsWaitUntil: false,
 		supportsEarlyHints: false,
 		runtimeName: "netlify"
@@ -102,7 +126,6 @@ var PRESET_CONFIGS = {
 	"netlify-edge": {
 		nitroPreset: "netlify-edge",
 		outputDir: ".netlify/edge-functions",
-		serverBundleDir: "server",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "netlify-edge"
@@ -110,7 +133,6 @@ var PRESET_CONFIGS = {
 	"aws-lambda": {
 		nitroPreset: "aws-lambda",
 		outputDir: ".output",
-		serverBundleDir: "server",
 		supportsWaitUntil: false,
 		supportsEarlyHints: false,
 		runtimeName: "aws-lambda"
@@ -118,7 +140,6 @@ var PRESET_CONFIGS = {
 	"deno-deploy": {
 		nitroPreset: "deno-deploy",
 		outputDir: ".output",
-		serverBundleDir: "server",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "deno-deploy"
@@ -126,7 +147,6 @@ var PRESET_CONFIGS = {
 	"azure-functions": {
 		nitroPreset: "azure-functions",
 		outputDir: ".output",
-		serverBundleDir: "server",
 		supportsWaitUntil: false,
 		supportsEarlyHints: false,
 		runtimeName: "azure-functions"
@@ -134,7 +154,6 @@ var PRESET_CONFIGS = {
 	"node-server": {
 		nitroPreset: "node-server",
 		outputDir: ".output",
-		serverBundleDir: "server",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "node-server"
@@ -142,7 +161,6 @@ var PRESET_CONFIGS = {
 	"bun": {
 		nitroPreset: "bun",
 		outputDir: ".output",
-		serverBundleDir: "server",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "bun"
@@ -150,139 +168,111 @@ var PRESET_CONFIGS = {
 };
 /** Presets that produce a locally-runnable server entry. */
 var LOCALLY_PREVIEWABLE = /* @__PURE__ */ new Set(["node-server", "bun"]);
-/**
-* Get the preset configuration for a given preset name.
-* @internal Exported for testing.
-*/
-function getPresetConfig(preset) {
-	return PRESET_CONFIGS[preset];
-}
 //#endregion
 //#region src/adapters/nitro-preview.ts
 /**
+* Content-Type by file extension for the preview server. Static hosts decide
+* this themselves; the table covers the file types a web build ships so the
+* preview does not turn ordinary files into downloads. An extension missing
+* here is served as `application/octet-stream`.
+*/
+var PREVIEW_MIME_TYPES = {
+	".html": "text/html; charset=utf-8",
+	".htm": "text/html; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".cjs": "text/javascript; charset=utf-8",
+	".map": "application/json; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".jsonld": "application/ld+json",
+	".webmanifest": "application/manifest+json",
+	".xml": "application/xml",
+	".rss": "application/rss+xml",
+	".atom": "application/atom+xml",
+	".txt": "text/plain; charset=utf-8",
+	".md": "text/markdown; charset=utf-8",
+	".csv": "text/csv; charset=utf-8",
+	".ics": "text/calendar; charset=utf-8",
+	".vtt": "text/vtt; charset=utf-8",
+	".pdf": "application/pdf",
+	".wasm": "application/wasm",
+	".zip": "application/zip",
+	".gz": "application/gzip",
+	".png": "image/png",
+	".apng": "image/apng",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".svg": "image/svg+xml",
+	".ico": "image/x-icon",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".bmp": "image/bmp",
+	".tif": "image/tiff",
+	".tiff": "image/tiff",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".ttf": "font/ttf",
+	".otf": "font/otf",
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".ogg": "audio/ogg",
+	".oga": "audio/ogg",
+	".m4a": "audio/mp4",
+	".flac": "audio/flac",
+	".mp4": "video/mp4",
+	".webm": "video/webm",
+	".ogv": "video/ogg",
+	".mov": "video/quicktime"
+};
+/**
 * Generate a standalone preview server script that uses Node's built-in
 * HTTP server. This bypasses Nitro entirely — the Nitro entry.ts imports
 * h3 which isn't available outside a Nitro build. For local preview we
-* just need to serve static files and route requests to the RSC handler.
+* just need to serve static files and, in a server build, route requests
+* to the RSC handler.
+*
+* Generated at build time rather than at preview time, so everything it
+* serves comes from the build's artifacts instead of guesses about the
+* directory it runs in.
 *
 * @internal Exported for testing.
 */
-function generatePreviewScript(buildDir, preset) {
-	const rscEntryRelative = relative(join(buildDir, "nitro"), join(buildDir, "rsc", "index.js"));
-	const rscEntry = rscEntryRelative.startsWith(".") ? rscEntryRelative : "./" + rscEntryRelative;
-	const publicDir = "./public";
-	const manifestInitPath = "./_timber-manifest-init.js";
-	return `// Generated by @timber-js/app — standalone preview server.
-// Uses Node's built-in HTTP server to serve static assets and route
-// dynamic requests through the RSC handler. No Nitro/h3 dependency.
-
-import { createServer } from 'node:http';
-import { readFile, stat } from 'node:fs/promises';
-import { join, extname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { existsSync } from 'node:fs';
-
-// Set runtime before importing the handler.
-process.env.TIMBER_RUNTIME = '${getPresetConfig(preset).runtimeName}';
-
-// Load the build manifest if it exists.
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
-const manifestPath = join(__dirname, '${manifestInitPath}');
-if (existsSync(manifestPath)) {
-  await import('${manifestInitPath}');
-}
-
+function generatePreviewScript(options) {
+	const immutablePrefixes = options.immutableDirs.map((dir) => `/${dir}/`);
+	const contentTypes = options.output === "static" ? options.contentTypes : {};
+	const handlerSetup = options.output === "server" ? `// Set runtime before importing the handler.
+process.env.TIMBER_RUNTIME = ${JSON.stringify(options.runtimeName)};
+${options.hasManifestInit ? `
+// Load the build manifest before the handler reads it.
+await import('./_timber-manifest-init.js');
+` : ""}
 // Import the RSC handler (default export is the fetch-like handler).
-const { default: handler, runWithEarlyHintsSender } = await import('${rscEntry}');
+const { default: handler, runWithEarlyHintsSender } = await import(${JSON.stringify(options.rscEntry)});
 
 // Import compression helper for self-hosted response compression.
 const { compressResponse } = await import('./_compress.mjs');
 
 // Web→Node response bridge with backpressure (TIM-1154).
 const { sendNodeResponse } = await import('./_send-response.mjs');
-
-const MIME_TYPES = {
-  '.html': 'text/html',
-  '.js': 'application/javascript',
-  '.mjs': 'application/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.ico': 'image/x-icon',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.ttf': 'font/ttf',
-  '.otf': 'font/otf',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.webm': 'video/webm',
-  '.mp4': 'video/mp4',
-  '.txt': 'text/plain',
-  '.xml': 'application/xml',
-  '.wasm': 'application/wasm',
-};
-
-const publicDir = join(__dirname, '${publicDir}');
-
-// Port resolution (TIM-842):
-//   - Default to 3000
-//   - If PORT env var is set, honor it strictly (fail loudly on conflict)
-//   - Otherwise auto-bump from 3000 until a free port is found
-// Mirrors the dev server behavior so timber dev/preview/production all
-// behave the same way around port selection.
-const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
-const portIsExplicit = envPort != null && Number.isFinite(envPort) && envPort > 0;
-const startPort = portIsExplicit ? envPort : 3000;
-const host = process.env.HOST || 'localhost';
-
-// Set after listenWithBump() resolves so request handlers can build
-// absolute URLs from the actual bound port (which may differ from
-// startPort after an auto-bump).
-let boundPort = startPort;
-
-const server = createServer(async (req, res) => {
-  // Scheme from the socket's TLS state — a hardcoded http:// breaks CSRF
-  // origin comparison and absolute-URL construction when TLS is terminated
-  // at this server (TIM-1073; mirrors the dev-server fix in TIM-1067).
-  // X-Forwarded-Proto is intentionally not consulted here: on a direct
-  // connection it would be attacker-controlled. The CSRF layer honors it
-  // separately for reverse-proxy deployments.
-  const scheme = req.socket?.encrypted ? 'https' : 'http';
-  const url = new URL(req.url || '/', \`\${scheme}://\${host}:\${boundPort}\`);
-
-  // Try serving static files from the public directory first.
-  const filePath = join(publicDir, url.pathname);
-  // Prevent path traversal.
-  if (filePath.startsWith(publicDir)) {
-    try {
-      const fileStat = await stat(filePath);
-      if (fileStat.isFile()) {
-        const ext = extname(filePath);
-        const contentType = MIME_TYPES[ext] || 'application/octet-stream';
-        const body = await readFile(filePath);
-        // Hashed assets get immutable cache, others get short cache.
-        const isImmutable =
-          url.pathname.startsWith('/assets/') || url.pathname.startsWith('/_timber/fonts/');
-        const cacheControl = isImmutable
-          ? 'public, max-age=31536000, immutable'
-          : 'public, max-age=3600, must-revalidate';
-        res.writeHead(200, {
-          'Content-Type': contentType,
-          'Content-Length': body.length,
-          'Cache-Control': cacheControl,
-        });
-        res.end(body);
-        return;
-      }
-    } catch {
-      // File not found — fall through to the RSC handler.
-    }
+` : "";
+	const fallback = options.output === "static" ? `  if (badPath) {
+    res.writeHead(400, { 'Content-Type': 'text/plain' });
+    res.end('Bad Request');
+    return;
   }
-
+  const notFound = await findFile('/404.html');
+  if (notFound) {
+    await sendFile(req, res, notFound, 404, 'text/html', 'public, max-age=0, must-revalidate');
+    return;
+  }
+  res.writeHead(404, { 'Content-Type': 'text/plain' });
+  res.end('Not Found');
+` : `  await handleDynamic(req, res, url);
+`;
+	const dynamicHandler = options.output === "server" ? `
+async function handleDynamic(req, res, url) {
   // Convert Node request to Web Request.
   const headers = new Headers();
   for (const [key, value] of Object.entries(req.headers)) {
@@ -336,7 +326,124 @@ const server = createServer(async (req, res) => {
     }
     res.end('Internal Server Error');
   }
-});
+}
+` : "";
+	return `// Generated by @timber-js/app — standalone preview server.
+// Do not edit — this file is regenerated on each build.
+// Uses Node's built-in HTTP server to serve the build's files${options.output === "server" ? " and route\n// dynamic requests through the RSC handler" : ""}. No Nitro/h3 dependency.
+
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { join, extname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { canonicalize } from './_canonicalize.mjs';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+${handlerSetup}
+const MIME_TYPES = ${JSON.stringify(PREVIEW_MIME_TYPES, null, 2)};
+
+// Recorded by the build: content-hashed directories, and the Content-Type of
+// each extensionless API route output (a file name cannot say it). Both are
+// decoded route-space paths, matched against the decoded request path.
+const IMMUTABLE_PREFIXES = ${JSON.stringify(immutablePrefixes)};
+const BASE = ${JSON.stringify(options.base)};
+const CONTENT_TYPES = ${JSON.stringify(contentTypes)};
+const SERVE_DIRECTORY_INDEX = ${options.output === "static"};
+
+const publicDir = join(__dirname, 'public');
+
+/**
+ * The file under publicDir that a decoded URL path names, or null. A static
+ * build lays its pages out as <path>/index.html, so a directory serves its
+ * index there.
+ */
+async function findFile(pathname) {
+  const filePath = join(publicDir, pathname);
+  // Prevent path traversal (and a sibling like public-other/ passing a bare
+  // prefix check).
+  if (!filePath.startsWith(publicDir + sep)) return null;
+  try {
+    const fileStat = await stat(filePath);
+    if (fileStat.isFile()) return filePath;
+    if (SERVE_DIRECTORY_INDEX && fileStat.isDirectory()) {
+      const index = join(filePath, 'index.html');
+      if ((await stat(index)).isFile()) return index;
+    }
+  } catch {
+    // Not found.
+  }
+  return null;
+}
+
+/**
+ * The route-space path for a request path, or null when the request is
+ * outside the deployment base (it names no file of this build).
+ */
+function stripBase(pathname) {
+  if (BASE === '/') return pathname;
+  if (pathname === BASE.slice(0, -1)) return '/';
+  if (!pathname.startsWith(BASE)) return null;
+  return pathname.slice(BASE.length - 1);
+}
+
+async function sendFile(req, res, filePath, status, contentType, cacheControl) {
+  const body = await readFile(filePath);
+  res.writeHead(status, {
+    'Content-Type': contentType,
+    'Content-Length': body.length,
+    'Cache-Control': cacheControl,
+  });
+  res.end(req.method === 'HEAD' ? undefined : body);
+}
+${dynamicHandler}
+// Port resolution (TIM-842):
+//   - Default to 3000
+//   - If PORT env var is set, honor it strictly (fail loudly on conflict)
+//   - Otherwise auto-bump from 3000 until a free port is found
+// Mirrors the dev server behavior so timber dev/preview/production all
+// behave the same way around port selection.
+const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
+const portIsExplicit = envPort != null && Number.isFinite(envPort) && envPort > 0;
+const startPort = portIsExplicit ? envPort : 3000;
+const host = process.env.HOST || 'localhost';
+
+// Set after listenWithBump() resolves so request handlers can build
+// absolute URLs from the actual bound port (which may differ from
+// startPort after an auto-bump).
+let boundPort = startPort;
+
+const server = createServer(async (req, res) => {
+  // Scheme from the socket's TLS state — a hardcoded http:// breaks CSRF
+  // origin comparison and absolute-URL construction when TLS is terminated
+  // at this server (TIM-1073; mirrors the dev-server fix in TIM-1067).
+  // X-Forwarded-Proto is intentionally not consulted here: on a direct
+  // connection it would be attacker-controlled. The CSRF layer honors it
+  // separately for reverse-proxy deployments.
+  const scheme = req.socket?.encrypted ? 'https' : 'http';
+  const url = new URL(req.url || '/', \`\${scheme}://\${host}:\${boundPort}\`);
+
+  // The runtime's own request-boundary canonicalizer (_canonicalize.mjs,
+  // compiled from server/canonicalize.ts): one decode, and the same 400s for
+  // encoded separators, null bytes, malformed encoding, and escaping the root
+  // (design/13-security.md). The base is stripped from its canonical result,
+  // so an encoded spelling of the base is the same path. What remains, in
+  // route space, is looked up in public/; null names no file.
+  const canonical = canonicalize(url.pathname, false);
+  const badPath = !canonical.ok;
+  const pathname = canonical.ok ? stripBase(canonical.pathname) : null;
+  const filePath = pathname === null ? null : await findFile(pathname);
+  if (filePath) {
+    const contentType =
+      CONTENT_TYPES[pathname] || MIME_TYPES[extname(filePath).toLowerCase()] || 'application/octet-stream';
+    // Hashed assets get immutable cache, others get short cache.
+    const isImmutable = IMMUTABLE_PREFIXES.some((prefix) => pathname.startsWith(prefix));
+    const cacheControl = isImmutable ? ${JSON.stringify(IMMUTABLE_CACHE)} : ${JSON.stringify(STATIC_CACHE)};
+    await sendFile(req, res, filePath, 200, contentType, cacheControl);
+    return;
+  }
+
+${fallback}});
 
 function listenWithBump(port, attempt = 0) {
   return new Promise((resolveListen, rejectListen) => {
@@ -483,12 +590,19 @@ function nitro(options = {}) {
 	const compress = options.compress ?? true;
 	return {
 		name: `nitro-${preset}`,
-		async buildOutput(config, buildDir) {
-			const outDir = join(buildDir, "nitro");
-			if (config.output === "static" && config.staticPagesDir) {
-				await buildStaticDirectoryOutput(config, buildDir, outDir, "public");
+		async buildOutput(config, artifacts) {
+			const outDir = join(artifacts.outputDir, "nitro");
+			if (artifacts.output === "static") {
+				await buildStaticDirectoryOutput(config, artifacts, outDir, "public");
 				const publicDir = join(outDir, "public");
-				await writeHeadersFile(publicDir, config, await findUnhashedStaticFiles(publicDir));
+				await writeHeadersFile(publicDir, config, artifacts);
+				await writeFile(join(outDir, CANONICALIZE_MODULE), await generateCanonicalizeModule());
+				await writeFile(join(outDir, PREVIEW_SCRIPT), generatePreviewScript({
+					output: "static",
+					immutableDirs: artifacts.immutableDirs,
+					base: adapterBase(config),
+					contentTypes: artifacts.contentTypes
+				}));
 				if ((options.staticTarget ?? "generic") === "github-pages") {
 					await writeFile(join(publicDir, ".nojekyll"), "");
 					try {
@@ -499,36 +613,57 @@ function nitro(options = {}) {
 			}
 			await runSharedBuildSteps({
 				config,
-				buildDir,
+				artifacts,
 				outDir,
 				publicDirName: "public"
 			});
 			await writeFile(join(outDir, "_compress.mjs"), await generateCompressModule());
 			await writeFile(join(outDir, "_send-response.mjs"), generateSendResponseModule());
-			if (config.manifestInit) {
+			if (LOCALLY_PREVIEWABLE.has(preset)) {
+				await writeFile(join(outDir, CANONICALIZE_MODULE), await generateCanonicalizeModule());
+				await writeFile(join(outDir, PREVIEW_SCRIPT), generatePreviewScript({
+					output: "server",
+					runtimeName: PRESET_CONFIGS[preset].runtimeName,
+					rscEntry: importSpecifier(outDir, join(artifacts.rsc.path, "index.js")),
+					hasManifestInit: !!artifacts.manifestInit,
+					immutableDirs: artifacts.immutableDirs,
+					base: adapterBase(config)
+				}));
+			}
+			if (artifacts.manifestInit) {
 				const rscEntry = join(outDir, "rsc", "index.js");
 				const rscContent = await readFile(rscEntry, "utf-8");
-				await writeFile(rscEntry, `${config.manifestInit}\n${rscContent}`);
+				await writeFile(rscEntry, `${artifacts.manifestInit}\n${rscContent}`);
 			}
-			const entry = generateNitroEntry(buildDir, outDir, preset, compress);
+			const entry = generateNitroEntry(preset, compress);
 			await writeFile(join(outDir, "entry.ts"), entry);
-			const { serverDir } = await runNitroBuild(outDir, preset, options.nitroConfig);
-			const prebuiltSrc = join(buildDir, "prebuilt");
-			await cp(prebuiltSrc, join(serverDir, "prebuilt"), { recursive: true }).catch((e) => {
-				if (e.code !== "ENOENT") throw e;
-			});
-			if (preset === "vercel" || preset === "vercel-edge") await copyPrebuiltToVercelFuncClones(dirname(serverDir), prebuiltSrc, basename(serverDir));
+			const { serverDir } = await runNitroBuild(outDir, preset, artifacts.immutableDirs, options.nitroConfig);
+			if (artifacts.prebuilt) {
+				const prebuiltSrc = artifacts.prebuilt.path;
+				await cp(prebuiltSrc, join(serverDir, "prebuilt"), { recursive: true });
+				if (preset === "vercel" || preset === "vercel-edge") await copyPrebuiltToVercelFuncClones(dirname(serverDir), prebuiltSrc, basename(serverDir));
+			}
 		},
-		preview: LOCALLY_PREVIEWABLE.has(preset) ? async (_config, buildDir) => {
-			const previewScript = generatePreviewScript(buildDir, preset);
-			const scriptPath = join(buildDir, "nitro", "_preview-server.mjs");
-			await writeFile(scriptPath, previewScript);
-			await spawnNitroPreview(preset === "bun" ? "bun" : "node", [scriptPath], join(buildDir, "nitro"));
-		} : void 0
+		async preview(_config, { output, outputDir }) {
+			if (output === "server" && !LOCALLY_PREVIEWABLE.has(preset)) throw new Error(`[timber] The nitro '${preset}' preset has no local runtime, so \`timber preview\` cannot run its server build. Preview with a node-server build, or with the platform's own tooling.`);
+			const nitroDir = join(outputDir, "nitro");
+			const script = join(nitroDir, PREVIEW_SCRIPT);
+			if (!existsSync(script)) throw new Error(`[timber] No preview server at ${script}. Run \`timber build\` before \`timber preview\`.`);
+			await spawnNitroPreview(output === "server" && preset === "bun" ? "bun" : process.execPath, [script], nitroDir);
+		}
 	};
 }
+/** The preview server buildOutput writes into the Nitro output directory. */
+var PREVIEW_SCRIPT = "_preview-server.mjs";
+/** The request-path canonicalizer the preview server imports beside it. */
+var CANONICALIZE_MODULE = "_canonicalize.mjs";
+/** A relative ESM import specifier for `file`, as imported from a module in `fromDir`. */
+function importSpecifier(fromDir, file) {
+	const path = relative(fromDir, file).split(sep).join("/");
+	return path.startsWith("../") ? path : "./" + path;
+}
 /** @internal Exported for testing. */
-function generateNitroEntry(buildDir, outDir, preset, compress = true) {
+function generateNitroEntry(preset, compress = true) {
 	const serverEntryRelative = "./rsc/index.js";
 	const runtimeName = PRESET_CONFIGS[preset].runtimeName;
 	const earlyHints = PRESET_CONFIGS[preset].supportsEarlyHints;
@@ -645,7 +780,7 @@ function wrapNitroLoggerForBuild(logger, prefixes = SUPPRESSED_NITRO_HINT_PREFIX
 function getPostBuildHint(preset) {
 	return LOCALLY_PREVIEWABLE.has(preset) ? "You can preview this build using `timber preview`" : null;
 }
-async function runNitroBuild(nitroDir, preset, userConfig) {
+async function runNitroBuild(nitroDir, preset, immutableDirs, userConfig) {
 	const presetConfig = PRESET_CONFIGS[preset];
 	const { createNitro, build: nitroBuild, prepare, copyPublicAssets } = await import("nitro/builder");
 	const nitro = await createNitro({
@@ -653,10 +788,7 @@ async function runNitroBuild(nitroDir, preset, userConfig) {
 		preset: presetConfig.nitroPreset,
 		renderer: { handler: join(nitroDir, "entry.ts") },
 		output: { dir: join(nitroDir, presetConfig.outputDir) },
-		routeRules: {
-			"/assets/**": { headers: { "Cache-Control": IMMUTABLE_CACHE } },
-			"/_timber/fonts/**": { headers: { "Cache-Control": IMMUTABLE_CACHE } }
-		},
+		routeRules: Object.fromEntries(immutableDirs.map((dir) => [`/${dir}/**`, { headers: { "Cache-Control": IMMUTABLE_CACHE } }])),
 		rollupConfig: { external: [/\.\.\/rsc\//] },
 		...presetConfig.extraConfig,
 		...userConfig
@@ -674,21 +806,6 @@ async function runNitroBuild(nitroDir, preset, userConfig) {
 	return { serverDir };
 }
 /**
-* Resolve the destination path for prebuilt flight payloads in the Nitro
-* output directory. The RSC entry resolves `../prebuilt/` relative to its
-* bundled chunk location (`<serverBundleDir>/_chunks/`), so prebuilt/ must
-* live at `<serverBundleDir>/prebuilt/`.
-*
-* The serverBundleDir varies by preset — Nitro's Vercel preset uses
-* `functions/__server.func` while most others use `server`.
-*
-* @internal Exported for testing.
-*/
-function resolvePrebuiltOutputPath(outDir, preset) {
-	const presetConfig = PRESET_CONFIGS[preset];
-	return join(outDir, presetConfig.outputDir, presetConfig.serverBundleDir, "prebuilt");
-}
-/**
 * Copy prebuilt payloads into cloned Vercel function directories.
 *
 * When users configure `vercel.functionRules`, Nitro's compiled hook clones
@@ -705,11 +822,9 @@ async function copyPrebuiltToVercelFuncClones(functionsDir, prebuiltSrc, baseFun
 	} catch {
 		return;
 	}
-	await Promise.all(funcDirs.map((dir) => cp(prebuiltSrc, join(dir, "prebuilt"), { recursive: true }).catch((e) => {
-		if (e.code !== "ENOENT") throw e;
-	})));
+	await Promise.all(funcDirs.map((dir) => cp(prebuiltSrc, join(dir, "prebuilt"), { recursive: true })));
 }
 //#endregion
-export { copyPrebuiltToVercelFuncClones, generateNitroEntry, getPostBuildHint, isSuppressedNitroHint, nitro, resolvePrebuiltOutputPath, selectSuppressedHintPrefixes, wrapNitroLoggerForBuild };
+export { copyPrebuiltToVercelFuncClones, generateNitroEntry, getPostBuildHint, isSuppressedNitroHint, nitro, selectSuppressedHintPrefixes, wrapNitroLoggerForBuild };
 
 //# sourceMappingURL=nitro.js.map