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

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;

package/src/client/browser-entry/hydrate.ts

@@ -6,20 +6,25 @@
  * 2. No RSC payload: deferred root creation via installDeferredNavigation
  *
  * Pre-hydration ordering contract (MUST execute in this order):
- *   1. initRouter()        — creates the global router so useRouter()
- *                            works during render
- *   2. setCurrentParams()  — populates params snapshot so
- *      + setNavigationState()  useSegmentParams() and usePathname()
- *                            return correct values during hydration
- *   3. hydrateRoot()       — synchronously executes component render
- *                            functions that depend on steps 1-2
+ *   1. initRouter()          — creates the global router so useRouter()
+ *                              works during render
+ *   2. setNavigationState()  — populates pathname/search so usePathname()
+ *                              returns correct values during hydration
+ *   3. hydrateRoot()         — synchronously executes component render
+ *                              functions that depend on steps 1-2
+ *
+ * Params are not part of this sequence. They arrive on the payload root and
+ * are published by `PayloadRoot` at the top of the tree, so
+ * `useSegmentParams()` is correct during hydration without anything having to
+ * run before it (TIM-1294, TIM-1297).
  *
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
 import { createElement } from 'react';
 import { hydrateRoot, createRoot } from 'react-dom/client';
-import { getRouterOrNull, setCurrentParams } from '#client-internal';
+import { getRouterOrNull } from '#client-internal';
+import { PayloadRoot } from '../params-context.js';
 import {
   NavigationProvider,
   getNavigationState,
@@ -79,26 +84,21 @@ interface HydrateOptions {
 }
 
 /**
- * Run the pre-hydration sequence: read server-embedded params and
- * set navigation state. Must be called AFTER initRouter().
+ * Run the pre-hydration sequence: set navigation state from the address bar.
+ * Must be called AFTER initRouter().
+ *
+ * Params are no longer seeded here. They used to arrive on two inline scripts
+ * that had to execute before `hydrateRoot()`, because hydration synchronously
+ * renders components that read them. They now ride the payload root, and the
+ * provider that publishes them renders before its own descendants — so the
+ * ordering the step existed to guarantee is now a property of the tree rather
+ * than of the bootstrap sequence (TIM-1294, TIM-1297).
  */
 export function runPreHydration(): void {
-  const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
-  if (earlyParams && typeof earlyParams === 'object') {
-    setCurrentParams(earlyParams as Record<string, string | string[]>);
-    setNavigationState({
-      params: earlyParams as Record<string, string | string[]>,
-      pathname: window.location.pathname,
-      search: window.location.search,
-    });
-    delete (self as unknown as Record<string, unknown>).__timber_params;
-  } else {
-    setNavigationState({
-      params: {},
-      pathname: window.location.pathname,
-      search: window.location.search,
-    });
-  }
+  setNavigationState({
+    pathname: window.location.pathname,
+    search: window.location.search,
+  });
 }
 
 /**
@@ -123,11 +123,22 @@ export function hydrateApp({ rscResult, config }: HydrateOptions): void {
     // startTransition, so React keeps old UI visible while new Suspense
     // boundaries resolve during navigation. See design/05-streaming.md.
     const navState = getNavigationState();
-    const withNav = createElement(
-      NavigationProvider,
-      { value: navState },
+    // The same chain `renderTree()` in router-init.ts builds on every
+    // navigation, in the same order. It has to be: an element type that is
+    // present here and absent on the first navigation (or the reverse)
+    // changes the type at that position, and React remounts everything below
+    // it — losing the layout state partial navigation exists to preserve.
+    //
+    // `source` is the payload's params promise, not a resolved record: the
+    // inlined Flight stream is still arriving and hydration cannot wait for
+    // it. PayloadRoot suspends on it exactly where React was going to suspend
+    // on `element` (TIM-1297).
+    const withParams = createElement(
+      PayloadRoot,
+      { source: rscResult.params },
       element as React.ReactNode
     );
+    const withNav = createElement(NavigationProvider, { value: navState }, withParams);
     const withUpdates = createElement(
       SegmentUpdateContext.Provider,
       { value: EMPTY_SEGMENT_UPDATES },

package/src/client/browser-entry/index.ts

@@ -40,11 +40,13 @@ import schemaCodecs from 'virtual:timber-schema';
 import { setLinkCodecs } from '../../params/codec-registry.js';
 setLinkCodecs(schemaCodecs);
 
-import { setClientDeploymentId, setStaticMode } from '../rsc-fetch.js';
+import { setClientDeploymentId, setStaticMode, setBasePath } from '../rsc-fetch.js';
+import { initStaleClient } from '../stale-client.js';
 
 import { setupServerActions } from './action-dispatch.js';
 import { createRscPayloadStream } from './rsc-stream.js';
 import { createTimberRouter } from './router-init.js';
+import { readPublishedParams } from '../../shared/payload-root.js';
 import { runPreHydration, hydrateApp } from './hydrate.js';
 import { setupPostHydration } from './post-hydration.js';
 import { setupHmr } from './hmr.js';
@@ -63,6 +65,16 @@ function bootstrap(runtimeConfig: typeof config): void {
     setClientDeploymentId(deploymentId);
   }
 
+  // Reactive skew recovery for failures that never reach the router —
+  // lazily imported client components, preloaded stylesheets. No-ops when
+  // there is no deployment ID, i.e. in dev (TIM-1260).
+  initStaleClient(deploymentId);
+
+  // Deployment base path (Vite's resolved `base`). Must be set before any
+  // RSC fetch — under a non-root base the payloads live below the prefix
+  // like every other emitted file (TIM-1261).
+  setBasePath((runtimeConfig as Record<string, unknown>).base as string | undefined);
+
   // Static mode: fetch _rsc/*.rsc files instead of route URLs with
   // Accept headers. Static hosts ignore Accept headers (TIM-1243).
   if ((runtimeConfig as Record<string, unknown>).output === 'static') {
@@ -75,6 +87,7 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Step 3: Create router + Navigation API integration
   const { router, navApiController } = createTimberRouter({
     initialElement: rscResult?.element ?? undefined,
+    initialParams: rscResult?.params,
     clientSegmentCache:
       ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false,
   });
@@ -90,6 +103,7 @@ function bootstrap(runtimeConfig: typeof config): void {
     router,
     navApiController,
     initialElement: rscResult?.element ?? null,
+    initialParams: rscResult?.params ?? readPublishedParams(undefined),
   });
 
   // Step 7: HMR (dev-only, no-op in production)

package/src/client/browser-entry/post-hydration.ts

@@ -15,12 +15,15 @@ import type { RouterInstance } from '#client-internal';
 import { getNavigationState } from '../navigation-context.js';
 import type { NavigationApiController } from '../navigation-api.js';
 import { getScrollY } from './scroll.js';
+import type { ParamsSource } from '../../shared/payload-root.js';
 
 interface PostHydrationOptions {
   router: RouterInstance;
   navApiController: NavigationApiController | null;
   /** Decoded RSC element from initial SSR (null if no RSC payload) */
   initialElement: unknown;
+  /** The params that payload published, from the same decode. */
+  initialParams: ParamsSource;
 }
 
 /**
@@ -30,20 +33,14 @@ export function setupPostHydration({
   router,
   navApiController,
   initialElement,
+  initialParams,
 }: PostHydrationOptions): void {
-  // Store the initial page in the history stack so back-button works
-  // after the first navigation. We store the decoded RSC element so
-  // back navigation can replay it instantly without a server fetch.
-  // Params were captured from the server-embedded __timber_params by
-  // runPreHydration() — without them on the entry, the cached replay on
-  // back-navigation would normalize params to {} and wipe every
-  // useSegmentParams() consumer on the initial page (TIM-1037).
   // Populate the segment cache from server-embedded segment metadata.
   // This enables state tree diffing from the very first client navigation.
   // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
   const timberSegments = (self as unknown as Record<string, unknown>).__timber_segments;
   const initialSegmentInfo = Array.isArray(timberSegments)
-    ? (timberSegments as import('../segment-cache').SegmentInfo[])
+    ? (timberSegments as import('../../shared/segment-info.js').SegmentInfo[])
     : null;
   if (initialSegmentInfo) {
     router.initSegmentCache(initialSegmentInfo);
@@ -53,9 +50,13 @@ export function setupPostHydration({
   // Store the initial page in the history stack so back-button works
   // after the first navigation. Include segmentInfo so the segment
   // cache is restored correctly on popstate cached replay.
+  // Replaying this entry on a Back re-renders `initialElement` and republishes
+  // `initialParams`. Both came out of one split of one decoded payload root
+  // (rsc-stream.ts), so the entry cannot replay with another route's params —
+  // which is what a separately-seeded copy used to do (TIM-1037, TIM-1285).
   router.historyStack.push(window.location.pathname + window.location.search, {
     payload: initialElement,
-    params: getNavigationState().params,
+    params: initialParams,
     segmentInfo: initialSegmentInfo,
   });