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

package/src/plugins/static-build.ts

@@ -1,35 +1,64 @@
 /**
  * timber-static-build — Vite sub-plugin for static output mode.
  *
- * When `output: 'static'` is set in timber.config.ts, this plugin:
- * 1. Validates that no dynamic APIs (cookies(), headers()) are used
- * 2. When client JavaScript is disabled, rejects 'use client' and 'use server' directives
- * 3. Coordinates build-time rendering of all pages
+ * When `output: 'static'` is set in timber.config.ts:
+ * 1. The plugin validates that no dynamic APIs (getCookies(), getHeaders())
+ *    are used
+ * 2. `runStaticGeneration`, the static generation step of the post-build
+ *    phase (plugins/post-build.ts), renders all routes to static HTML + RSC
+ *    flight files
  *
- * Design doc: design/15-future-prerendering.md
+ * Design doc: design/11-platform.md §"static output mode"
  */
 
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import { detectFileDirective } from '#/utils/directive-parser.js';
+import { mkdir, readdir, readFile, writeFile, rename, rm, stat } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, extname, isAbsolute, join, resolve, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { writeFileAtomic } from '../utils/write-file-atomic.ts';
+import type { PluginContext } from '../plugin-context.ts';
+import type { DirectoryArtifact } from '../adapters/types.ts';
+import type {
+  StaticGenerationOptions,
+  StaticGenerationSummary,
+  StaticPageEntry,
+  StaticRedirectEntry,
+} from '../server/static-generator.ts';
+import { isRelativeBase, normalizeBasePath, withBasePath } from '../shared/base-path.ts';
+import type { RscManifest, RscManifestEntry } from '../shared/rsc-manifest.ts';
+import { htmlEscapeJsonString } from '../server/flight-scripts.ts';
+import { RSC_PAYLOAD_DIR, rscPayloadPath } from '../shared/rsc-payload-path.ts';
+import { REDIRECTS_FILE, RESERVED_OUTPUT_PATHS } from '../shared/static-platform-files.ts';
+import {
+  detectFsIdentity,
+  fsKey,
+  EXACT_FS_IDENTITY,
+  type FsIdentity,
+} from '../adapters/fs-identity.ts';
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
+/**
+ * A single entry in the RSC manifest injected into static HTML.
+ * Maps an unhashed `/_rsc/*.rsc` path to its hashed URL, with
+ * optional route params inlined to avoid a sidecar fetch.
+ */
+// Declared in shared/rsc-manifest.ts so the client that reads this manifest and
+// the build that writes it cannot drift. Re-exported for existing importers.
+export type { RscManifestEntry, RscManifest } from '../shared/rsc-manifest.ts';
+
 export interface StaticValidationError {
-  type: 'dynamic-api' | 'nojs-directive';
+  type: 'dynamic-api';
   file: string;
   message: string;
   line?: number;
 }
 
-export interface StaticOptions {
-  clientJavascriptDisabled: boolean;
-}
-
 // ---------------------------------------------------------------------------
