@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/llms.txt

@@ -0,0 +1,55 @@
+# @timber-js/app
+
+> Vite-native React Server Components framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript.
+
+timber.js is a React framework built on Vite and React Server Components. It uses file-system routing (app/ directory), server components by default, and produces real HTTP status codes. It deploys to Cloudflare Workers, Node.js, Vercel, Netlify, and more via adapters.
+
+It is inspired by, but _not_ next.js. Do not assume next.js features work in timber, though the routing is similar, much of the rest diverges.
+
+## Docs
+
+Documentation ships with this package in the `docs/` directory. All files are MDX.
+
+### Learn (core concepts, read in order)
+
+- [Introduction](docs/learn/00-introduction.mdx)
+- [Quick Start](docs/learn/01-quick-start.mdx)
+- [Pages and Layouts](docs/learn/02-pages-and-layouts.mdx)
+- [Fetching Data](docs/learn/03-fetching-data.mdx)
+- [Access Control](docs/learn/03b-access-control.mdx)
+- [Loading States](docs/learn/04-loading-states.mdx)
+- [The Flush Point](docs/learn/04b-the-flush-point.mdx)
+- [Typed Params](docs/learn/05-typed-params.mdx)
+- [Forms and Actions](docs/learn/06-forms-and-actions.mdx)
+- [Streaming](docs/learn/08-streaming.mdx)
+- [Caching](docs/learn/09-caching.mdx)
+- [Middleware](docs/learn/10-middleware.mdx)
+- [Error Handling](docs/learn/11-error-handling.mdx)
+- [Client Navigation](docs/learn/12-client-navigation.mdx)
+- [Configuration](docs/learn/13-configuration.mdx)
+- [Deploying](docs/learn/14-deploying.mdx)
+
+### More (advanced topics)
+
+- [Advanced Routing](docs/more/01-advanced-routing.mdx)
+- [Advanced Forms](docs/more/02-advanced-forms.mdx)
+- [Coming from Next.js](docs/more/03-coming-from-nextjs.mdx)
+- [Metadata and Fonts](docs/more/04-metadata-and-fonts.mdx)
+- [MDX](docs/more/04b-mdx.mdx)
+- [Content Collections](docs/more/05-content-collections.mdx)
+- [Instrumentation & Tracing](docs/more/06-instrumentation.mdx)
+- [Security](docs/more/07-security.mdx)
+
+### API Reference
+
+- [@timber-js/app/server](docs/api/30-api-server.mdx)
+- [@timber-js/app/client](docs/api/31-api-client.mdx)
+- [@timber-js/app/cache](docs/api/32-api-cache.mdx)
+- [Search & Segment Params](docs/api/33-api-search-params.mdx)
+- [timber.config.ts](docs/api/34-api-config.mdx)
+- [TypeScript](docs/api/35-api-typescript.mdx)
+- [CLI](docs/api/36-cli.mdx)
+
+## AI Agent Skill
+
+A Claude Code skill is included at `agent-skill.md`. Load it for guidance on building timber.js applications.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.21",
-  "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
+  "version": "0.2.0-alpha.211",
+  "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
     "framework",
@@ -26,12 +26,27 @@
     "dist",
     "src",
     "bin",
