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

package/dist/shared/static-platform-files.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Platform files the static build is allowed to overwrite in the output.
+ *
+ * The build merges two trees into the deployed directory — the client bundle
+ * (which carries everything the user put in `public/`) and the pre-rendered
+ * site. That merge otherwise refuses overlaps, because a silent overwrite
+ * leaves one of two artifacts deployed with nothing recording which
+ * (TIM-1266).
+ *
+ * These names are the exception, and only because the pre-rendered copy is
+ * *derived from* the one it replaces rather than competing with it:
+ * `plugins/static-build.ts` reads `public/_redirects` and writes the
+ * generated rules plus the user's, so the winner is a superset of the loser.
+ *
+ * That holds only for a file the current pass produced, which is why
+ * `cleanConditionalArtifacts` deletes a previous build's `_redirects` before
+ * generation: written only when a pass finds redirects, it would otherwise
+ * survive into a pass that produced nothing and claim an exemption it no
+ * longer earns.
+ *
+ * `_headers` is NOT here. It is not written into the pre-rendered tree at
+ * all — adapters generate it directly into the output, folding in the
+ * user's copy as they go (TIM-1326).
+ *
+ * Declared once so the code that performs the merge and the code that
+ * produces the merged file cannot disagree about which names are exempt.
+ *
+ * Isomorphic: no server, client, or build-time imports.
+ */
+/** Platform redirect rules (Cloudflare Pages, Netlify). See TIM-1245/TIM-1249. */
+export declare const REDIRECTS_FILE = "_redirects";
+/** Platform header rules (Cloudflare Pages, Netlify). See TIM-1241/TIM-1326. */
+export declare const HEADERS_FILE = "_headers";
+/**
+ * Where a user authors platform files. Stated once because two modules read
+ * from here — `plugins/static-build.ts` for `_redirects`, adapters for
+ * `_headers` — and they must look in the same place.
+ *
+ * Both read the **project source**, never the build output. The generated
+ * file lands under the same name in the output directory, so a reader aimed
+ * there would fold the previous build's generated rules back in and compound
+ * them on every rebuild.
+ */
+export declare const USER_PLATFORM_DIR = "public";
+/** Output-relative paths whose pre-rendered copy subsumes the `public/` one. */
+export declare const USER_MERGED_PLATFORM_FILES: readonly string[];
+/**
+ * Output paths the framework writes itself, which no route may claim.
+ *
+ * These are written outside the per-entry writer — `_redirects` after
+ * generation, `_headers` by the adapter after the copy — so the collision
+ * tracker never sees them and a route rendering to one of these paths is
+ * overwritten with nothing recording it.
+ *
+ * Reserved rather than tracked, because there is no version of "serve a route
+ * at `/_headers`" that works: Cloudflare Pages and Netlify read these two
+ * files themselves and never serve them, so the route is unservable however
+ * the conflict is resolved.
+ *
+ * That justification is per-file, not per-mechanism. `.nojekyll` is written
+ * the same way and is deliberately NOT here: only the `github-pages` target
+ * writes it, and everywhere else `/.nojekyll` is an ordinary servable path,
+ * so reserving it globally would refuse a valid Cloudflare site. Its write
+ * site skips the write when a file is already there instead — GitHub Pages
+ * only cares that the file exists.
+ *
+ * Same reasoning as the synthetic 404 entry using an internal urlPath so a
+ * real `/404` route cannot collide with `404.html`.
+ */
+export declare const RESERVED_OUTPUT_PATHS: readonly string[];
+//# sourceMappingURL=static-platform-files.d.ts.map

package/dist/shared/static-platform-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-platform-files.d.ts","sourceRoot":"","sources":["../../src/shared/static-platform-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,kFAAkF;AAClF,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C,gFAAgF;AAChF,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAqB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAmC,CAAC"}

package/docs/api/31-api-client.mdx

@@ -28,7 +28,7 @@ import { Link } from '@timber-js/app/client';
 | ------------ | ------------------- | ------------------------------------------- |
 | `href`       | `string`            | Target URL (type-checked against route map) |
 | `replace`    | `boolean`           | Use `replaceState` instead of `pushState`   |
-| `prefetch`   | `boolean`           | Prefetch on hover/viewport                  |
+| `prefetch`   | `boolean`           | Prefetch the RSC payload on hover           |
 | `onNavigate` | `OnNavigateHandler` | Intercept navigation before routing         |
 
 ### `<TimberErrorBoundary>`
@@ -60,6 +60,8 @@ router.forward();
 | `back()`        | Go back                            |
 | `forward()`     | Go forward                         |
 