-// Detection: dynamic APIs (cookies, headers)
+// Detection: dynamic APIs (getCookies, getHeaders, and legacy cookies/headers)
 // ---------------------------------------------------------------------------
 
 /**
@@ -39,12 +68,14 @@ export interface StaticOptions {
  * We detect both import-level and call-level usage.
  */
 const DYNAMIC_API_PATTERNS: Array<{ pattern: RegExp; name: string }> = [
+  { pattern: /\bgetCookieJar\s*\(/, name: 'getCookieJar()' },
+  { pattern: /\bgetHeaders\s*\(/, name: 'getHeaders()' },
   { pattern: /\bcookies\s*\(/, name: 'cookies()' },
   { pattern: /\bheaders\s*\(/, name: 'headers()' },
 ];
 
 /**
- * Detect usage of dynamic per-request APIs (cookies(), headers())
+ * Detect usage of dynamic per-request APIs (getCookies(), getHeaders())
  * that cannot work at build time in static mode.
  *
  * Returns an array of validation errors.
@@ -79,75 +110,654 @@ export function detectDynamicApis(code: string, fileId: string): StaticValidatio
 }
 
 // ---------------------------------------------------------------------------
-// Detection: 'use client' / 'use server' directives (clientJavascript disabled)
+// Redirect rules
 // ---------------------------------------------------------------------------
 
 /**
- * Detect 'use client' and 'use server' directives using AST-based parsing.
- * When client JavaScript is disabled, both are hard build errors — no React
- * runtime or server actions are allowed in the output.
+ * Generate a `_redirects` file from collected redirect entries.
+ * Uses the Cloudflare Pages / Netlify format: `/from /to statusCode`
+ *
+ * Both sides are base-prefixed (TIM-1274). `from` is matched by the host
+ * against the request path and `to` is served to the browser as a `Location`,
+ * so both are deployed-URL space while `StaticRedirectEntry` carries route
+ * space — under `base: '/repo/'`, a rule `/old /new 301` would match nothing
+ * and, if it did, would send the browser off the deployment.
  *
- * When client JavaScript is enabled, these are allowed (client components
- * hydrate, server actions get extracted to API endpoints).
+ * An off-origin `to` is left alone: `redirectExternal()` produces an absolute
+ * URL, and a protocol-relative one addresses another host too. Neither is a
+ * path on this deployment, so neither takes the prefix.
+ *
+ * @param base Normalized deployment base (see `shared/base-path.ts`).
+ * @internal Exported for testing.
  */
-export function detectDirectives(
-  code: string,
-  fileId: string,
-  options: StaticOptions
-): StaticValidationError[] {
-  if (!options.clientJavascriptDisabled) return [];
+export function generateRedirectsFile(redirects: StaticRedirectEntry[], base: string): string {
+  const target = (to: string) =>
+    to.startsWith('/') && !to.startsWith('//') ? withBasePath(base, to) : to;
+  const lines = redirects.map((r) => `${withBasePath(base, r.from)} ${target(r.to)} ${r.status}`);
+  return lines.join('\n') + '\n';
+}
 
-  const errors: StaticValidationError[] = [];
+// ---------------------------------------------------------------------------
+// File output helpers
+// ---------------------------------------------------------------------------
 
-  const clientDirective = detectFileDirective(code, ['use client']);
-  if (clientDirective) {
-    errors.push({
-      type: 'nojs-directive',
-      file: fileId,
-      message:
-        `'use client' is not allowed when client JavaScript is disabled (clientJavascript: false). ` +
-        `This mode produces zero JavaScript — client components cannot exist.`,
-      line: clientDirective.line,
-    });
+/**
+ * Determine the output file path for a static page entry.
+ *
+ * Pages: /about → about/index.html, / → index.html
+ * RSC:   /about → _rsc/about/index.rsc, / → _rsc/index.rsc
+ * API:   /feed.xml → feed.xml, /api/data → api/data
+ *
+ * The RSC shape mirrors the HTML shape for the reason the HTML shape has it:
+ * a route gets a directory and the artifact is the `index` inside it, so the
+ * mapping is injective. See `shared/rsc-payload-path.ts` (TIM-1266).
+ */
+export function staticOutputPath(entry: StaticPageEntry): string {
+  const urlPath = entry.urlPath === '/' ? '' : entry.urlPath;
+
+  if (entry.kind === 'rsc') {
+    // Route space is `/…`; the static output path is relative to the output
+    // directory, so drop the leading slash.
+    return rscPayloadPath(entry.urlPath).slice(1);
+  }
+
+  if (entry.kind === 'api') {
+    // API routes use their URL path directly. If no extension, fall
+    // back to the path as-is (static host serves based on content type).
+    return urlPath.startsWith('/') ? urlPath.slice(1) : urlPath || 'index';
+  }
+
+  // HTML pages
+  if (!urlPath) return 'index.html';
+  // Synthetic 404 entry from static generation — must be 404.html at the
+  // root so static hosts (GitHub Pages, Cloudflare Pages, Netlify) serve
+  // it automatically for unmatched URLs. Uses an internal urlPath to avoid
+  // colliding with a real /404 page route.
+  if (urlPath === '/_timber_not_found') return '404.html';
+  return `${urlPath.startsWith('/') ? urlPath.slice(1) : urlPath}/index.html`;
+}
+
+// ---------------------------------------------------------------------------
+// Output path collisions (TIM-1266)
+// ---------------------------------------------------------------------------
+
+/**
+ * Records which entry claimed each output path and reports second claims.
+ *
+ * Two entries landing on one path is not a rendering failure — both render
+ * fine — so nothing downstream notices. The file is written twice, the second
+ * write wins, and the deployment serves one route's bytes at another route's
+ * URL with the same content type and the same shape (TIM-1266).
+ *
+ * The naming rules are injective by construction (a route path is a directory
+ * and the artifact is the `index` inside it), so a collision here means either
+ * two entries were enumerated for one URL or a route reached a path the
+ * framework reserves for itself (`404.html`). Both are build errors: there is
+ * no correct file to write.
+ *
+ * Two entries can also be unwritable together without claiming the same
+ * string: one wants a file where the other wants a directory (`about` from an
+ * API route, `about/index.html` from a page). The filesystem does refuse that
+ * one — `EISDIR` on the rename, `ENOTDIR` on the mkdir, depending on which
+ * lands second — but an errno names a path, and in the rename case the path
+ * it names is the write's temp file. Reported here instead, so the message says which
+ * two routes.
+ *
+ * Collisions are **collected, not thrown**. `onEntry` runs inside the
+ * generator, whose RSC branch treats a throw as "this payload is unavailable,
+ * SPA navigation falls back to a full load" and swallows it — which for a
+ * collision is the wrong end state, since the two payloads are still
+ * ambiguous. The caller raises them once generation is done.
+ *
+ * @internal Exported for testing.
+ */
+export class StaticOutputPaths {
+  private readonly claimed = new Map<string, StaticPageEntry>();
+  /** Every ancestor directory of a claimed path, mapped to its claimant. */
+  private readonly directories = new Map<string, StaticPageEntry>();
+  private readonly collisions: string[] = [];
+
+  /**
+   * @param identity How the output filesystem decides two paths name one
+   *   file, from `detectFsIdentity`. The guard predicts whether two writes
+   *   land on one file, which is a property of the filesystem — so it is
+   *   asked, not assumed. Folding unconditionally would reject `/Foo` beside
+   *   `/foo` on Linux, where both are perfectly servable files.
+   */
+  private readonly identity: FsIdentity;
+
+  constructor(identity: FsIdentity = EXACT_FS_IDENTITY) {
+    this.identity = identity;
+  }
+
+  /** The identity under which the filesystem will compare this path. */
+  private key(relPath: string): string {
+    return fsKey(relPath, this.identity);
+  }
+
+  /**
+   * Claim `relPath` for `entry`. Returns false when the path cannot be
+   * written alongside an earlier claim, in which case the caller must not
+   * write the file — the losing entry is recorded and the build fails at
+   * the end.
+   */
+  claim(relPath: string, entry: StaticPageEntry): boolean {
+    // Folded like every other comparison here: on a case-insensitive
+    // filesystem a route rendering to `_HEADERS` is the same file the
+    // adapter is about to write, so a case-sensitive match would wave it
+    // through into the overwrite this reservation exists to stop.
+    if (RESERVED_OUTPUT_PATHS.some((name) => this.key(name) === this.key(relPath))) {
+      this.collisions.push(
+        `  - ${relPath}: reserved — the framework writes this file itself, ` +
+          `and ${entry.kind} for ${entry.urlPath} would be overwritten by it`
+      );
+      return false;
+    }
+
+    const key = this.key(relPath);
+    const conflict =
+      this.claimed.get(key) ??
+      // This entry wants a file where an earlier one wants a directory…
+      this.directories.get(key) ??
+      // …or a directory where an earlier one wants a file.
+      ancestors(relPath).reduce<StaticPageEntry | undefined>(
+        (found, dir) => found ?? this.claimed.get(this.key(dir)),
+        undefined
+      );
+
+    if (conflict) {
+      this.collisions.push(
+        `  - ${relPath}: ${conflict.kind} for ${conflict.urlPath} and ${entry.kind} for ${entry.urlPath}`
+      );
+      return false;
+    }
+
+    this.claimed.set(key, entry);
+    for (const dir of ancestors(relPath)) {
+      const dirKey = this.key(dir);
+      if (!this.directories.has(dirKey)) this.directories.set(dirKey, entry);
+    }
+    return true;
   }
 
-  const serverDirective = detectFileDirective(code, ['use server']);
-  if (serverDirective) {
-    errors.push({
-      type: 'nojs-directive',
-      file: fileId,
-      message:
-        `'use server' is not allowed when client JavaScript is disabled (clientJavascript: false). ` +
-        `This mode produces zero JavaScript — server actions cannot exist.`,
-      line: serverDirective.line,
+  /** Throw if any two entries could not both be written. */
+  assertNoCollisions(): void {
+    if (this.collisions.length === 0) return;
+    throw new Error(
+      `[timber] Static generation: ${this.collisions.length} output path collision(s) — ` +
+        `two entries write the same path and one would silently overwrite the other. ` +
+        `Rename or remove one route in each pair:\n${this.collisions.join('\n')}`
+    );
+  }
+}
+
+/** Every directory an output path sits under, outermost first. */
+function ancestors(relPath: string): string[] {
+  const parts = relPath.split('/');
+  parts.pop();
+  return parts.map((_, i) => parts.slice(0, i + 1).join('/'));
+}
+
+/**
+ * Writes generated entries into the static output directory, one file per
+ * entry, refusing any write that would land on a path another entry holds.
+ *
+ * @internal Exported for testing.
+ */
+export class StaticSiteWriter {
+  /** Content-Type per URL path for extensionless API routes (TIM-1241). */
+  readonly contentTypes: Record<string, string> = {};
+  private readonly paths: StaticOutputPaths;
+
+  private readonly staticDir: string;
+
+  constructor(staticDir: string, identity: FsIdentity = EXACT_FS_IDENTITY) {
+    this.staticDir = staticDir;
+    this.paths = new StaticOutputPaths(identity);
+  }
+
+  async write(entry: StaticPageEntry): Promise<void> {
+    const relPath = staticOutputPath(entry);
+    const fullPath = resolve(this.staticDir, relPath);
+
+    // Reject path traversal: generated params with "../" could escape
+    // the output directory and overwrite build artifacts.
+    //
+    // Tested on the first *segment*, not on the prefix. A slug is arbitrary
+    // application data, and `..draft` is an ordinary directory name whose
+    // relative path merely begins with two dots — a prefix test failed the
+    // build on it. `isAbsolute` covers the case `relative()` gives up on and
+    // returns an absolute path for: a different Windows drive, where the
+    // round-trip check below compares equal and would let it through.
+    const rel = relative(this.staticDir, fullPath);
+    const firstSegment = rel.split(/[\\/]/)[0];
+    if (firstSegment === '..' || isAbsolute(rel) || resolve(this.staticDir, rel) !== fullPath) {
+      throw new Error(
+        `[timber] Static generation: output path "${relPath}" escapes the ` +
+          `static output directory — check generateStaticSegmentParams for ` +
+          `path traversal characters in ${entry.urlPath}`
+      );
+    }
+
+    // Claim the *normalized* path, not the one `staticOutputPath` built. Two
+    // distinct strings can name one file — a generated param carrying `..`
+    // makes `_rsc/a/../b/index.rsc` and `_rsc/b/index.rsc` different keys for
+    // the same write, which is the collision this check exists to stop. The
+    // traversal guard above only rejects escapes; it lets an in-bounds detour
+    // through.
+    //
+    // A losing claim is not written: the build is about to fail, and
+    // clobbering the winner would make the failure state worse than the one
+    // being reported.
+    if (!this.paths.claim(rel.replace(/\\/g, '/'), entry)) return;
+
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFileAtomic(fullPath, entry.body);
+
+    // Track Content-Type for extensionless API routes so adapters
+    // can write per-path Content-Type rules in _headers. TIM-1241.
+    if (entry.kind === 'api' && !extname(relPath) && entry.contentType) {
+      this.contentTypes[entry.urlPath] = entry.contentType;
+    }
+  }
+
+  /** Throw if any two entries could not both be written. */
+  assertNoCollisions(): void {
+    this.paths.assertNoCollisions();
+  }
+}
+
+/**
+ * Remove artifacts a generation pass produces only *conditionally*, so none
+ * of them can survive from an earlier build into this one.
+ *
+ * Pages are not in this set: every page is rewritten each pass, and a page
+ * whose route was deleted is a different problem (a stale file nothing links
+ * to) from the one here.
+ *
+ * - `_rsc/` because the files are content-hashed. Left in place, a previous
+ *   build's already-hashed payload gets hashed again and accumulates.
+ * - `_redirects` because it is written only when this pass found redirects.
+ *   A build whose redirects were removed would otherwise ship the previous
+ *   build's rules — and would break the merge exemption in
+ *   `shared/static-platform-files.ts`, which lets the pre-rendered copy
+ *   overwrite `public/_redirects` on the grounds that it *contains* it. That
+ *   holds only for a file the current pass produced (TIM-1266).
+ *
+ * @internal Exported for testing.
+ */
+export async function cleanConditionalArtifacts(staticDir: string): Promise<void> {
+  await rm(join(staticDir, RSC_PAYLOAD_DIR), { recursive: true, force: true }).catch(() => {});
+  await rm(join(staticDir, REDIRECTS_FILE), { force: true }).catch(() => {});
+}
+
+// ---------------------------------------------------------------------------
+// Static generation orchestration (runs after Vite build)
+// ---------------------------------------------------------------------------
+
+interface StaticGenerateModule {
+  __timber_generateStaticSite?: (
+    options: StaticGenerationOptions
+  ) => Promise<StaticGenerationSummary>;
+}
+
+/**
+ * A port as Node actually hands it over: `unref()` is a Node addition the DOM
+ * lib type does not declare. Optional rather than asserted, so a runtime whose
+ * `MessageChannel` has no such method is simply skipped instead of throwing.
+ */
+type ReleasablePort = MessagePort & { unref?: () => void };
+
+/**
+ * Run `fn` with `MessageChannel` instrumented, then stop every channel opened
+ * while it ran from holding the process open.
+ *
+ * Static generation is the only build pass that renders **HTML** in the build
+ * process: it imports the built app bundle and drives the full SSR pipeline
+ * through it. React's scheduler opens a `MessageChannel` at module scope in
+ * that bundle (`scheduler`'s DOM build) and never closes it, and a ref'd
+ * `MessagePort` keeps Node's event loop alive on its own — so `timber build`
+ * finished the site, printed its summary, and then hung forever. Server-mode
+ * builds are unaffected because nothing there renders through react-dom.
+ *
+ * `unref()` is the whole fix: it leaves the port working and only drops the
+ * "keep the process alive" property. It is applied **after** `fn` resolves, so
+ * a render in flight can never be cut short by the process exiting under it —
+ * an unref'd port would let Node exit while the scheduler still had a
+ * continuation queued, which is a silently truncated page rather than a hang.
+ *
+ * Nothing renders after this pass. If that ever changes, the release has to
+ * move to the end of whatever renders last.
+ *
+ * @internal Exported for testing.
+ */
+export async function withSchedulerPortsReleased<T>(fn: () => Promise<T>): Promise<T> {
+  const opened: ReleasablePort[] = [];
+  const OriginalMessageChannel = globalThis.MessageChannel;
+
+  globalThis.MessageChannel = class extends OriginalMessageChannel {
+    constructor() {
+      super();
+      opened.push(this.port1, this.port2);
+    }
+  };
+
+  try {
+    return await fn();
+  } finally {
+    globalThis.MessageChannel = OriginalMessageChannel;
+    for (const port of opened) port.unref?.();
+  }
+}
+
+/** The pre-rendered site a static generation pass wrote. */
+export interface StaticSite {
+  pages: DirectoryArtifact;
+  /** Content-Type per URL path for extensionless API outputs (TIM-1241). */
+  contentTypes: Record<string, string>;
+  /** `[RSC_PAYLOAD_DIR]` when payloads were written and content-hashed, else none. */
+  immutableDirs: string[];
+}
+
+/**
+ * Load the built RSC entry and run the static generation pass — the static
+ * generation step of the post-build phase (plugins/post-build.ts).
+ *
+ * The build manifest it renders with is already final: the phase merged the
+ * RSC assets manifest into it and published it before this step. Unlike
+ * prebuilt capture, this needs the FULL pipeline handler, so
+ * __TIMBER_CAPTURE_MODE__ must be false.
+ *
+ * Returns the site only once it is complete, so an adapter is never handed a
+ * directory a failed pass left half-written — a failure throws instead.
+ */
+export async function runStaticGeneration(ctx: PluginContext, rscDir: string): Promise<StaticSite> {
+  const entryPath = join(rscDir, 'index.js');
+  warnUnusableBase(ctx);
+
+  // Ensure capture mode is off — we need the full handler.
+  (globalThis as Record<string, unknown>).__TIMBER_CAPTURE_MODE__ = false;
+
+  console.log('[timber] Static generation: building site…');
+
+  const staticDir = join(ctx.buildDir, 'static-pages');
+  await cleanConditionalArtifacts(staticDir);
+  await mkdir(staticDir, { recursive: true });
+
+  const sitemapConfig = ctx.config.sitemap;
+  const autoSitemapEnabled = Boolean(sitemapConfig?.enabled && sitemapConfig?.baseUrl);
+
+  const writer = new StaticSiteWriter(staticDir, await detectFsIdentity(staticDir));
+  // Route params are not collected here any more. They used to be lifted off
+  // the generated entry's response headers and inlined into the manifest,
+  // because a `.rsc` file carries no headers and the manifest was the only
+  // channel a static SPA navigation had (TIM-1255, TIM-1285). The params are
+  // now inside the payload itself — a field on its root row — so the `.rsc`
+  // file carries them and there is nothing to lift (TIM-1294).
+
+  // The app bundle is imported and rendered inside this wrapper, and only
+  // inside it: everything it opens to schedule React work is released on the
+  // way out so the build process can exit.
+  const summary = await withSchedulerPortsReleased(async () => {
+    let mod: StaticGenerateModule;
+    try {
+      const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
+      mod = (await import(/* @vite-ignore */ entryUrl)) as StaticGenerateModule;
+    } catch (error) {
+      // A missing entry lands here too: the import is the existence check.
+      throw new Error(
+        `[timber] Static generation: failed to load the built RSC entry (${entryPath}). ` +
+          `The full request handler must initialize for static rendering.`,
+        { cause: error }
+      );
+    }
+
+    const generate = mod.__timber_generateStaticSite;
+    if (typeof generate !== 'function') {
+      throw new Error(
+        `[timber] Static generation: built RSC entry does not export ` +
+          `__timber_generateStaticSite — rebuild from a clean build directory`
+      );
+    }
+
+    return generate({
+      autoSitemapEnabled,
+      renderTimeoutMs: ctx.config.renderTimeoutMs,
+      onEntry: (entry: StaticPageEntry) => writer.write(entry),
     });
+  });
+
+  const totalUrls = summary.rendered + summary.errors.length;
+  console.log(
+    `[timber] Static generation: rendered ${summary.rendered}/${totalUrls} entries.` +
+      (summary.errors.length > 0 ? ` ${summary.errors.length} failed.` : '') +
+      (summary.redirects.length > 0 ? ` ${summary.redirects.length} redirect(s).` : '')
+  );
+
+  // Warnings are non-fatal but must not be buried in the per-entry log stream —
+  // they name a degraded artifact the developer is about to deploy (TIM-1258).
+  for (const warning of summary.warnings) {
+    console.warn(`[timber] Static generation warning: ${warning}`);
   }
 
-  return errors;
+  if (summary.errors.length > 0) {
+    const details = summary.errors.map((e) => `  - ${e.urlPath}: ${e.message}`).join('\n');
+    throw new Error(`[timber] Static generation failed:\n${details}`);
+  }
+
+  // Raised after the render errors above: a collision means the site is
+  // ambiguous, not that a page failed, and the message names both routes.
+  writer.assertNoCollisions();
+
+  // Hash RSC flight payloads for immutable caching (TIM-1254).
+  // Renames _rsc/*.rsc → _rsc/*-<hash>.rsc and injects a manifest
+  // into each HTML file so the client can resolve hashed URLs.
+  // Skip when client JS is disabled — no SPA navigation, no RSC fetches,
+  // and injecting a <script> tag would violate the no-JS contract.
+  const immutableDirs: string[] = [];
+  if (!ctx.clientJavascript.disabled) {
+    const rscManifest = await hashRscPayloads(staticDir);
+    if (Object.keys(rscManifest).length > 0) {
+      immutableDirs.push(RSC_PAYLOAD_DIR);
+      await injectRscManifestIntoHtml(staticDir, rscManifest);
+      console.log(
+        `[timber] Static generation: hashed ${Object.keys(rscManifest).length} RSC flight payloads`
+      );
+    }
+  }
+
+  // Write _redirects file for platform redirect rules (Cloudflare Pages,
+  // Netlify, etc.). Format: /from /to status. See TIM-1245.
+  if (summary.redirects.length > 0) {
+    const generated = generateRedirectsFile(summary.redirects, normalizeBasePath(ctx.base));
+    const redirectsPath = join(staticDir, REDIRECTS_FILE);
+
+    // Merge with user-authored _redirects if present. TIM-1249.
+    const userRedirects = await readUserRedirects(ctx.root);
+    if (userRedirects !== null) {
+      await writeFileAtomic(redirectsPath, generated + '\n' + userRedirects);
+      console.log(
+        `[timber] Static generation: wrote _redirects with ${summary.redirects.length} ` +
+          `generated rule(s), merged with user-authored _redirects`
+      );
+    } else {
+      await writeFileAtomic(redirectsPath, generated);
+      console.log(
+        `[timber] Static generation: wrote _redirects with ${summary.redirects.length} rule(s)`
+      );
+    }
+  }
+
+  // Content types travel with the site because they describe it: a static
+  // host cannot infer the type of an extensionless API output (TIM-1241).
+  return { pages: { path: staticDir }, contentTypes: writer.contentTypes, immutableDirs };
 }
 
 // ---------------------------------------------------------------------------
-// Combined validation
+// Base path validation (TIM-1261)
 // ---------------------------------------------------------------------------
 
 /**
- * Run all static mode validations on a source file.
+ * Warn when Vite's `base` is document-relative (`'./'`) in static mode.
+ *
+ * Payload URLs are addressed from the deployment root plus the base prefix.
+ * A relative base gives no prefix to compute (see shared/base-path.ts), so
+ * `/_rsc/about.rsc` is requested at the domain root — correct only when the
+ * site is served from there. The build still succeeds: relative bases work
+ * fine for assets, and for a root-served site nothing is wrong. The warning
+ * exists so a sub-path deployment does not silently degrade to a hard
+ * navigation on every link.
+ *
+ * Skipped when client JS is disabled — there is no SPA navigation and no
+ * payload fetch to mis-address.
  *
- * Combines:
- * - Dynamic API detection (cookies, headers) — always in static mode
- * - Directive detection ('use client', 'use server') — only when client JS is disabled
+ * @internal Exported for testing.
  */
-export function validateStaticMode(
-  code: string,
-  fileId: string,
-  options: StaticOptions
-): StaticValidationError[] {
-  const errors: StaticValidationError[] = [];
+export function warnUnusableBase(ctx: PluginContext): void {
+  if (ctx.clientJavascript.disabled) return;
+  if (!isRelativeBase(ctx.base)) return;
+  console.warn(
+    `[timber] Static mode: base is "${ctx.base}", which is document-relative. ` +
+      `RSC payload URLs are addressed from the domain root, so client-side ` +
+      `navigation will fall back to a full page load if the site is served ` +
+      `from a sub-path. Use an absolute base (e.g. base: '/repo/') to deploy ` +
+      `under a sub-path. See design/11-platform.md.`
+  );
+}
 
-  errors.push(...detectDynamicApis(code, fileId));
-  errors.push(...detectDirectives(code, fileId, options));
+// ---------------------------------------------------------------------------
+// RSC flight payload hashing (TIM-1254)
+// ---------------------------------------------------------------------------
 
-  return errors;
+/**
+ * Compute a short content hash for immutable caching.
+ * Uses 8 chars of base64url-encoded SHA-256, matching Vite's asset hash style.
+ */
+export function contentHash(data: Buffer | Uint8Array): string {
+  return createHash('sha256').update(data).digest('base64url').slice(0, 8);
+}
+
+/**
+ * Walk a directory recursively and return all file paths.
+ */
+async function walkDir(dir: string): Promise<string[]> {
+  const results: string[] = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...(await walkDir(full)));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Hash all RSC flight payloads in `_rsc/`, rename them with content
+ * hashes, and build a manifest with optional inlined route params.
+ *
+ * Before: `_rsc/index.rsc`, `_rsc/about.rsc`
+ * After:  `_rsc/index-B7YxEKdN.rsc`, `_rsc/about-C8ZzFLfO.rsc`
+ *
+ * The manifest maps the original `_rsc/` URL to an entry object:
+ * `{"/_rsc/index.rsc":{"url":"/_rsc/index-B7YxEKdN.rsc"}, ...}`
+ *
+ * Keys and URLs are **route-space**: root-relative, never carrying Vite's
+ * `base`. The client applies the base once, at fetch time
+ * (`client/rsc-fetch.ts` → `toStaticRscUrl`), so the generated site stays
+ * relocatable and the base has exactly one expression at runtime rather
+ * than two that must agree. See TIM-1261.
+ *
+ * Route params (from `routeParams`) are inlined into the manifest
+ * entry, eliminating the need for .params.json sidecar files. TIM-1255.
+ *
+ * Injected into HTML as:
+ * `<script>window.__TIMBER_RSC_MANIFEST__={...}</script>`
+ *
+ * @internal Exported for testing.
+ */
+export async function hashRscPayloads(staticDir: string): Promise<RscManifest> {
+  const rscDir = join(staticDir, RSC_PAYLOAD_DIR);
+  const files = await walkDir(rscDir);
+  const manifest: RscManifest = {};
+
+  for (const filePath of files) {
+    if (!filePath.endsWith('.rsc')) continue;
+
+    const content = await readFile(filePath);
+    const hash = contentHash(content);
+    const rel = relative(staticDir, filePath).replace(/\\/g, '/');
+
+    const base = filePath.slice(0, -'.rsc'.length);
+    const hashedPath = `${base}-${hash}.rsc`;
+
+    await rename(filePath, hashedPath);
+
+    const hashedRel = relative(staticDir, hashedPath).replace(/\\/g, '/');
+    const key = `/${rel}`;
+    manifest[key] = { url: `/${hashedRel}` };
+  }
+
+  return manifest;
+}
+
+/**
+ * Inject the RSC manifest into all HTML files as a `<script>` tag
+ * before `</head>`. This lets the client resolve hashed RSC URLs
+ * without an extra network request.
+ *
+ * @internal Exported for testing.
+ */
+export async function injectRscManifestIntoHtml(
+  staticDir: string,
+  manifest: RscManifest
+): Promise<void> {
+  const allFiles = await walkDir(staticDir);
+  const htmlFiles = allFiles.filter((f) => f.endsWith('.html'));
+  const escapedJson = htmlEscapeJsonString(JSON.stringify(manifest));
+  const scriptTag = `<script>window.__TIMBER_RSC_MANIFEST__=${escapedJson}</script>`;
+
+  for (const htmlFile of htmlFiles) {
+    let html = await readFile(htmlFile, 'utf-8');
+    // Insert before </head> so it's available before any client JS runs
+    const headClose = html.indexOf('</head>');
+    if (headClose !== -1) {
+      html = html.slice(0, headClose) + scriptTag + html.slice(headClose);
+    } else {
+      // Fallback: prepend to body
+      html = scriptTag + html;
+    }
+    await writeFile(htmlFile, html);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// User-authored _redirects merge (TIM-1249)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a user-authored `_redirects` file from the project's `public/`
+ * directory. Returns `null` if no file exists.
+ *
+ * @internal Exported for testing.
+ */
+export async function readUserRedirects(root: string): Promise<string | null> {
+  const candidates = [join(root, 'public', REDIRECTS_FILE)];
+  for (const path of candidates) {
+    try {
+      return await readFile(path, 'utf-8');
+    } catch {
+      // File doesn't exist — try next
+    }
+  }
+  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -157,15 +767,11 @@ export function validateStaticMode(
 /**
  * Create the timber-static-build Vite plugin.
  *
- * Only active when output: 'static' is configured.
- *
- * Hooks:
- * - transform: Validates source files for static mode violations
+ * Only active when output: 'static' is configured. Validates source files
+ * for static mode violations; rendering the site is `runStaticGeneration`,
+ * which the post-build phase calls.
  */
 export function timberStaticBuild(ctx: PluginContext): Plugin {
-  const isStatic = ctx.config.output === 'static';
-  const clientJavascriptDisabled = ctx.clientJavascript.disabled;
-
   return {
     name: 'timber-static-build',
 
@@ -173,10 +779,14 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
      * Validate source files during transform.
      *
      * In static mode, we check every app/ file for:
-     * - Dynamic API usage (cookies(), headers()) → build error
-     * - When client JS disabled: 'use client' / 'use server' directives → build error
+     * - Dynamic API usage (getCookies(), getHeaders()) → build error
      */
     transform(code: string, id: string) {
+      // Read ctx.config lazily inside the hook — not at plugin construction
+      // time — so file-based config from timber.config.ts is respected.
+      // See TIM-451.
+      const isStatic = ctx.config.output === 'static';
+
       // Only active in static mode
       if (!isStatic) return null;
 
@@ -189,7 +799,7 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
       // Only check JS/TS files
       if (!/\.[jt]sx?$/.test(id)) return null;
 
-      const errors = validateStaticMode(code, id, { clientJavascriptDisabled });
+      const errors = detectDynamicApis(code, id);
 
       if (errors.length > 0) {
         // Format all errors into a single build error message