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

package/src/adapters/compress-module.ts

@@ -7,12 +7,90 @@
 // hand-written string template, any fix to server/compress.ts automatically
 // flows to the production module. See design/18-build-system.md ("entry
 // modules are real TypeScript files, not codegen strings").
+//
+// The transform strips types; it does NOT bundle. The emitted file sits
+// alone in the build output, so any import specifier that survives into it
+// is a module resolution failure at runtime on the deployed server. Shared
+// constants are therefore interpolated here — the same treatment the
+// Cloudflare worker template gives `RSC_KEY_HEADERS` — and anything else
+// that reaches the output as an import is rejected with a build error
+// rather than shipped.
 
 import { transformWithOxc } from 'vite';
 // Vite's ?raw import embeds the file as a string at build time — works
 // in both dev (Vite resolves the TS source) and the published package
 // (the string is inlined into the compiled adapter entry).
 import compressSource from '../server/compress.ts?raw';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
+
+/**
+ * The one import `server/compress.ts` is allowed to carry, and its inlined
+ * form.
+ *
+ * The binding list is matched exactly rather than as `{…}`. A second binding
+ * added to that import would otherwise be erased along with the statement and
+ * become a `ReferenceError` in the deployed `_compress.mjs` — the failure this
+ * whole module exists to make impossible. Matching exactly means such an
+ * import falls through to the rejection below instead.
+ */
+const INLINED_IMPORTS: ReadonlyArray<{ pattern: RegExp; replacement: string }> = [
+  {
+    pattern:
+      /^import\s*\{\s*RSC_CONTENT_TYPE\s*,?\s*\}\s*from\s*["'][^"']*shared\/rsc-media-type\.js["'];?[ \t]*$/m,
+    replacement: `const RSC_CONTENT_TYPE = ${JSON.stringify(RSC_CONTENT_TYPE)};`,
+  },
+];
+
+/**
+ * Every way a module specifier can reach the emitted file, minus Node
+ * builtins.
+ *
+ * `node:*` is exempt because it resolves on the deployed server exactly as it
+ * does here — `_compress.mjs` already imports `node:zlib` and `node:stream`,
+ * and self-hosted (Node/Bun) is the only place this file runs. Everything
+ * else — relative paths, bare packages — has no resolution target next to a
+ * lone `.mjs` in the build output.
+ *
+ * All three forms are listed rather than the one `server/compress.ts` happens
+ * to use, because a re-export or a lazy `await import()` fails in exactly the
+ * same place and is exactly as invisible until deploy.
+ */
+const MODULE_SPECIFIERS: readonly RegExp[] = [
+  // import … from '…'  /  export … from '…'
+  /^[ \t]*(?:import|export)\b[^\n]*\bfrom\s*["'](?!node:)[^"']+["']/m,
+  // import '…'  (side effect only)
+  /^[ \t]*import\s*["'](?!node:)[^"']+["']/m,
+  // import('…')  (dynamic, literal specifier)
+  /\bimport\s*\(\s*["'](?!node:)[^"']+["']/,
+];
+
+/**
+ * Replace the shared-module imports with their values and reject anything
+ * else that would leave a dangling specifier in `_compress.mjs`.
+ *
+ * Exported separately from `generateCompressModule` so both branches can be
+ * driven with fixtures: the source it normally compiles is fixed, so a test
+ * of the generator alone can only ever exercise whichever branch that source
+ * happens to take today.
+ *
+ * @internal Exported for testing.
+ */
+export function inlineCompressImports(code: string): string {
+  let out = code;
+  for (const { pattern, replacement } of INLINED_IMPORTS) {
+    out = out.replace(pattern, replacement);
+  }
+  const surviving = MODULE_SPECIFIERS.map((pattern) => pattern.exec(out)).find(Boolean);
+  if (surviving) {
+    throw new Error(
+      `[timber] server/compress.ts is emitted as a standalone _compress.mjs (type-stripped, ` +
+        `not bundled), so it cannot import anything at runtime. Found: ${surviving[0].trim()}\n` +
+        `  Either inline the value in adapters/compress-module.ts (see INLINED_IMPORTS) or ` +
+        `keep the dependency out of server/compress.ts.`
+    );
+  }
+  return out;
+}
 
 /**
  * Compile server/compress.ts into a standalone ESM module.
@@ -31,6 +109,6 @@ export async function generateCompressModule(): Promise<string> {
   return (
     '// Generated by @timber-js/app — compiled from server/compress.ts.\n' +
     '// Do not edit — this file is regenerated on each build.\n' +
-    result.code
+    inlineCompressImports(result.code)
   );
 }

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.
  */