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

package/src/adapters/cloudflare.ts

@@ -13,8 +13,13 @@ 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';
 
 // ─── Bindings passthrough ─────────────────────────────────────────────────
 // ALS stores the env object per-request so server components and middleware
@@ -409,14 +414,78 @@ 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.
+    // 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('text/x-component')
     const reqCc = request.headers.get('Cache-Control') || ''
     const bypassCache = reqCc.includes('no-cache') || reqCc.includes('max-age=0')
@@ -426,7 +495,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 +528,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 +883,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 ─────────────────────────────────────────────────────────────────

package/src/adapters/fs-identity.ts

@@ -0,0 +1,156 @@
+/**
+ * What the output filesystem considers "the same file".
+ *
+ * Two build steps compare paths to decide whether two artifacts would land on
+ * one file — the render pass (`plugins/static-build.ts`) and the adapter's
+ * tree merge (`build-output-helper.ts`). Both are predicting a filesystem
+ * decision, so both ask the filesystem rather than comparing raw strings
+ * (TIM-1266).
+ *
+ * Two properties matter, and they are independent:
+ *
+ * - **Case folding.** macOS APFS and Windows NTFS fold by default, ext4 does
+ *   not. Dynamic params `Foo` and `foo` are one file on a Mac and two on
+ *   Linux CI.
+ * - **Unicode normalization.** APFS compares normalization-insensitively, so
+ *   `café` spelled NFC (`é`) and NFD (`e` + combining acute) address one
+ *   file. This holds even on a *case-sensitive* APFS volume, which is why it
+ *   is probed separately rather than inferred from case folding.
+ *
+ * Probed rather than read off `process.platform`: a case-sensitive volume on
+ * macOS and a case-insensitive mount on Linux are both ordinary, and the
+ * answer that matters is the one for the directory being written.
+ *
+ * Leaf module — Node built-ins only. Deliberately not in `adapters/shared.ts`,
+ * which `server/asset-headers.ts` re-exports from and which therefore must
+ * stay free of `node:fs` for the Workers bundle.
+ */
+
+import { writeFile, stat, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+
+/** How the output filesystem decides that two paths name one file. */
+export interface FsIdentity {
+  /** `Foo` and `foo` are the same file. */
+  caseInsensitive: boolean;
+  /** Canonically equivalent Unicode spellings are the same file. */
+  normalizationInsensitive: boolean;
+  /**
+   * Trailing dots and spaces are stripped from each segment, so `foo.` and
+   * `foo` are the same file. Win32 does this in path resolution rather than
+   * in the filesystem, which is why it is probed like the others.
+   */
+  stripsTrailingDotsAndSpaces: boolean;
+}
+
+/** Every path comparison is exact — the conservative answer when unprobed. */
+export const EXACT_FS_IDENTITY: FsIdentity = {
+  caseInsensitive: false,
+  normalizationInsensitive: false,
+  stripsTrailingDotsAndSpaces: false,
+};
+
+/**
+ * Probe `dir` by writing one file and asking for it under other spellings.
+ *
+ * Returns {@link EXACT_FS_IDENTITY} when the probe cannot run. That
+ * under-detects, but a directory this cannot write to is one the caller is
+ * about to fail on anyway, with a clearer error than a missed collision.
+ */
+export async function detectFsIdentity(dir: string): Promise<FsIdentity> {
+  // `café` — NFC, with a precomposed é. The UUID contributes the
+  // hex letters the case probe needs.
+  const name = `.timber-probe-${randomUUID()}-café`;
+  const path = join(dir, name);
+
+  try {
+    await writeFile(path, '');
+    const [caseInsensitive, normalizationInsensitive, stripsTrailingDotsAndSpaces] =
+      await Promise.all([
+        exists(join(dir, name.toUpperCase())),
+        // NFD spells the same string as `e` + U+0301; a filesystem that
+        // resolves it to the NFC file compares normalization-insensitively.
+        exists(join(dir, name.normalize('NFD'))),
+        // Win32 strips trailing dots and spaces during path resolution, so
+        // asking for `name.` reaches `name`.
+        exists(join(dir, `${name}.`)),
+      ]);
+    return { caseInsensitive, normalizationInsensitive, stripsTrailingDotsAndSpaces };
+  } catch {
+    return EXACT_FS_IDENTITY;
+  } finally {
+    await rm(path, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Fold a path to the identity the filesystem compares it under.
+ *
+ * Normalization first, then case: `toLowerCase()` operates per code point, so
+ * folding a decomposed string first would leave the combining marks in a
+ * different order than folding a precomposed one.
+ *
+ * An approximation of the filesystem's own algorithm — APFS and NTFS fold per
+ * their own Unicode tables, which `toLowerCase()` matches for everything short
+ * of the exotic. It errs toward *finding* a collision, and the cost of a false
+ * positive is a build error naming two routes rather than a silent overwrite.
+ */
+export function fsKey(path: string, identity: FsIdentity): string {
+  let key = identity.caseInsensitive ? caseFold(path) : path;
+  if (identity.normalizationInsensitive) key = key.normalize('NFC');
+  if (identity.stripsTrailingDotsAndSpaces) key = key.split('/').map(stripTrailing).join('/');
+  return key;
+}
+
+/**
+ * Approximate Unicode case folding, which is what case-insensitive
+ * filesystems actually compare under.
+ *
+ * `toLowerCase()` is not it. Greek `σ` and final `ς` are both already
+ * lowercase and stay distinct under it, yet NTFS upcases both to `Σ` and APFS
+ * folds `ς` to `σ` — so two routes differing only in that letter are one file
+ * on both, and a lowercase key admitted them as two claims (TIM-1266).
+ * Uppercasing first collapses them.
+ *
+ * The residual is over-folding, in these cases and a few like them:
+ *
+ * | pair      | folded together here | NTFS / APFS       |
+ * | --------- | -------------------- | ----------------- |
+ * | `σ` / `ς` | yes                  | yes — the fix     |
+ * | `ß` / `ss`| yes                  | no                |
+ * | `ı` / `i` | yes                  | no                |
+ * | `fi` / `fi`| yes                  | no                |
+ *
+ * That direction is deliberate. Over-folding costs a build error naming two
+ * routes, which a developer fixes by renaming one; under-folding costs a
+ * payload silently overwritten by another route's, which nothing downstream
+ * can detect. An exact fold would need `Intl.Collator`, which compares but
+ * emits no sort key, so using it would turn a hash lookup into a pairwise
+ * scan over every claimed path.
+ */
+function caseFold(value: string): string {
+  return value.toUpperCase().toLowerCase();
+}
+
+/**
+ * Drop trailing dots and spaces from one path segment, as Win32 does.
+ *
+ * A segment that is nothing but dots and spaces is left alone: `.` and `..`
+ * are traversal, which the caller rejects before reaching here, and emptying
+ * a segment would merge two unrelated paths rather than the aliases this
+ * models.
+ */
+function stripTrailing(segment: string): string {
+  const stripped = segment.replace(/[. ]+$/, '');
+  return stripped === '' ? segment : stripped;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/adapters/nitro.ts

@@ -10,11 +10,12 @@ import { execFile } from 'node:child_process';
 import { join, relative, dirname, basename } from 'node:path';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { generateCompressModule } from './compress-module.js';
-import { IMMUTABLE_CACHE, generateHeadersFile } from './shared.js';
+import { adapterBase, IMMUTABLE_CACHE, generateHeadersFile } from './shared.js';
 import {
   runSharedBuildSteps,
   buildStaticDirectoryOutput,
   findUnhashedStaticFiles,
+  writeHeadersFile,
 } from './build-output-helper.js';
 
 // ─── Presets ─────────────────────────────────────────────────────────────────
@@ -229,15 +230,14 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
 
         // Write _headers for cache control + extensionless Content-Type.
         // Netlify supports the _headers convention just like Cloudflare.
-        const unhashedPaths = await findUnhashedStaticFiles(publicDir);
-        await writeFile(
-          join(publicDir, '_headers'),
-          generateHeadersFile(unhashedPaths, config.staticContentTypes)
-        );
+        await writeHeadersFile(publicDir, config, await findUnhashedStaticFiles(publicDir));
 
         // Platform-specific files for static deploy targets.
         const target = options.staticTarget ?? 'generic';
         if (target === 'github-pages') {
+          // Deploy-from-a-branch runs Jekyll, which drops `_`-prefixed paths —
+          // every `_rsc/` payload. Written unconditionally: GitHub reads only
+          // that the file exists, never its contents.
           await writeFile(join(publicDir, '.nojekyll'), '');
           // GitHub Pages doesn't support _redirects files. Warn if any
           // redirects were generated — those routes will 404 on GH Pages.

package/src/adapters/shared.ts

@@ -8,6 +8,25 @@
 // IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,
 // or any module that transitively depends on Vite. A test in
 // tests/adapters/shared-no-forbidden-imports.test.ts enforces this.
+// ../shared/ is exempt: it is dependency-free by the same rule.
+
+import { withBasePath } from '../shared/base-path.js';
+
+/**
+ * The deployment base an adapter should write platform rules against.
+ *
+ * `config.base` is optional on `TimberConfig` because adapters can be invoked
+ * by callers that predate it (a hand-written adapter, a test harness). Falling
+ * back to `'/'` reproduces the pre-TIM-1274 output exactly, which is correct
+ * for the only deployments those callers can have: a build under a non-root
+ * base always goes through `plugins/adapter-build.ts`, which populates it.
+ *
+ * Typed structurally rather than as `TimberConfig` so this module keeps no
+ * import of `./types.js` at runtime.
+ */
+export function adapterBase(config: { base?: string }): string {
+  return config.base ?? '/';
+}
 
 // ─── Static asset cache headers ──────────────────────────────────────────
 
@@ -33,27 +52,165 @@ export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
  * A `/*` catch-all is NOT used — it would be additive on Cloudflare,
  * producing duplicate Cache-Control directives on hashed assets
  * (invalid per RFC 9111).
+ *
+ * **Every rule path is written in deployed-URL space** (TIM-1274). The
+ * platform matches these patterns against the request path, which under a
+ * non-root `base` sits below the prefix: with `base: '/repo/'` the assets are
+ * at `/repo/assets/*`, so a rule saying `/assets/*` matches nothing. Silent
+ * for the cache rules (slower, still correct) and not silent for the
+ * Content-Type rules — an extensionless API route output is unreadable on
+ * Cloudflare Workers Static Assets without one.
+ *
+ * The prefix is applied at exactly one point, `rulePath()`, which every rule
+ * in this function goes through. Prefixing the three wildcards and
+ * hand-checking that the per-file rules agree is how the next rule gets
+ * missed.
  */
 // Cloudflare Workers Static Assets caps _headers at 100 rules.
 // Reserve 3 for the wildcard hashed-asset rules (/assets/*, /_timber/fonts/*, /_rsc/*).
 const MAX_PER_FILE_RULES = 97;
 
-export function generateHeadersFile(
-  unhashedPaths?: string[],
-  contentTypes?: Record<string, string>
-): string {
-  let content = `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
+export interface HeadersFileOptions {
+  /**
+   * The deployment base, already normalized by `normalizeBasePath()` —
+   * leading and trailing slash, `'/'` at the domain root.
+   *
+   * Required rather than defaulted: a caller that forgets it would emit
+   * root-relative rules that match nothing, which is the bug this closes.
+   */
+  base: string;
+  /** Unhashed static files (route-space paths) needing per-file cache rules. */
+  unhashedPaths?: string[];
+  /** Route-space path → Content-Type, for extensionless API route outputs. */
+  contentTypes?: Record<string, string>;
+  /**
+   * Verbatim contents of the user's `public/_headers`, appended after the
+   * generated rules. See `mergeUserHeaders` for why it goes last.
+   */
+  userRules?: string;
+}
 
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
+/**
+ * Count the rules in a `_headers` file — a rule is a path line, which is any
+ * line that is neither blank, a comment, nor an indented header.
+ *
+ * @internal Exported for testing.
+ */
+export function countHeaderRules(content: string): number {
+  return content
+    .split('\n')
+    .filter((line) => line.trim() !== '' && !line.startsWith('#') && !/^\s/.test(line)).length;
+}
 
-/_timber/fonts/*
-  Cache-Control: ${IMMUTABLE_CACHE}
+/** One `_headers` block: a path pattern and the headers it sets. */
+export interface HeaderRule {
+  pattern: string;
+  headers: Array<{ name: string; value: string }>;
+}
 
-/_rsc/*
-  Cache-Control: ${IMMUTABLE_CACHE}
+/**
+ * Parse a `_headers` file. A non-indented, non-comment line opens a rule; the
+ * indented `Name: value` lines beneath it belong to that rule.
+ *
+ * @internal Exported for testing.
+ */
+export function parseHeaderRules(content: string): HeaderRule[] {
+  const rules: HeaderRule[] = [];
+  for (const raw of content.split('\n')) {
+    const line = raw.replace(/\r$/, '');
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue;
+    if (/^\s/.test(line)) {
+      const current = rules[rules.length - 1];
+      if (!current) continue; // header with no rule above it — not ours to fix
+      const colon = line.indexOf(':');
+      if (colon === -1) continue;
+      current.headers.push({
+        name: line.slice(0, colon).trim(),
+        value: line.slice(colon + 1).trim(),
+      });
+    } else {
+      rules.push({ pattern: line.trim(), headers: [] });
+    }
+  }
+  return rules;
+}
+
+/**
+ * Whether a user pattern can match paths a generated pattern also matches.
+ *
+ * Deliberately narrow: equality, or a prefix-glob (`/x/*`, `/*`) whose literal
+ * prefix contains the other's. Anything cleverer risks claiming an overlap
+ * that is not there, and the only thing this drives is a warning — a false
+ * positive is noise a developer cannot act on.
+ */
+function patternsOverlap(a: string, b: string): boolean {
+  if (a === b) return true;
+  const prefixOf = (p: string) => (p.endsWith('*') ? p.slice(0, -1) : null);
+  const [pa, pb] = [prefixOf(a), prefixOf(b)];
+  if (pa !== null && (b.startsWith(pa) || pa === '')) return true;
+  if (pb !== null && (a.startsWith(pb) || pb === '')) return true;
+  return false;
+}
+
+export function generateHeadersFile({
+  base,
+  unhashedPaths,
+  contentTypes,
+  userRules,
+}: HeadersFileOptions): string {
+  /** Route-space rule path → deployed-URL rule path. */
+  const rulePath = (path: string) => withBasePath(base, path);
+
+  // Cloudflare and Netlify apply *every* matching rule, so emitting a header
+  // the user also sets on the same path yields two definitions of it — a
+  // comma-joined `Cache-Control` that is invalid per RFC 9111, and neither
+  // side's intent. This module already refuses to emit a `/*` catch-all for
+  // that reason; appending the user's file verbatim reintroduced it through
+  // the back door (TIM-1326).
+  //
+  // An explicit app rule beats a framework default, so where the user names
+  // the same pattern and the same header, ours is dropped. Only exact pattern
+  // matches are resolved this way: silently dropping asset immutability
+  // because a `/*` rule *might* subsume it would be a worse surprise than the
+  // duplicate, so overlapping-but-different patterns warn instead.
+  const userRuleList = userRules ? parseHeaderRules(userRules) : [];
+  const overriddenExactly = new Set(
+    userRuleList.flatMap((rule) =>
+      rule.headers.map((h) => `${rule.pattern}\0${h.name.toLowerCase()}`)
+    )
+  );
+  const overridden = (pattern: string, header: string) =>
+    overriddenExactly.has(`${pattern}\0${header.toLowerCase()}`);
+
+  const warnedOverlaps = new Set<string>();
+  const emit = (pattern: string, header: string, value: string): string => {
+    if (overridden(pattern, header)) return '';
+    for (const rule of userRuleList) {
+      if (rule.pattern === pattern) continue;
+      if (!patternsOverlap(rule.pattern, pattern)) continue;
+      for (const h of rule.headers) {
+        if (h.name.toLowerCase() !== header.toLowerCase()) continue;
+        const key = `${rule.pattern}\0${pattern}\0${header.toLowerCase()}`;
+        if (warnedOverlaps.has(key)) continue;
+        warnedOverlaps.add(key);
+        console.warn(
+          `[timber] _headers: your rule "${rule.pattern}" sets ${header}, which ` +
+            `timber also sets on "${pattern}". Cloudflare and Netlify apply both, ` +
+            `so the response gets two ${header} values. Use the exact pattern ` +
+            `"${pattern}" to replace timber's rule, or narrow yours so they do ` +
+            `not overlap.`
+        );
+      }
+    }
+    return `\n${pattern}\n  ${header}: ${value}\n`;
+  };
+
+  let content = `# Auto-generated by @timber-js/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
 `;
+  for (const path of ['/assets/*', '/_timber/fonts/*', '/_rsc/*']) {
+    content += emit(rulePath(path), 'Cache-Control', IMMUTABLE_CACHE);
+  }
 
   // Content-Type rules are higher priority than cache headers for
   // extensionless files — without them the file is unreadable.
@@ -80,18 +237,36 @@ export function generateHeadersFile(
           `files will get Cache-Control headers.`
       );
     }
-    if (capped.length > 0) {
-      content += `\n# Unhashed static assets — short-lived cache with revalidation\n`;
-      for (const p of capped) {
-        content += `\n${p}\n  Cache-Control: ${STATIC_CACHE}\n`;
-      }
+    // Section bodies are built before their comment header so a section the
+    // user has overridden entirely does not leave a heading over nothing.
+    const body = capped.map((p) => emit(rulePath(p), 'Cache-Control', STATIC_CACHE)).join('');
+    if (body !== '') {
+      content += `\n# Unhashed static assets — short-lived cache with revalidation\n${body}`;
     }
   }
 
-  if (ctEntries.length > 0) {
-    content += `\n# Content-Type for extensionless API routes\n`;
-    for (const [urlPath, ct] of ctEntries) {
-      content += `\n${urlPath}\n  Content-Type: ${ct}\n`;
+  const ctBody = ctEntries
+    .map(([urlPath, ct]) => emit(rulePath(urlPath), 'Content-Type', ct))
+    .join('');
+  if (ctBody !== '') {
+    content += `\n# Content-Type for extensionless API routes\n${ctBody}`;
+  }
+
+  // User rules last, matching the `_redirects` merge. Their paths are left
+  // verbatim: `_redirects` prefixes the rules it generates because it wrote
+  // them in route space, but these are the user's own text, already authored
+  // against the URLs the site is deployed at.
+  if (userRules && userRules.trim() !== '') {
+    content += `\n# User-authored rules from public/_headers\n\n${userRules.trim()}\n`;
+
+    const total = countHeaderRules(content);
+    if (total > MAX_PER_FILE_RULES + 3) {
+      console.warn(
+        `[timber] _headers: ${total} rules after merging public/_headers, over ` +
+          `Cloudflare's ${MAX_PER_FILE_RULES + 3}-rule limit. Rules past the ` +
+          `limit are dropped by the platform — remove some, or move static ` +
+          `assets under a directory the wildcard rules already cover.`
+      );
     }
   }
 

package/src/adapters/types.ts

@@ -11,6 +11,18 @@
 export interface TimberConfig {
   /** Absolute path to the project root (Vite root). */
   root?: string;
+  /**
+   * The resolved deployment base, normalized by `normalizeBasePath()` —
+   * leading and trailing slash, `'/'` at the domain root.
+   *
+   * Adapters write platform files (`_headers`, `_redirects`) whose rules the
+   * host matches against the *request* path, so those rules live in deployed-
+   * URL space rather than route space and need this prefix (TIM-1274).
+   *
+   * Populated by `plugins/adapter-build.ts` from `ctx.base`, the single copy
+   * lifted in TIM-1261. Adapters must not re-derive it from `config.base`.
+   */
+  base?: string;
   output: 'server' | 'static';
   clientJavascriptDisabled?: boolean;
   /**
@@ -23,7 +35,7 @@ export interface TimberConfig {
    * Absolute path to the directory containing pre-rendered static HTML,
    * RSC flight files, and API route outputs. Present only when
    * output: 'static' and the static generation pass completed.
-   * Layout: path/index.html, _rsc/path.rsc, api-route-path
+   * Layout: path/index.html, _rsc/path/index.rsc, api-route-path
    */
   staticPagesDir?: string;
   /**

package/src/cache/fast-hash.ts

@@ -9,6 +9,11 @@
  * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes
  * including Cloudflare Workers. No node:crypto dependency.
  *
+ * Server-side only. The `_rsc` payload cache key deliberately does NOT use
+ * this — the origin compares that value, which makes it a check rather than
+ * a cache key, and FNV is solvable for a chosen digest. See
+ * `shared/rsc-cache-key.ts`.
+ *
  * See TIM-370.
  */
 

package/src/client/browser-entry/action-dispatch.ts

@@ -18,6 +18,7 @@ import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runti
 import { getRouter, getRouterOrNull } from '#client-internal';
 import { setHardNavigating } from '../navigation-root.js';
 import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.js';
+import { markClientStale } from '../stale-client.js';
 export function setupServerActions(): void {
   setServerCallback(async (id: string, args: unknown[]) => {
     const body = await encodeReply(args);
@@ -44,11 +45,15 @@ export function setupServerActions(): void {
       headers: actionHeaders,
       body,
     }).then((res) => {
-      // Version skew detection (TIM-446): if the server signals a reload,
-      // trigger a full page load to pick up the new deployment.
+      // Version skew detection (TIM-446): the server has signalled that this
+      // client is stale.
       if (res.headers.get(RELOAD_HEADER) === '1') {
-        window.location.reload();
-        throw new Error('Version skew detected — reloading page');
+        // Record it and fail the action. No page load: the action cannot
+        // succeed either way (its ID does not exist in the new build), and
+        // tearing the document down here would destroy whatever the user had
+        // typed into the form. Their next navigation recovers (TIM-1275).
+        markClientStale();
+        throw new Error('Version skew detected — this client is out of date');
       }
       hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
       hasRedirect = res.headers.get('X-Timber-Redirect') != null;