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

package/src/plugins/static-build.ts

@@ -10,9 +10,9 @@
 
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
-import { mkdir, readdir, readFile, writeFile, rename, rm } from 'node:fs/promises';
-import { createHash } from 'node:crypto';
-import { dirname, extname, join, resolve, relative } from 'node:path';
+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 type { PluginContext } from '../plugin-context.js';
 import type {
@@ -22,7 +22,17 @@ import type {
   StaticRedirectEntry,
 } from '../server/static-generator.js';
 import { mergeRscAssetsManifest } from './adapter-build.js';
+import { isRelativeBase, normalizeBasePath, withBasePath } from '../shared/base-path.js';
+import type { RscManifest, RscManifestEntry } from '../shared/rsc-manifest.js';
 import { htmlEscapeJsonString } from '../server/flight-scripts.js';
+import { rscPayloadPath } from '../shared/rsc-payload-path.js';
+import { REDIRECTS_FILE, RESERVED_OUTPUT_PATHS } from '../shared/static-platform-files.js';
+import {
+  detectFsIdentity,
+  fsKey,
+  EXACT_FS_IDENTITY,
+  type FsIdentity,
+} from '../adapters/fs-identity.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -33,12 +43,9 @@ import { htmlEscapeJsonString } from '../server/flight-scripts.js';
  * Maps an unhashed `/_rsc/*.rsc` path to its hashed URL, with
  * optional route params inlined to avoid a sidecar fetch.
  */
-export interface RscManifestEntry {
-  url: string;
-  params?: Record<string, string | string[]>;
-}
-
-export type RscManifest = Record<string, RscManifestEntry>;
+// 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.js';
 
 export interface StaticValidationError {
   type: 'dynamic-api';
@@ -107,10 +114,23 @@ export function detectDynamicApis(code: string, fileId: string): StaticValidatio
  * 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.
+ *
+ * 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 generateRedirectsFile(redirects: StaticRedirectEntry[]): string {
-  const lines = redirects.map((r) => `${r.from} ${r.to} ${r.status}`);
+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';
 }
 
@@ -129,15 +149,20 @@ async function writeFileAtomic(path: string, data: Uint8Array | string): Promise
  * Determine the output file path for a static page entry.
  *
  * Pages: /about → about/index.html, / → index.html
- * RSC:   /about → _rsc/about.rsc, / → _rsc/index.rsc
+ * 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') {
-    const rscPath = urlPath || '/index';
-    return `_rsc${rscPath}.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') {
@@ -156,6 +181,216 @@ export function staticOutputPath(entry: StaticPageEntry): string {
   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 `about.tmp`. 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.
+   */
+  constructor(private readonly identity: FsIdentity = EXACT_FS_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;
+  }
+
+  /** 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;
+
+  constructor(
+    private readonly staticDir: string,
+    identity: FsIdentity = EXACT_FS_IDENTITY
+  ) {
+    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'), { recursive: true, force: true }).catch(() => {});
+  await rm(join(staticDir, REDIRECTS_FILE), { force: true }).catch(() => {});
+}
+
 // ---------------------------------------------------------------------------
 // Static generation orchestration (runs after Vite build)
 // ---------------------------------------------------------------------------
@@ -166,6 +401,55 @@ interface StaticGenerateModule {
   ) => 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?.();
+  }
+}
+
 /**
  * Load the built RSC entry and run the static generation pass.
  *
@@ -200,80 +484,50 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
 
   console.log('[timber] Static generation: building site…');
 
-  let mod: StaticGenerateModule;
-  try {
-    const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
-    mod = (await import(/* @vite-ignore */ entryUrl)) as StaticGenerateModule;
-  } catch (error) {
-    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`
-    );
-  }
-
   const staticDir = join(ctx.buildDir, 'static-pages');
-  // Clean stale RSC artifacts from previous builds before generating
-  // new ones. Without this, already-hashed files from a prior build
-  // would get re-hashed and accumulate in the output.
-  await rm(join(staticDir, '_rsc'), { recursive: true, force: true }).catch(() => {});
+  await cleanConditionalArtifacts(staticDir);
   await mkdir(staticDir, { recursive: true });
 
   const sitemapConfig = ctx.config.sitemap;
   const autoSitemapEnabled = Boolean(sitemapConfig?.enabled && sitemapConfig?.baseUrl);
 