+If the server answers a navigation or a `refresh()` with an error, the router hands the URL back to the server as a full page load so it can render the error page as HTML with the right status code. That applies to back/forward too. None of these methods report the failure to your code — there is nothing to catch, and nothing to render a fallback for.
+
 ### `usePathname()`
 
 Returns the current pathname as a string.
@@ -97,7 +99,7 @@ const pending = usePendingNavigation();
 Per-link pending state. Must be used inside a `<Link>` component's children.
 
 ```tsx
-const { pending } = useLinkStatus();
+const { isPending } = useLinkStatus();
 ```
 
 ### `useSegmentParams(segmentPath?)`

package/docs/learn/02-pages-and-layouts.mdx

@@ -140,7 +140,7 @@ app/
 timber produces build errors for ambiguous route configurations:
 
 - **Duplicate convention files** — `page.tsx` and `page.jsx` in the same directory is an error, not a silent winner-by-filesystem-order
-- **Route group collisions** — two route groups in the same slot that both define a page for the same URL path are caught at build time
+- **Route collisions** — two pages (or a page and a `route.ts`) that answer the same URL are caught at build time. Routes are compared by the URLs they match, not by how they are spelled: `x/(a)/[id]/page.tsx` and `x/(b)/[slug]/page.tsx` collide, and so do `x/(a)/page.tsx` and `x/(b)/[[...rest]]/page.tsx`, since an optional catch-all also matches with zero segments. Different segment _kinds_ don't collide — `[id]` beside `[...rest]` is ordered deterministically and keeps building
 
 This behavior is deterministic regardless of filesystem `readdir` order. In Next.js, the result of these ambiguities depends on the OS and filesystem, which can produce different behavior between local development and CI.
 

package/docs/learn/11-error-handling.mdx

@@ -73,6 +73,8 @@ Priority order (innermost to outermost):
 3. `error.tsx` — catches anything unmatched
 4. Parent segments → framework default
 
+If nothing in the chain matches, timber renders a built-in status page: a plain document with the status code and its reason phrase, and nothing else — no request URL, no error message. It is what a static build writes to `404.html` when your app has no not-found page, so a static deploy always ships one. Add a root `app/404.tsx` (or `4xx.tsx` / `error.tsx`) to replace it.
+
 ## `error.tsx`
 
 The general error boundary. It's a client component:

package/docs/learn/12-client-navigation.mdx

@@ -93,8 +93,8 @@ Track per-link pending state during navigation:
 import { Link, useLinkStatus } from '@timber-js/app/client';
 
 function NavItemInner({ children }: { children: React.ReactNode }) {
-  const { pending } = useLinkStatus();
-  return <span className={pending ? 'opacity-50' : ''}>{children}</span>;
+  const { isPending } = useLinkStatus();
+  return <span className={isPending ? 'opacity-50' : ''}>{children}</span>;
 }
 
 export function NavItem({ href, children }: { href: string; children: React.ReactNode }) {

package/docs/learn/14-deploying.mdx

@@ -200,6 +200,29 @@ export default {
 
 Pre-renders every route to HTML at build time. Add `clientJavascript: false` for zero-JavaScript output. Deploy to any static file host — S3, CloudFront, Cloudflare Pages, GitHub Pages, Netlify, or any HTTP server.
 
+### Serving from a sub-path
+
+To deploy under a path instead of a domain root — `https://user.github.io/repo/` on GitHub Pages, for example — set Vite's `base`:
+
+```ts title="vite.config.ts"
+export default defineConfig({
+  base: '/repo/',
+  plugins: [timber()],
+});
+```
+
+Every URL timber emits picks up the prefix: client assets, fonts, and the RSC payloads behind client-side navigation.
+
+Your own links are not rewritten. `base` prefixes emitted assets, not application URLs, so an `href` must include the prefix itself:
+
+```tsx
+<Link href={`${import.meta.env.BASE_URL}about`}>About</Link>
+```
+
+A plain `href="/about"` points at the domain root, outside your deployment.
+
+A relative base (`'./'`) can't tell timber where the site lives, so payload URLs fall back to the domain root and client-side navigation degrades to full page loads on a sub-path deployment. The build warns when it sees one — use an absolute base like `'/repo/'`.
+
 ## CDN Integration
 
 timber.js provides typed helpers for CDN caching headers and tag-based purging. CDN caching is always developer-elected — the framework never sets cache headers automatically.

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

@@ -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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.185",
+  "version": "0.2.0-alpha.186",
   "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",
@@ -199,7 +199,7 @@
   },
   "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 });