+    "docs",
+    "agent-skill.md",
+    "llms.txt",
     "README.md",
     "LICENSE"
   ],
   "type": "module",
   "imports": {
-    "#/*": "./src/*"
+    "#server-internal": {
+      "types": "./dist/server/internal.d.ts",
+      "default": "./dist/server/internal.js"
+    },
+    "#client-internal": {
+      "types": "./dist/client/internal.d.ts",
+      "default": "./dist/client/internal.js"
+    },
+    "#routing": {
+      "types": "./dist/routing/index.d.ts",
+      "default": "./dist/routing/index.js"
+    },
+    "#server-only-guard": "./src/server/server-only-guard-noop.js"
   },
   "exports": {
     ".": {
@@ -46,13 +61,49 @@
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js"
     },
+    "./client/internal": {
+      "types": "./dist/client/internal.d.ts",
+      "import": "./dist/client/internal.js"
+    },
     "./cache": {
       "types": "./dist/cache/index.d.ts",
       "import": "./dist/cache/index.js"
     },
-    "./content": {
-      "types": "./dist/content/index.d.ts",
-      "import": "./dist/content/index.js"
+    "./cache/stores/memory": {
+      "types": "./dist/cache/stores/memory.d.ts",
+      "import": "./dist/cache/stores/memory.js"
+    },
+    "./cache/stores/redis": {
+      "types": "./dist/cache/stores/redis.d.ts",
+      "import": "./dist/cache/stores/redis.js"
+    },
+    "./cache/stores/cloudflare-kv": {
+      "types": "./dist/cache/stores/cloudflare-kv.d.ts",
+      "import": "./dist/cache/stores/cloudflare-kv.js"
+    },
+    "./cache/stores/vercel": {
+      "types": "./dist/cache/stores/vercel.d.ts",
+      "import": "./dist/cache/stores/vercel.js"
+    },
+    "./cdn": {
+      "types": "./dist/cdn/index.d.ts",
+      "import": "./dist/cdn/index.js"
+    },
+    "./cdn/cloudflare": {
+      "types": "./dist/cdn/cloudflare-purge.d.ts",
+      "import": "./dist/cdn/cloudflare-purge.js"
+    },
+    "./cdn/cloudflare-workers": {
+      "types": "./dist/cdn/workers-cache-purge.d.ts",
+      "import": "./dist/cdn/workers-cache-purge.js"
+    },
+    "./cdn/fastly": {
+      "types": "./dist/cdn/fastly-purge.d.ts",
+      "import": "./dist/cdn/fastly-purge.js"
+    },
+    "./codec": {
+      "types": "./dist/codec.d.ts",
+      "import": "./dist/codec.js"
     },
     "./cookies": {
       "types": "./dist/cookies/index.d.ts",
@@ -62,45 +113,68 @@
       "types": "./dist/search-params/index.d.ts",
       "import": "./dist/search-params/index.js"
     },
-    "./routing": {
-      "types": "./dist/routing/index.d.ts",
-      "import": "./dist/routing/index.js"
+    "./params": {
+      "types": "./dist/params/index.d.ts",
+      "import": "./dist/params/index.js"
     },
     "./adapters/cloudflare": {
       "types": "./dist/adapters/cloudflare.d.ts",
       "import": "./dist/adapters/cloudflare.js"
     },
+    "./adapters/cloudflare/cache": {
+      "types": "./dist/adapters/cloudflare-kv-cache.d.ts",
+      "import": "./dist/adapters/cloudflare-kv-cache.js"
+    },
+    "./adapters/cloudflare/dev": {
+      "types": "./dist/adapters/cloudflare-dev.d.ts",
+      "import": "./dist/adapters/cloudflare-dev.js"
+    },
     "./adapters/nitro": {
       "types": "./dist/adapters/nitro.d.ts",
       "import": "./dist/adapters/nitro.js"
     },
+    "./adapters/types": {
+      "types": "./dist/adapters/types.d.ts",
+      "import": "./dist/adapters/types.js"
+    },
+    "./fonts/google": {
+      "types": "./dist/shims/font-google.d.ts",
+      "import": "./dist/shims/font-google.js"
+    },
+    "./fonts/local": {
+      "types": "./dist/shims/font-local.d.ts",
+      "import": "./dist/shims/font-local.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/context-async-hooks": "^2.6.0",
-    "@opentelemetry/sdk-trace-base": "^2.6.0",
-    "nitro": "3.0.260311-beta"
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.11.0",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "cookie": "^2.0.1",
+    "jsonc-parser": "^3.3.1",
+    "magic-string": "^1.4.1",
+    "nitro": "3.0.260903-beta",
+    "oxc-transform-react": "^0.150.0",
+    "srvx": "^1.0.5"
   },
   "peerDependencies": {
-    "@content-collections/core": "^0.14.0",
+    "@content-collections/core": "^0.14.0 || ^0.15.0",
     "@content-collections/mdx": "^0.2.0",
-    "@content-collections/vite": "^0.2.0",
-    "@mdx-js/rollup": "^3.0.0",
-    "@vitejs/plugin-react": "^6.0.0",
-    "@vitejs/plugin-rsc": ">=0.5.21",
+    "@content-collections/vite": "^0.2.0 || ^0.3.0",
+    "@typescript/native-preview": "^7.0.0-dev.0",
+    "@vitejs/plugin-react": "^6.1.0",
+    "@vitejs/plugin-rsc": ">=0.5.35",
     "nuqs": "^2.0.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "vite": "^8.0.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "satteri": "^0.9.5",
+    "vite": "8.3.0",
+    "vite-plugin-satteri": "^0.2.15",
+    "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -113,14 +187,31 @@
     "@content-collections/vite": {
       "optional": true
     },
-    "@mdx-js/rollup": {
+    "satteri": {
+      "optional": true
+    },
+    "vite-plugin-satteri": {
+      "optional": true
+    },
+    "@typescript/native-preview": {
+      "optional": true
+    },
+    "wrangler": {
       "optional": true
     },
     "zod": {
       "optional": true
     }
   },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2"
+  },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "copy-docs": "node scripts/copy-docs.js",
+    "build": "vite build --config vite.lib.config.ts && node scripts/build-types.js && pnpm run copy-docs",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/adapters/build-output-helper.ts

@@ -0,0 +1,353 @@
+// Shared build-output helper for adapter buildOutput() methods.
+//
+// Steps 1–5 of every adapter's buildOutput are platform-agnostic:
+//   1. Copy client assets to the public/static directory
+//   2. Write _headers file for static asset cache control
+//   3. Copy RSC + SSR server bundles
+//   4. Write manifest-init module (if present)
+//
+// Only the final steps (entry codegen, platform config) vary per adapter.
+//
+// IMPORTANT: This module must remain a leaf — no imports from ../server/,
+// ../client/, or Vite-dependent code. See adapters/shared.ts header.
+
+import { writeFile, mkdir, cp, rm, readdir, readFile } from 'node:fs/promises';
+import { join, basename, relative } from 'node:path';
+import { adapterBase, generateHeadersFile } from './shared.ts';
+// Isomorphic, zero-import module — safe to load from an adapter, which Node's
+// native ESM loader evaluates before Vite's resolver exists. Same precedent as
+// `adapters/shared.ts` importing `../shared/base-path.js`.
+import {
+  HEADERS_FILE,
+  USER_MERGED_PLATFORM_FILES,
+  USER_PLATFORM_DIR,
+} from '../shared/static-platform-files.ts';
+import { detectFsIdentity, fsKey } from './fs-identity.ts';
+import type {
+  BuildArtifacts,
+  ServerBuildArtifacts,
+  StaticBuildArtifacts,
+  TimberConfig,
+} from './types.ts';
+
+/** Options for the shared build output steps. */
+export interface BuildOutputBaseOptions {
+  /** Resolved timber config. */
+  config: TimberConfig;
+  /** What the build produced. */
+  artifacts: ServerBuildArtifacts;
+  /** Adapter-specific output directory (e.g. `.timber/dist/nitro`). */
+  outDir: string;
+  /**
+   * Name of the public/static directory within outDir.
+   * Nitro uses 'public', Cloudflare uses 'static'.
+   */
+  publicDirName: string;
+}
+
+/**
+ * Run the platform-agnostic build output steps shared by all adapters:
+ *
+ * 1. Create the output directory
+ * 2. Copy client assets to the public/static directory
+ * 3. Write the `_headers` file for static asset cache control
+ * 4. Copy RSC and SSR server bundles into the output directory
+ * 5. Write the manifest-init module if present
+ *
+ * Returns the resolved public directory path for further adapter-specific use.
+ */
+export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise<string> {
+  const { config, artifacts, outDir, publicDirName } = opts;
+
+  // 1. Create the output directory.
+  await mkdir(outDir, { recursive: true });
+
+  // 2. Copy client assets to public/static directory.
+  // When client JavaScript is disabled, skip .js files — only CSS,
+  // fonts, images, and other static assets are needed.
+  const publicDir = join(outDir, publicDirName);
+  await mkdir(publicDir, { recursive: true });
+  const clientDir = artifacts.client.path;
+  // Find WASM files that are referenced by client JS (legitimate client WASM)
+  // vs orphaned server-only WASM (e.g. @takumi-rs for OG image generation).
+  // Only strip orphaned WASM to avoid breaking client-side WASM usage.
+  const referencedWasm = await findReferencedWasm(clientDir);
+
+  await cp(clientDir, publicDir, {
+    recursive: true,
+    filter: (src: string) => {
+      if (src.endsWith('.wasm') && !referencedWasm.has(basename(src))) {
+        return false;
+      }
+      if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;
+      return true;
+    },
+  });
+
+  // 3. Write _headers file for static asset cache control.
+  // Scan for unhashed files so they get per-file Cache-Control rules in the
+  // _headers file. On platforms like Cloudflare Workers Static Assets, the
+  // worker never sees static file requests — _headers is the only mechanism.
+  await writeHeadersFile(publicDir, config, artifacts);
+
+  // 4. Copy RSC + SSR server bundles into the output directory. The RSC
+  // bundle imports the SSR one by a path the RSC plugin computed between the
+  // two *build* directories, which the build names `rsc/` and `ssr/` as
+  // siblings (index.ts); deploying them under the same names keeps it valid.
+  await cp(artifacts.rsc.path, join(outDir, 'rsc'), { recursive: true });
+  await cp(artifacts.ssr.path, join(outDir, 'ssr'), { recursive: true });
+
+  // 4b. Copy prebuilt/ flight payloads (cache.component artifacts). These
+  // are produced by the post-build capture pass (design/44) and read at
+  // request time via the adapter's PrebuiltPayloadSource.
+  if (artifacts.prebuilt) {
+    await cp(artifacts.prebuilt.path, join(outDir, 'prebuilt'), { recursive: true });
+  }
+
+  // 5. Write manifest-init module if present.
+  if (artifacts.manifestInit) {
+    await writeFile(join(outDir, '_timber-manifest-init.js'), artifacts.manifestInit);
+  }
+
+  return publicDir;
+}
+
+/**
+ * Find unhashed static files in the public directory that need per-file
+ * Cache-Control rules in the `_headers` file.
+ *
+ * Excludes:
+ * - Files under the build's `immutableDirs` (covered by wildcard rules)
+ * - Files under `rsc/` and `ssr/` (server bundles, never served)
+ * - Underscore-prefixed files (`_headers`, `_worker.js`, etc.)
+ *
+ * Ordered for the rule cap: well-known metadata files, then everything
+ * else, then files under an underscore-prefixed directory — the
+ * framework's own output (unhashed RSC payloads in a static build with
+ * client JavaScript disabled, which nothing fetches). Those can number one
+ * per route, and must not take the budget from the app's real files.
+ *
+ * @internal Exported for testing.
+ */
+// Well-known metadata files that should be prioritized when capping
+// _headers rules, so they're never dropped in favor of less important files.
+const PRIORITY_FILES = new Set([
+  '/favicon.ico',
+  '/robots.txt',
+  '/sitemap.xml',
+  '/manifest.json',
+  '/manifest.webmanifest',
+  '/apple-touch-icon.png',
+]);
+
+export async function findUnhashedStaticFiles(
+  publicDir: string,
+  immutableDirs: readonly string[]
+): Promise<string[]> {
+  let files: string[];
+  try {
+    files = await collectFiles(publicDir);
+  } catch {
+    return [];
+  }
+
+  const priority: string[] = [];
+  const rest: string[] = [];
+  const framework: string[] = [];
+  for (const file of files) {
+    const rel = relative(publicDir, file).replace(/\\/g, '/');
+    if (immutableDirs.some((dir) => rel.startsWith(`${dir}/`))) continue;
+    if (rel.startsWith('rsc/') || rel.startsWith('ssr/')) continue;
+    if (basename(rel).startsWith('_')) continue;
+    const urlPath = '/' + rel;
+    if (PRIORITY_FILES.has(urlPath)) {
+      priority.push(urlPath);
+    } else if (rel.startsWith('_')) {
+      framework.push(urlPath);
+    } else {
+      rest.push(urlPath);
+    }
+  }
+
+  return [...priority.sort(), ...rest.sort(), ...framework.sort()];
+}
+
+/**
+ * Scan client JS files for references to .wasm filenames.
+ * Returns the set of WASM basenames that are actually imported/referenced
+ * by client code and must be preserved in the static output.
+ */
+async function findReferencedWasm(clientDir: string): Promise<Set<string>> {
+  const referenced = new Set<string>();
+  const files = await collectFiles(clientDir);
+
+  const jsFiles = files.filter((f) => f.endsWith('.js'));
+  const wasmFiles = files.filter((f) => f.endsWith('.wasm')).map((f) => basename(f));
+  if (wasmFiles.length === 0) return referenced;
+
+  for (const jsFile of jsFiles) {
+    const content = await readFile(jsFile, 'utf-8');
+    for (const wasmName of wasmFiles) {
+      if (content.includes(wasmName)) {
+        referenced.add(wasmName);
+      }
+    }
+  }
+
+  return referenced;
+}
+
+/**
+ * Build a static-only output directory (no server entry). Copies client
+ * assets and pre-rendered HTML/RSC/API files into `outDir/publicDirName`.
+ * Used by both Cloudflare and Nitro adapters in `output: 'static'` mode.
+ */
+export async function buildStaticDirectoryOutput(
+  config: TimberConfig,
+  artifacts: StaticBuildArtifacts,
+  outDir: string,
+  publicDirName: string
+): Promise<void> {
+  // Clean stale artifacts from prior builds (e.g. server-mode builds that
+  // left rsc/, ssr/, _worker.js in the outDir). Without this, a static
+  // build after a server build inherits 140+ unused server chunks.
+  await rm(outDir, { recursive: true, force: true }).catch(() => {});
+  await mkdir(outDir, { recursive: true });
+
+  const publicDir = join(outDir, publicDirName);
+  await mkdir(publicDir, { recursive: true });
+
+  // Copy client assets (JS, CSS, fonts, images).
+  await cp(artifacts.client.path, publicDir, {
+    recursive: true,
+    filter: (src: string) => {
+      if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;
+      return true;
+    },
+  });
+
+  // Copy pre-rendered static pages (HTML + RSC flight + API routes).
+  //
+  // This is the one place the build merges two independently-produced trees
+  // into a single directory, and `cp` resolves an overlap by overwriting with
+  // no diagnostic — the deployment then contains one of the two artifacts and
+  // nothing recorded which. Refuse instead (TIM-1266).
+  await assertNoTreeCollision(artifacts.pages.path, publicDir);
+  await cp(artifacts.pages.path, publicDir, { recursive: true });
+}
+
+/**
+ * Write the `_headers` file, folding in the user's `public/_headers`.
+ *
+ * Every adapter used to `writeFile` a generated `_headers` over whatever
+ * Vite had copied out of `public/`, so an app shipping its own CSP, CORS, or
+ * cache rules deployed without them and without a word (TIM-1326). The
+ * generated rules and the user's are not competitors — they address different
+ * paths — so this merges rather than refusing, the way `_redirects` has since
+ * TIM-1249.
+ *
+ * **Read from the project, not the output.** The generated file lands under
+ * the same name in the output directory, and `runSharedBuildSteps` does not
+ * clean `outDir`; a reader aimed there would fold the previous build's
+ * generated rules back in and compound them on every rebuild — the defect
+ * this pass fixed for `_redirects`.
+ *
+ * User rules go last. On Cloudflare and Netlify a `_headers` file applies
+ * every matching rule, so appending means the user's rules take effect; where
+ * a platform resolves a conflict in favour of the earlier rule instead, the
+ * framework keeps the paths it owns and the user keeps the rest. Under either
+ * reading this is no worse than the previous behaviour, which was to drop the
+ * user's rules entirely.
+ *
+ * @internal Exported for testing.
+ */
+export async function writeHeadersFile(
+  dir: string,
+  config: TimberConfig,
+  artifacts: BuildArtifacts
+): Promise<void> {
+  const userRules = await readUserPlatformFile(config.root, HEADERS_FILE);
+  await writeFile(
+    join(dir, HEADERS_FILE),
+    generateHeadersFile({
+      base: adapterBase(config),
+      immutableDirs: artifacts.immutableDirs,
+      // Scanned from the directory being deployed, which holds everything
+      // the platform will serve from it.
+      unhashedPaths: await findUnhashedStaticFiles(dir, artifacts.immutableDirs),
+      contentTypes: artifacts.output === 'static' ? artifacts.contentTypes : undefined,
+      userRules: userRules ?? undefined,
+    })
+  );
+}
+
+/**
+ * Read a user-authored platform file from the project's `public/` directory.
+ * Returns null when the project has none, or when no root is configured —
+ * a caller without a root cannot locate the project at all, and inventing
+ * one from `process.cwd()` would read a different project's file.
+ */
+async function readUserPlatformFile(
+  root: string | undefined,
+  name: string
+): Promise<string | null> {
+  if (!root) return null;
+  try {
+    return await readFile(join(root, USER_PLATFORM_DIR, name), 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Throw if copying `srcDir` over `destDir` would overwrite an existing file.
+ *
+ * Compared against the destination **as it stands**, not against the other
+ * source tree: the first copy is filtered (client JS is dropped when client
+ * JavaScript is disabled), so the files that are actually there are the only
+ * ones a second copy can clobber.
+ *
+ * @internal Exported for testing.
+ */
+export async function assertNoTreeCollision(srcDir: string, destDir: string): Promise<void> {
+  const [srcFiles, destFiles, identity] = await Promise.all([
+    collectFiles(srcDir).catch(() => [] as string[]),
+    collectFiles(destDir).catch(() => [] as string[]),
+    // `cp` will resolve these paths the way the destination filesystem does,
+    // so the comparison predicting it has to as well: on macOS a hand-written
+    // `public/About/index.html` and a generated `about/index.html` are one
+    // file, and an exact-string set waves the overwrite through (TIM-1266).
+    detectFsIdentity(destDir),
+  ]);
+
+  const key = (p: string) => fsKey(p, identity);
+  const existing = new Set(destFiles.map((f) => key(relative(destDir, f).replace(/\\/g, '/'))));
+  const exempt = new Set(USER_MERGED_PLATFORM_FILES.map(key));
+  const collisions = srcFiles
+    .map((f) => relative(srcDir, f).replace(/\\/g, '/'))
+    .filter((rel) => existing.has(key(rel)) && !exempt.has(key(rel)))
+    .sort();
+
+  if (collisions.length === 0) return;
+
+  throw new Error(
+    `[timber] Build output: ${collisions.length} file(s) in the pre-rendered site ` +
+      `collide with files already in the output directory. Copying would silently ` +
+      `overwrite them — a generated page and a file in public/ cannot share a path:\n` +
+      collisions.map((c) => `  - ${c}`).join('\n')
+  );
+}
+
+async function collectFiles(dir: string): Promise<string[]> {
+  const result: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...(await collectFiles(fullPath)));
+    } else {
+      result.push(fullPath);
+    }
+  }
+  return result;
+}

package/src/adapters/canonicalize-module.ts

@@ -0,0 +1,29 @@
+// Compiles server/canonicalize.ts into a standalone ESM module
+// (_canonicalize.mjs) for the Nitro preview server, so preview answers a
+// request path exactly as the runtime's request boundary does — the same
+// rejections (encoded separators, null bytes, malformed encoding, escaping
+// the root) and the same single decode — instead of a hand-kept copy of
+// those rules drifting from them. Same mechanism as compress-module.ts:
+// type-stripped, not bundled, so the source must stay import-free.
+
+import { transformWithOxc } from 'vite';
+// Vite's ?raw import embeds the file as a string at build time (see
+// compress-module.ts).
+import canonicalizeSource from '../server/canonicalize.ts?raw';
+import { assertStandalone } from './compress-module.ts';
+
+/**
+ * Compile server/canonicalize.ts into a standalone ESM module exporting
+ * `canonicalize`.
+ *
+ * @internal Exported for testing.
+ */
+export async function generateCanonicalizeModule(): Promise<string> {
+  const result = await transformWithOxc(canonicalizeSource, '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
+  );
+}