@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/docs/more/01-advanced-routing.mdx

@@ -67,7 +67,7 @@ This is useful for CDN-cacheable file-extension routes (e.g. image generation en
 - One param per segment — `[foo]-[bar]` is not supported
 - Affixes cannot be used with catch-all (`[...slug].png`) or optional catch-all segments
 - Matching is greedy: `[id].png` matching `a.png.png` yields `id = "a.png"`
-- `params.ts` codecs use the bare param name (`id`), not the full segment pattern
+- `app/schema.ts` codecs use the bare bracket form (`[id]`), not the full segment pattern
 
 **Priority:** static → affixed dynamic → bare dynamic → catch-all → optional catch-all. A static `foo.png` always wins over `[id].png`.
 
@@ -112,11 +112,28 @@ export default function DashboardLayout({
 
 Slots don't add URL depth. Each slot independently matches the current URL and can have its own `access.ts`, `error.tsx`, and layouts. If a slot's access check fails, the slot degrades gracefully — the rest of the page is unaffected (see [Access Control](/docs/access-control)).
 
-Each slot is also its own collision space: a slot page sharing a URL with the parent page is the point of parallel routes, but two route groups inside one slot producing pages at the same URL (`@side/(a)/x/page.tsx` + `@side/(b)/x/page.tsx`) fail the build, just like the same collision outside a slot.
+**A slot cannot be nested inside another slot.** Slots are resolved for segments on the matched route chain, and a slot's own subtree is not on that chain — so a nested slot could never render, and the build rejects it:
+
+```
+app/dashboard/layout.tsx                     ← receives { children, sidebar }
+app/dashboard/@sidebar/page.tsx              ✓
+app/dashboard/settings/layout.tsx            ← receives { children, panel }
+app/dashboard/settings/@panel/page.tsx       ✓ a second slot deeper on the main chain
+app/dashboard/@sidebar/@panel/page.tsx       ✗ build error — nested inside @sidebar
+app/dashboard/@sidebar/settings/@panel/...   ✗ build error — same, further down
+```
+
+This is a build error rather than a documented limit because nothing at request time could tell you: a slot that never rendered looks exactly like a slot that simply didn't match. Put the second slot on a segment of the main route chain instead.
+
+Note the `layout.tsx` beside each slot. A slot is handed to its owning segment's layout as a named prop, so **the owner must have one** — `app/dashboard/@sidebar/` with no `app/dashboard/layout.tsx` has nothing to be passed to and never renders. That case is dead in the same way as a nested slot, and the build does not currently catch it.
+
+Each slot is also its own collision space: a slot page sharing a URL with the parent page is the point of parallel routes, but two pages inside one slot that answer the same URL (`@side/(a)/x/page.tsx` + `@side/(b)/x/page.tsx`) fail the build, just like the same collision outside a slot. Interceptors that start at the same URL are their own space on the same principle — see [Intercepting routes](#intercepting-routes).
+
+Every collision space is checked the same way: routes are compared by the URLs they match rather than by how they are spelled, so `(a)/[id]` and `(b)/[slug]` collide even though their paths read differently, and a page collides with an optional catch-all beside it because `[[...rest]]` also matches with zero segments. Segment kinds stay distinct — `[id]` beside `[...rest]`, or an affixed `img-[id]` beside a bare `[slug]`, are ordered deterministically and keep building.
 
 ## Intercepting Routes
 
-Intercepting routes show a different component on soft navigation (client-side link click) vs hard navigation (direct URL). This enables the modal pattern:
+Intercepting routes show a different component on soft navigation (client-side link click) vs hard navigation (direct URL).
 
 | Marker     | Meaning       |
 | ---------- | ------------- |
@@ -125,6 +142,159 @@ Intercepting routes show a different component on soft navigation (client-side l
 | `(..)(..)` | Two levels up |
 | `(...)`    | Root level    |
 
+Where you put the intercepting directory picks between two behaviours.
+
+**Inside a parallel slot → modal overlay.** The slot renders the intercepting page on top; the page you came from stays mounted behind it.
+
+```
+app/feed/@modal/(.)photo/[id]/page.tsx   ← soft nav: modal over the feed
+app/feed/photo/[id]/page.tsx             ← hard nav: the full page
+```
+
+**As a plain child of a segment or route group → sibling layout swap.** No overlay and no slot: the intercepting page replaces the content of *its own* directory's layout chain. This is how two route groups can serve one URL with different layouts.
+
+```
+app/(landing)/layout.tsx
+app/(landing)/[artistSlug]/[year]/page.tsx      ← hard nav renders this
+app/(browse)/layout.tsx
+app/(browse)/(...)[artistSlug]/[year]/page.tsx  ← soft nav from inside (browse) renders this
+```
+
+Navigate directly to `/grateful-dead/1977` and you get `(landing)`'s page under `(landing)`'s layout. Click a link to it from anywhere inside `(browse)` and you stay in `(browse)`'s layout with the intercepting page beneath it. Unlike the modal shape, the intercepting page's params come from the URL you navigated to, so `getSegmentParams()` works exactly as it does on a canonical route.
+
+An intercepting directory must be a **direct** child of one or the other. A marker one directory deeper inside a slot, or nested inside another intercepting subtree, would match the navigation and then have nothing to render — the build fails naming the directory rather than silently serving the wrong page.
+
+```
+app/feed/@modal/(.)photo/[id]/page.tsx   ✓ modal overlay
+app/feed/(.)photo/[id]/page.tsx          ✓ layout swap (feed/layout.tsx required)
+app/(browse)/(...)photo/[id]/page.tsx    ✓ layout swap, scoped to (browse)
+app/feed/@modal/(x)/(.)photo/page.tsx    ✗ build error — not a direct slot child
+app/feed/(.)a/(.)b/page.tsx              ✗ build error — nested interception
+```
+
+Outside a slot, the directory holding the marker must have a `layout.tsx`. That is the directory the swap is scoped to, and the browser reports which directories it has mounted from its layouts — a scope it cannot report would let the swap fire once and then quietly stop. In practice you already have one, since rendering inside that layout is the point.
+
+```
+app/(browse)/layout.tsx                  ✓ required
+app/(browse)/(...)photo/[id]/page.tsx
+```
+
+Also outside a slot, every directory above the marker must be a static segment or a route group. The swapped page renders its own layouts against the URL you navigated to, and that URL carries no values for params declared above the marker — so a dynamic ancestor is a build error rather than a layout that renders with a missing param. Put the same interception in a slot if you need one: the modal shape re-matches the source route, which supplies them.
+
+```
+app/(browse)/(...)photo/[id]/page.tsx    ✓
+app/docs/guides/(.)[id]/page.tsx         ✓
+app/[team]/(..)photo/[id]/page.tsx       ✗ build error — [team] is above the marker
+app/[team]/@modal/(.)photo/[id]/page.tsx ✓ a slot supplies [team] from the source route
+```
+
+Two pages that intercept the same URL are a build error when both sit under interceptors that **start at the same URL** — the set timber resolves in one pass. Route groups are transparent here just as they are elsewhere, so two of them under one marker both claim the same target; and two markers that compute the same starting point are the same case one level up. Either way, which page renders would come down to the order the filesystem happens to list them in.
+
+Pages are compared by the URLs they match, not by how you spell them — so param names don't make two dynamic segments different, and an optional catch-all also matches with *zero* segments.
+
+```
+app/feed/(.)photo/(a)/page.tsx           ✗ build error — both intercept /feed/photo
+app/feed/(.)photo/(b)/page.tsx
+
+app/feed/(.)photo/(a)/[id]/page.tsx      ✗ build error — [id] and [slug] match the same URLs
+app/feed/(.)photo/(b)/[slug]/page.tsx
+
+app/feed/(.)photo/(a)/page.tsx           ✗ build error — [[...rest]] also matches zero segments,
+app/feed/(.)photo/(b)/[[...rest]]/page.tsx    so it claims /feed/photo too
+
+app/feed/(.)photo/page.tsx               ✓ a page plus a tail — the page always wins
+app/feed/(.)photo/[[...rest]]/page.tsx        /feed/photo, the catch-all takes the rest
+
+app/feed/(.)photo/(x)/a/page.tsx         ✓ different URLs
+app/feed/(.)photo/(y)/b/page.tsx
+
+app/feed/(.)photo/(x)/[id]/page.tsx      ✓ different kinds — a single segment always
+app/feed/(.)photo/(y)/[...rest]/page.tsx      beats a catch-all, so this is unambiguous
+
+app/feed/@modal/(.)[a]/page.tsx          ✗ build error — two markers, one starting point,
+app/feed/@modal/(.)[b]/page.tsx               same kind: nothing separates them
+
+app/feed/@modal/(.)photo/[id]/page.tsx   ✓ same starting point, different kinds — the
+app/feed/@modal/(.)[albumSlug]/page.tsx       literal `photo` wins, everything else the second
+```
+
+A route group is transparent for matching, so putting a page inside one does not give it a URL of its own:
+
+```
+app/feed/(.)photo/page.tsx               ✗ build error — both are /feed/photo, so the
+app/feed/(.)photo/(a)/page.tsx                one in the group could never render
+```
+
+Interceptors that start at **different** URLs stay legal even when they target one page — `(.)x` beside `(..)x`, or interceptors in two different slots. Those are separate spaces, and the resolver orders them (deepest marker first).
+
+### Dynamic intercepted segments
+
+The marker is a prefix on an ordinary segment name, so the name after it uses the same bracket syntax as anywhere else:
+
+```
+app/gallery/@modal/(.)photo/[id]/page.tsx    # intercepts /gallery/photo/{id}
+app/gallery/@modal/(.)[albumSlug]/page.tsx   # intercepts /gallery/{albumSlug}
+app/gallery/@modal/(.)[...rest]/page.tsx     # intercepts the whole tail
+```
+
+Intercepting siblings in one slot follow the usual priority — static, then dynamic, then catch-all — so `(.)photo/[id]` and `(.)[albumSlug]` can live in the same `@modal` without ambiguity.
+
+Two affixed interceptors are the one case priority cannot separate: `(.)a-[id]` and `(.)[slug]-b` both match `/gallery/a-b` with the same combined affix length, so which modal opened would come down to filesystem order. That fails the build, exactly as it does for ordinary affixed siblings.
+
+One placement fails the build: an interception whose intercepted level lands below a catch-all. Markers count URL segments, and a catch-all matches a number of them that changes per request, so "same level as `/docs/[...path]`" has no fixed position in `/docs/a/b/c`. Such an interception would fire only when the catch-all consumed exactly one segment and be silently dropped otherwise, so timber names the directory in a build error instead. Climbing past the catch-all avoids it:
+
+```
+app/docs/[...path]/@modal/(.)photo/[id]/page.tsx    ✗ build error
+app/docs/[...path]/@modal/(..)photo/[id]/page.tsx   ✓ (..) climbs past it, basing at /docs
+app/docs/[...path]/@modal/(...)photo/[id]/page.tsx  ✓ (...) bases at the root
+app/[artistSlug]/@modal/(.)photo/[id]/page.tsx      ✓ a dynamic segment is one URL part
+```
+
+A catch-all inside an intercepting route must also be the last segment — nothing below a catch-all can ever match, and the rewrite generated for the unreachable page would hijack the navigation with nothing to render:
+
+```
+app/feed/@modal/(.)[...rest]/page.tsx              ✓
+app/feed/@modal/(.)photo/[...rest]/page.tsx        ✓
+app/feed/@modal/(.)[...rest]/child/page.tsx        ✗ build error — child is unreachable
+app/feed/@modal/(.)photo/[...rest]/child/page.tsx  ✗ build error — same, one level down
+```
+
+### Params in intercepting directories
+
+A dynamic intercepted segment binds a param like any other, so the ordinary param rules apply to it:
+
+```
+app/feed/@modal/(.)[id]/[id]/page.tsx      ✗ build error — duplicate param name
+app/feed/@modal/(.)[albumSlug]/[id]/...    ✓
+```
+
+### Params inside an intercepting page
+
+This section is about the **modal** shape. A layout-swap interception has nothing special going on: its chain is the main route, so `getSegmentParams()` returns the URL's params everywhere in it, exactly as on a canonical route.
+
+Inside a slot, `getSegmentParams()` returns **the intercepted route's** params — what the page's own directories declare:
+
+```tsx title="app/gallery/@modal/(.)photo/[id]/page.tsx"
+export default async function PhotoModal() {
+  const { id } = getSegmentParams(); // the photo's id, not the gallery's params
+  return <Modal photo={await getPhoto(id)} />;
+}
+```
+
+That is worth stating because the request itself is matched against the *source* route (`/gallery`) — the page still rendering behind the modal. The modal's own params are scoped to it, and the source page underneath keeps reading its own.
+
+This is the general slot rule: inside a parallel slot, a no-arg `getSegmentParams()` returns that slot's own params merged over the main route's — the same value as passing the slot's segment path explicitly. Params the slot re-derives win, so a slot that reads a URL part as `[...year]` gets `string[]` even when the main route read it as `[year]`.
+
+### Scope
+
+An interception fires only when the departing page renders the directory that owns it — the slot's parent for a modal, the marker's own parent for a layout swap. For `app/feed/@modal/(.)photo/`, that directory is `/feed`: clicking a photo link from `/feed` or `/feed/trending` opens the modal; clicking one from `/settings` does not.
+
+Route groups count here even though they are invisible in the URL. Anything owned by `app/(browse)/` is scoped to `(browse)`, so a navigation starting in a sibling `(landing)` group renders the normal route, not the interception — that is what makes the layout-swap shape work. A directory at the app root is scoped to the root, which every page renders, which is why `(...)` at the root intercepts from anywhere.
+
+**When two interceptions both apply, the innermost one wins.** A directory and a directory beneath it may each hold a marker for the same URL, and a page inside the inner one renders both — so `app/feed/(.)photo/` and `app/feed/(a)/(.)photo/` both qualify for a click made inside `(a)`. The one scoped to `(a)` renders, on the same reasoning that a `(.)` marker beats a `(...)` one beside it: the more local directory is the more specific statement. Directories that are *not* on one chain — `(a)` beside `(b)` — never both qualify, so they stay independent.
+
+Because scope depends on where the click starts, so does a prefetch: `<Link prefetch>` fetches the variant for the page the link is on, and the cached payload is only used by a click that starts there. Hovering an intercepting link gets you the modal; the same URL prefetched from elsewhere stays the full page.
+
 ## API Routes
 
 Export HTTP method handlers from `route.ts`:

package/docs/more/03-coming-from-nextjs.mdx

@@ -64,9 +64,9 @@ app/
 
 **Next.js:** `useSearchParams()` hook returns a `URLSearchParams` object.
 
-**timber:** Typed search params via `defineSearchParams` in a `params.ts` file. Server reads via `.get()`, client reads/writes via `.useQueryStates()`. Segment params are defined globally in `app/schema.ts` via `defineSchema()`, accessed with `getSegmentParams(SEGMENT_PATH)` using the `$segment` module.
+**timber:** Typed search params via `defineSearchParams` in any module you import. Server reads via `.get()`, client reads/writes via `.useQueryStates()`. Segment params are defined globally in `app/schema.ts` via `defineSchema()`, accessed with `getSegmentParams(SEGMENT_PATH)` using the `$segment` module.
 
-```ts title="app/products/params.ts"
+```ts title="app/products/search-params.ts"
 import { defineSearchParams } from '@timber-js/app/search-params';
 import { z } from 'zod/v4';
 

package/docs/more/04-metadata-and-fonts.mdx

@@ -91,7 +91,7 @@ If you declare `openGraph.images` in your metadata, both auto-linked tags are su
 
 `favicon.tsx` lets you generate favicons dynamically (e.g. tenant branding). The URL stays `/favicon.ico` for browser compatibility.
 
-For OG image generation, use `@takumi-rs/image-response` (BYO package — not bundled with timber):
+For OG image generation, use `takumi-js/response` (BYO package — not bundled with timber):
 
 ```tsx title="app/opengraph-image.tsx"
 import { ImageResponse } from 'takumi-js/response';

package/docs/more/50-ai-agent-instructions.mdx

@@ -59,7 +59,7 @@ These are the things you will get wrong if you assume Next.js behavior.
 | Middleware | Single global `middleware.ts` with matchers | Per-segment `middleware.ts` files + global `proxy.ts`. One-arg signature: `middleware(ctx)`. |
 | `notFound()` | `notFound()` from `next/navigation` | `deny(404)` from `@timber-js/app/server`. Sends a real HTTP 404. |
 | `redirect()` | `redirect()` from `next/navigation` | `redirect()` from `@timber-js/app/server`. Same concept, different import. |
-| Search params | Untyped `useSearchParams()` | Typed `defineSearchParams()` with Zod schemas in `params.ts`. |
+| Search params | Untyped `useSearchParams()` | Typed `defineSearchParams()` with Zod schemas, in any module you import. |
 | Auth pattern | In middleware or components | `access.ts` per segment with slot degradation. |
 | Forms | `useFormState` / `useFormStatus` | `createActionClient` + `useActionState` returns a 4-tuple. Forms work without JS. |
 
@@ -71,7 +71,7 @@ These are the things you will get wrong if you assume Next.js behavior.
 | `Link`, `useRouter`, `usePathname`, `useActionState` | `@timber-js/app/client` |
 | `cache`, `CacheHandler` | `@timber-js/app/cache` |
 | `defineSearchParams` | `@timber-js/app/search-params` |
-| `defineSchema`, `defineSegmentParams` | `@timber-js/app/params` |
+| `defineSchema`, `InferCodecType` | `@timber-js/app/params` |
 | Content collection data | `content-collections` |
 | `Metadata` type | `@timber-js/app/server` |
 
@@ -90,7 +90,7 @@ app/                    # Route tree — file-system routing
     access.ts           # Per-segment authorization
     denied.tsx          # Rendered when access.ts denies
     error.tsx           # Error boundary for this segment
-    params.ts           # Search param definitions
+    search-params.ts    # Search param definitions (ordinary module, not a convention)
   schema.ts             # Segment param schemas (from @timber-js/app/params)
 content/                # Content collections (outside route tree)
 timber.config.ts        # Framework configuration
@@ -104,6 +104,8 @@ content-collections.ts  # Collection definitions (optional)
 
 2. **Adding `'use client'` to everything** — components are server components by default. Only add `'use client'` when you need browser APIs, event handlers, or React hooks like `useState`/`useEffect`.
 
+   The exception: `error.tsx`, `global-error.tsx`, and component status files (`404.tsx`, `4xx.tsx`, `503.tsx`, …) **always** need `'use client'`. timber passes them to a client error boundary as a prop, so a server component there breaks every page under that segment. The build rejects it and names the file. MDX status files (`404.mdx`) are exempt.
+
 3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache.data()` from `@timber-js/app/cache` when you want caching.
 
 4. **Creating `loading.tsx` files** — this convention does not exist. Use `<Suspense>` with an explicit fallback where you want streaming.
@@ -114,7 +116,7 @@ content-collections.ts  # Collection definitions (optional)
 
 7. **Putting all middleware in one file** — middleware is per-segment. Place `middleware.ts` at the route level that matches the concern. Use `proxy.ts` for global concerns.
 
-8. **Assuming `useSearchParams()` exists** — use `defineSearchParams()` in a `params.ts` file with Zod schemas, then access via `.get()` (server) or `.useQueryStates()` (client).
+8. **Assuming `useSearchParams()` exists** — use `defineSearchParams()` in any module with Zod schemas, then access via `.get()` (server) or `.useQueryStates()` (client).
 
 ## Quick Patterns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.185",
+  "version": "0.2.0-alpha.187",
   "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",
@@ -113,10 +113,6 @@
       "types": "./dist/search-params/index.d.ts",
       "import": "./dist/search-params/index.js"
     },
-    "./segment-params": {
-      "types": "./dist/segment-params/index.d.ts",
-      "import": "./dist/segment-params/index.js"
-    },
     "./params": {
       "types": "./dist/params/index.d.ts",
       "import": "./dist/params/index.js"
@@ -165,6 +161,7 @@
     "@content-collections/mdx": "^0.2.0",
     "@content-collections/vite": "^0.2.0 || ^0.3.0",
     "@mdx-js/rollup": "^3.0.0",
+    "@typescript/native-preview": "^7.0.0-dev.0",
     "@vitejs/plugin-react": "^6.0.0",
     "@vitejs/plugin-rsc": ">=0.5.28",
     "nuqs": "^2.0.0",
@@ -187,6 +184,9 @@
     "@mdx-js/rollup": {
       "optional": true
     },
+    "@typescript/native-preview": {
+      "optional": true
+    },
     "wrangler": {
       "optional": true
     },
@@ -194,12 +194,15 @@
       "optional": true
     }
   },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2"
+  },
   "engines": {
     "node": ">=22.18.0"
   },
   "scripts": {
     "copy-docs": "node scripts/copy-docs.js",
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist && pnpm run copy-docs",
+    "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

@@ -13,7 +13,16 @@
 
 import { writeFile, mkdir, cp, rm, readdir, readFile } from 'node:fs/promises';
 import { join, basename, relative } from 'node:path';
-import { generateHeadersFile } from './shared.js';
+import { adapterBase, generateHeadersFile } from './shared.js';
+// 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.js';
+import { detectFsIdentity, fsKey } from './fs-identity.js';
 import type { TimberConfig } from './types';
 
 /** Options for the shared build output steps. */
@@ -77,8 +86,7 @@ export async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise
   // 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.
-  const unhashedPaths = await findUnhashedStaticFiles(publicDir);
-  await writeFile(join(publicDir, '_headers'), generateHeadersFile(unhashedPaths));
+  await writeHeadersFile(publicDir, config, await findUnhashedStaticFiles(publicDir));
 
   // 4. Copy RSC + SSR server bundles into the output directory.
   await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
@@ -218,11 +226,116 @@ export async function buildStaticDirectoryOutput(
   });
 
   // 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).
   if (config.staticPagesDir) {
+    await assertNoTreeCollision(config.staticPagesDir, publicDir);
     await cp(config.staticPagesDir, 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,
+  unhashedPaths: string[]
+): Promise<void> {
+  const userRules = await readUserPlatformFile(config.root, HEADERS_FILE);
+  await writeFile(
+    join(dir, HEADERS_FILE),
+    generateHeadersFile({
+      base: adapterBase(config),
+      unhashedPaths,
+      contentTypes: config.staticContentTypes,
+      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 });

package/src/adapters/cloudflare.ts

@@ -13,8 +13,16 @@ import {
   runSharedBuildSteps,
   findUnhashedStaticFiles,
   buildStaticDirectoryOutput,
+  writeHeadersFile,
 } from './build-output-helper.js';
-import { generateHeadersFile } from './shared.js';
+import { adapterBase, generateHeadersFile } from './shared.js';
+// 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 { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.js';
+// Same reasoning: the media type the origin's own RSC gate matches on, so the
+// two predicates cannot drift apart. See `shared/rsc-media-type.ts`.
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 
 // ─── Bindings passthrough ─────────────────────────────────────────────────
 // ALS stores the env object per-request so server components and middleware
@@ -409,15 +417,79 @@ function initPlatformTracer() {
   return tracerInit
 }
 
+// The \`Vary\` tokens this cache can serve a correct answer for.
+//
+// Cloudflare's Cache API keys on the request URL. It does not implement
+// RFC 9111 §4.1 secondary key selection, so a stored response is handed to
+// every request for that URL regardless of what \`Vary\` nominates — except
+// \`Accept-Encoding\`, which the platform segregates itself. Storing a
+// response whose \`Vary\` says "this answer is specific to header H" under a
+// key that ignores H is cross-client reuse (TIM-1269): a developer writing
+// the correct \`public, s-maxage=60\` + \`Vary: Cookie\` gets their logged-in
+// page served to anonymous visitors. Refusing to store is the conservative
+// answer, and the only one available without rewriting the key.
+//
+// The framework's own tokens are on this list because the adapter already
+// segregates them, more strictly than \`Vary\` would:
+//
+//   - \`Accept\` — \`isRsc\` above excludes \`text/x-component\` from both lookup
+//     and store, so the HTML/Flight split \`Vary: Accept\` exists to protect
+//     never reaches this cache in the first place.
+//   - \`X-Timber-State-Tree\`, \`X-Timber-URL\`, \`X-Timber-Deployment-Id\` — the
+//     origin reads all three only on RSC requests (version skew at
+//     \`server/pipeline-phases.ts\`, interception rewrites likewise, state-tree
+//     diffing at \`server/rsc-entry/render-route.ts\`). On the non-RSC requests
+//     this cache stores, they cannot change the response.
+//
+// That second bullet is a coupling, not an observation: if any of those
+// headers ever starts varying a document response, this list is wrong and
+// the cache poisons. Because the list is derived, a header added to
+// \`RSC_KEY_HEADERS\` inherits the exemption silently — so
+// \`tests/adapters/cloudflare-vary.test.ts\` fails until that header is named
+// there alongside the evidence for its gate, and the gates themselves are
+// covered there, in \`tests/render-route.test.ts\`, and in
+// \`tests/interception-x-timber-url.test.ts\`.
+//
+// Interpolated from \`RSC_KEY_HEADERS\` rather than spelled again — "which
+// headers vary an RSC response" has one answer, and a hand-copied second
+// list here would drift silently on the fallback path nobody exercises.
+//
+// Known residual: a route handler that content-negotiates on \`Accept\`
+// (JSON vs HTML) *and* marks itself \`public\` is still mis-keyed, because the
+// \`isRsc\` split is binary and does not separate those two. That is no worse
+// than the pre-TIM-1269 behaviour, which stored every \`Vary\` but \`*\`.
+const VARY_HONORED = new Set(${JSON.stringify(['accept-encoding', ...RSC_KEY_HEADERS.map((h) => h.toLowerCase())])})
+
+// Applied to BOTH sides of the cache — what may be stored, and what a hit
+// may serve. Refusing to store only stops new poisoning: entries a previous
+// deployment wrote under the old predicate stay servable for whatever
+// s-maxage the developer chose, which can be a day. Checking on the way out
+// makes the fix take effect on deploy rather than on expiry, and costs one
+// header read per hit. A rejected entry falls through to the origin and is
+// then declined by the same predicate on the way back in, so it is not
+// rewritten — it simply ages out.
+function canHonorVary(vary) {
+  // Absent or empty Vary nominates nothing — the URL is the whole key.
+  if (!vary) return true
+  return vary.split(',').every((token) => VARY_HONORED.has(token.trim().toLowerCase()))
+}
+
 export default {
 ${handlersSpread}  async fetch(request, env, ctx) {
     // One-time on first request; resolved-promise await thereafter.
     await initPlatformTracer()
 
     // Edge-cache GET/HEAD responses via the Cache API. RSC navigation
-    // requests (Accept: text/x-component) are excluded — they vary by
-    // X-Timber-State-Tree which the cache key doesn't capture.
-    const isRsc = request.headers.get('Accept')?.includes('text/x-component')
+    // requests (Accept: text/x-component) are excluded. Their varying
+    // inputs are now in the URL via ?_rsc= (TIM-1268), but this cache keys
+    // on the request URL alone and cannot honour Vary, so a payload request
+    // that arrives without the param — stripped query, hand-rolled client —
+    // would share a key with the document.
+    //
+    // This exclusion is load-bearing in the other direction too: the store
+    // predicate below treats "Vary: Accept" as honoured *because* of it
+    // (see VARY_HONORED). Removing it would make that allowlist unsound.
+    const isRsc = request.headers.get('Accept')?.includes(${JSON.stringify(RSC_CONTENT_TYPE)})
     const reqCc = request.headers.get('Cache-Control') || ''
     const bypassCache = reqCc.includes('no-cache') || reqCc.includes('max-age=0')
         || request.headers.has('Pragma')
@@ -426,7 +498,17 @@ ${handlersSpread}  async fetch(request, env, ctx) {
     const cache = cacheable && typeof caches !== 'undefined' ? caches.default : null
     if (cache) {
       const cached = await cache.match(request)
-      if (cached) return cached
+      // A hit whose Vary this cache cannot key on is treated as a miss —
+      // see canHonorVary. Entries written before that predicate existed are
+      // exactly the ones that would be served to the wrong client.
+      if (cached) {
+        if (canHonorVary(cached.headers.get('Vary'))) return cached
+        // Declining the hit means nobody will ever read this body. Release
+        // it rather than leaving the stream dangling for the rest of the
+        // request (design/02-rendering-pipeline.md §"Cancel Readers When You
+        // No Longer Need the Stream").
+        cached.body?.cancel().catch(() => {})
+      }
     }
 
     // Bridge ctx.cache into the per-request ALS so WorkersCachePurge can
@@ -449,10 +531,10 @@ ${handlersSpread}  async fetch(request, env, ctx) {
     // See design/25-production-deployments.md §"CDN / Edge Cache".
     if (cache && request.method === 'GET' && response.status === 200) {
       const cc = response.headers.get('Cache-Control')
-      const vary = response.headers.get('Vary')
       if (cc && !cc.includes('no-store') && !cc.includes('private')
           && (cc.includes('public') || cc.includes('s-maxage'))
-          && vary !== '*' && !response.headers.has('Set-Cookie')) {
+          && canHonorVary(response.headers.get('Vary'))
+          && !response.headers.has('Set-Cookie')) {
         ctx.waitUntil(cache.put(request, response.clone()))
       }
     }
@@ -804,11 +886,7 @@ export async function buildStaticOutput(
   await buildStaticDirectoryOutput(config, buildDir, outDir, '.');
 
   // Write _headers file for cache control + content-type rules.
-  const unhashedPaths = await findUnhashedStaticFiles(outDir);
-  await writeFile(
-    join(outDir, '_headers'),
-    generateHeadersFile(unhashedPaths, config.staticContentTypes)
-  );
+  await writeHeadersFile(outDir, config, await findUnhashedStaticFiles(outDir));
 }
 
 // ─── Preview ─────────────────────────────────────────────────────────────────