-  const contentTypes: Record<string, string> = {};
-  // Collect route params from RSC entries so they can be inlined
-  // into the manifest instead of written as .params.json sidecars.
-  // Keyed by the unhashed /_rsc/*.rsc URL path. TIM-1255.
-  const routeParams: Record<string, Record<string, string | string[]>> = {};
-
-  const summary = await generate({
-    autoSitemapEnabled,
-    renderTimeoutMs: ctx.config.renderTimeoutMs,
-    onEntry: async (entry: StaticPageEntry) => {
-      const relPath = staticOutputPath(entry);
-      const fullPath = resolve(staticDir, relPath);
-
-      // Reject path traversal: generated params with "../" could escape
-      // the output directory and overwrite build artifacts.
-      const rel = relative(staticDir, fullPath);
-      if (rel.startsWith('..') || resolve(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}`
-        );
-      }
+  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) {
+      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 }
+      );
+    }
 
-      await mkdir(dirname(fullPath), { recursive: true });
-      await writeFileAtomic(fullPath, entry.body);
-
-      // Capture route params for RSC entries. These are inlined into
-      // the RSC manifest (TIM-1255) instead of written as sidecars.
-      if (entry.kind === 'rsc' && entry.headers['x-timber-params']) {
-        const rscUrlKey = entry.urlPath === '/' ? '/_rsc/index.rsc' : `/_rsc${entry.urlPath}.rsc`;
-        try {
-          routeParams[rscUrlKey] = JSON.parse(entry.headers['x-timber-params']);
-        } catch {
-          // Malformed params header — skip
-        }
-      }
+    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`
+      );
+    }
 
-      // 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) {
-        contentTypes[entry.urlPath] = entry.contentType;
-      }
-    },
+    return generate({
+      autoSitemapEnabled,
+      renderTimeoutMs: ctx.config.renderTimeoutMs,
+      onEntry: (entry: StaticPageEntry) => writer.write(entry),
+    });
   });
 
   const totalUrls = summary.rendered + summary.errors.length;
@@ -283,15 +537,25 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
       (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}`);
+  }
+
   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();
+
   // Store content-type mappings on the plugin context so adapters
   // can include them in the _headers file. TIM-1241.
-  if (Object.keys(contentTypes).length > 0) {
-    ctx.staticContentTypes = contentTypes;
+  if (Object.keys(writer.contentTypes).length > 0) {
+    ctx.staticContentTypes = writer.contentTypes;
   }
 
   // Hash RSC flight payloads for immutable caching (TIM-1254).
@@ -300,7 +564,7 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
   // Skip when client JS is disabled — no SPA navigation, no RSC fetches,
   // and injecting a <script> tag would violate the no-JS contract.
   if (!ctx.clientJavascript.disabled) {
-    const rscManifest = await hashRscPayloads(staticDir, routeParams);
+    const rscManifest = await hashRscPayloads(staticDir);
     if (Object.keys(rscManifest).length > 0) {
       await injectRscManifestIntoHtml(staticDir, rscManifest);
       ctx.rscManifest = rscManifest;
@@ -313,8 +577,8 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
   // 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);
-    const redirectsPath = join(staticDir, '_redirects');
+    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);
@@ -335,6 +599,38 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
   return summary;
 }
 
+// ---------------------------------------------------------------------------
+// Base path validation (TIM-1261)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ *
+ * @internal Exported for testing.
+ */
+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.`
+  );
+}
+
 // ---------------------------------------------------------------------------
 // RSC flight payload hashing (TIM-1254)
 // ---------------------------------------------------------------------------
@@ -379,6 +675,12 @@ async function walkDir(dir: string): Promise<string[]> {
  * 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.
  *
@@ -387,10 +689,7 @@ async function walkDir(dir: string): Promise<string[]> {
  *
  * @internal Exported for testing.
  */
-export async function hashRscPayloads(
-  staticDir: string,
-  routeParams?: Record<string, Record<string, string | string[]>>
-): Promise<RscManifest> {
+export async function hashRscPayloads(staticDir: string): Promise<RscManifest> {
   const rscDir = join(staticDir, '_rsc');
   const files = await walkDir(rscDir);
   const manifest: RscManifest = {};
@@ -409,11 +708,7 @@ export async function hashRscPayloads(
 
     const hashedRel = relative(staticDir, hashedPath).replace(/\\/g, '/');
     const key = `/${rel}`;
-    const entry: RscManifestEntry = { url: `/${hashedRel}` };
-    if (routeParams?.[key]) {
-      entry.params = routeParams[key];
-    }
-    manifest[key] = entry;
+    manifest[key] = { url: `/${hashedRel}` };
   }
 
   return manifest;
@@ -460,7 +755,7 @@ export async function injectRscManifestIntoHtml(
  * @internal Exported for testing.
  */
 export async function readUserRedirects(root: string): Promise<string | null> {
-  const candidates = [join(root, 'public', '_redirects')];
+  const candidates = [join(root, 'public', REDIRECTS_FILE)];
   for (const path of candidates) {
     try {
       return await readFile(path, 'utf-8');
@@ -542,6 +837,7 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
         const isStatic = ctx.config.output === 'static';
         if (!isStatic) return;
 
+        warnUnusableBase(ctx);
         await runStaticGeneration(ctx);
       },
     },