@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.160

package/src/client/browser-entry/rsc-stream.ts

@@ -0,0 +1,157 @@
+/**
+ * RSC Stream Bootstrap — decodes the server-inlined RSC payload.
+ *
+ * The RSC payload is embedded in the HTML as progressive inline script
+ * tags that call `self.__timber_f.push([type, data])` as RSC chunks arrive.
+ * Typed tuples: [0] = bootstrap signal, [1, string] = Flight data chunk.
+ *
+ * This module sets up a ReadableStream fed by those push() calls so
+ * `createFromReadableStream` can decode the Flight protocol progressively.
+ *
+ * See design/18-build-system.md §"Entry Files"
+ */
+
+import { createFromReadableStream } from '../../rsc-runtime/browser.js';
+import { isPageUnloading } from '../unload-guard.js';
+
+type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
+
+export interface RscStreamResult {
+  /** The decoded RSC element (thenable/lazy — resolved by React during render) */
+  element: unknown;
+}
+
+/**
+ * Create the RSC payload stream from server-inlined `__timber_f` chunks.
+ *
+ * Returns null if no RSC payload was inlined (e.g., JS-only client).
+ * When a payload exists, returns the decoded element for hydration.
+ */
+export function createRscPayloadStream(): RscStreamResult | null {
+  // __timber_f is initialized in <head> via flightInitScript() (see
+  // flight-scripts.ts). If it doesn't exist, skip Flight decoding
+  // entirely and fall through to the createRoot branch.
+  // Do NOT defensively create it here: that would cause
+  // createFromReadableStream to be called on an empty stream, producing
+  // a "Connection closed" error on hydration. See TIM-552.
+  const timberChunks = (self as unknown as Record<string, FlightSegment[] | undefined>).__timber_f;
+  if (!timberChunks) return null;
+
+  const encoder = new TextEncoder();
+
+  // Buffer to hold string data until the stream writer is ready.
+  // Scripts that execute before hydration starts push data here.
+  let dataBuffer: string[] | undefined = [];
+  let streamWriter: ReadableStreamDefaultController<Uint8Array> | null = null;
+  let streamFlushed = false;
+
+  /** Process a typed tuple from __timber_f. */
+  function handleSegment(seg: FlightSegment): void {
+    if (seg[0] === 0) {
+      // Bootstrap signal — initialize buffer (already done above)
+      if (!dataBuffer) dataBuffer = [];
+    } else if (seg[0] === 1) {
+      // Flight data chunk
+      if (streamWriter) {
+        streamWriter.enqueue(encoder.encode(seg[1]));
+      } else if (dataBuffer) {
+        dataBuffer.push(seg[1]);
+      }
+    }
+  }
+
+  // Process any chunks that arrived before this script executed.
+  for (const seg of timberChunks) {
+    handleSegment(seg);
+  }
+  // Clear the array to release memory.
+  timberChunks.length = 0;
+
+  // Patch push() so subsequent script tags feed data in real time.
+  (timberChunks as unknown as { push: (seg: FlightSegment) => void }).push = handleSegment;
+
+  const rscPayload = new ReadableStream<Uint8Array>({
+    start(controller) {
+      streamWriter = controller;
+      // Flush buffered data into the stream.
+      if (dataBuffer) {
+        for (const data of dataBuffer) {
+          controller.enqueue(encoder.encode(data));
+        }
+        dataBuffer = undefined;
+      }
+      // If DOM already loaded (non-streaming or fast page), close now.
+      if (streamFlushed) {
+        controller.close();
+      }
+    },
+  });
+
+  // Close the stream when the document finishes loading.
+  // DOMContentLoaded fires after the HTML parser has processed all
+  // inline scripts (including streamed Suspense replacements and
+  // RSC data), so all push() calls have completed by this point.
+  //
+  // If the page is unloading (user refreshed or navigated away),
+  // do NOT close the stream. When the connection drops mid-stream,
+  // DOMContentLoaded fires because the parser finishes. Closing an
+  // incomplete RSC stream causes React's Flight client to throw
+  // "Connection closed." — a jarring error on a page being replaced.
+  // Leaving the stream open is harmless: the page is being torn down.
+  function onDOMContentLoaded(): void {
+    if (isPageUnloading()) return;
+
+    // In dev mode, do NOT close the stream. React's RSC renderer
+    // includes debug owner/stack references ($1, $14, etc.) in the
+    // Flight payload that point to rows delivered through the debug
+    // channel, not the main Flight stream. The browser Flight client
+    // tracks these as pending chunks. Closing the stream with
+    // unresolved chunks triggers reportGlobalError("Connection closed")
+    // which kills the entire React tree.
+    //
+    // Leaving the stream open is harmless: React has already received
+    // all data rows and can hydrate fully. The pending debug chunks
+    // just remain unresolved (they're only used for React DevTools
+    // component stacks, not rendering).
+    //
+    // In production, debug rows are not emitted, so closing is safe.
+    if (process.env.NODE_ENV === 'development') {
+      // Mark as flushed so no more data is buffered, but don't close.
+      streamFlushed = true;
+      dataBuffer = undefined;
+      return;
+    }
+
+    if (streamWriter && !streamFlushed) {
+      streamWriter.close();
+      streamFlushed = true;
+      dataBuffer = undefined;
+    }
+    streamFlushed = true;
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', onDOMContentLoaded, false);
+  } else {
+    // DOM already parsed. All inline RSC <script> tags have already
+    // executed and pushed their data into the buffer. The buffer was
+    // flushed into the stream during start() above.
+    //
+    // Close via queueMicrotask rather than setTimeout. setTimeout
+    // defers to the next macrotask, which can race with React's
+    // Flight client read loop — if React finishes reading all queued
+    // chunks and issues a reader.read() that pends, the stream is
+    // NOT closed yet (setTimeout hasn't fired), so React sees an
+    // open stream and waits. Then setTimeout fires and closes it.
+    // This works in theory but some React Flight builds interpret
+    // a mid-read close as "Connection closed" rather than clean EOF.
+    // queueMicrotask fires at the end of the current microtask
+    // checkpoint — after start() and createFromReadableStream
+    // initialization but before any macrotask, giving React a
+    // consistent close signal. See TIM-524.
+    queueMicrotask(onDOMContentLoaded);
+  }
+
+  const element = createFromReadableStream(rscPayload);
+  return { element };
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Scroll position helpers for the browser entry.
+ *
+ * Reads scroll position from the document viewport or explicitly marked
+ * `data-timber-scroll-restoration` containers.
+ *
+ * See design/19-client-navigation.md §"Overflow Scroll Containers".
+ */
+
+/**
+ * Read the current scroll position.
+ *
+ * Checks window scroll first, then explicit `data-timber-scroll-restoration`
+ * containers. With segment tree merging, shared layouts are reconciled in
+ * place via `cloneElement` — React preserves their DOM and scroll state
+ * naturally. We don't need to auto-detect overflow containers; only
+ * explicitly marked containers are tracked.
+ */
+/**
+ * Scroll the element matching a URL #fragment into view.
+ *
+ * Mirrors browser anchor behavior: looks up the decoded fragment by id,
+ * then by anchor name. Returns true when a matching element was found and
+ * scrolled; false otherwise (the router falls back to scroll-to-top, same
+ * as a full page load with an unknown fragment). See TIM-1035.
+ */
+export function scrollToHashTarget(hash: string): boolean {
+  const fragment = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (!fragment) return false;
+  let id: string;
+  try {
+    id = decodeURIComponent(fragment);
+  } catch {
+    return false;
+  }
+  const target = document.getElementById(id) ?? document.getElementsByName(id)[0];
+  if (!target) return false;
+  target.scrollIntoView();
+  return true;
+}
+
+export function getScrollY(): number {
+  if (window.scrollY || document.documentElement.scrollTop || document.body.scrollTop) {
+    return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop;
+  }
+  for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
+    if ((el as HTMLElement).scrollTop > 0) return (el as HTMLElement).scrollTop;
+  }
+  return 0;
+}

package/src/client/error-boundary.tsx

@@ -20,6 +20,7 @@
 
 import { Component, createElement, type ReactNode } from 'react';
 import { getSsrData } from './ssr-data.js';
+import { getRouterOrNull } from './router-ref.js';
 
 // ─── Page Unload Detection ───────────────────────────────────────────────────
 // Track whether the page is being unloaded (user refreshed or navigated away).
@@ -65,17 +66,24 @@ type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
 
 export interface TimberErrorBoundaryProps {
   /** The component to render when an error is caught. */
-  fallbackComponent: (...args: unknown[]) => ReactNode;
+  fallbackComponent?: (...args: unknown[]) => ReactNode;
+  /**
+   * Pre-rendered fallback element. Used for MDX status files which are server
+   * components and cannot be passed as function props across the RSC→client
+   * boundary. When set, rendered directly instead of calling fallbackComponent.
+   *
+   * See design/10-error-handling.md §"Status-Code File Variants" — MDX status
+   * files are server components by default (zero client JS).
+   */
+  fallbackElement?: ReactNode;
   /**
    * Status code filter. If set, only catches errors matching this status.
    * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
    */
   status?: number;
   /**
-   * When true, catching a DenySignal sets _denyHandledByBoundary on the
-   * nav context to prevent page-level deny promotion. Only slot catch-all
-   * boundaries should set this — segment boundaries (403.tsx, 4xx.tsx,
-   * error.tsx) must NOT, otherwise normal page denies get swallowed.
+   * When true, this boundary wraps a parallel slot. Slot denials are
+   * graceful degradation — they must NOT change the HTTP status code.
    */
   isSlotBoundary?: boolean;
   children: ReactNode;
@@ -86,6 +94,20 @@ interface TimberErrorBoundaryState {
   error: Error | null;
 }
 
+// Module-level guard: the first boundary to catch a given redirect digest
+// schedules the navigation and marks it handled here. Subsequent renders
+// (React retries the error-boundary render path multiple times in dev, and
+// outer boundaries that also see the error) become no-ops, preventing
+// duplicate router.navigate() calls.
+const _handledRedirects = new WeakSet<object>();
+
+// Companion guard keyed by location: client-render redirect() (the
+// next/navigation shim) throws a FRESH error instance on every render
+// attempt, and React replays the errored render — so the WeakSet alone
+// would schedule the navigation twice. While a navigation to a location
+// is pending, further redirect errors for the same location are no-ops.
+let _pendingRedirectLocation: string | null = null;
+
 // ─── Component ───────────────────────────────────────────────────────────────
 
 export class TimberErrorBoundary extends Component<
@@ -131,11 +153,55 @@ export class TimberErrorBoundary extends Component<
     const error = this.state.error;
     const parsed = parseDigest(error);
 
-    // RedirectSignal errors must propagate through all error boundaries
-    // so the SSR shell fails and the pipeline catch block can produce a
-    // proper HTTP redirect response. See design/04-authorization.md.
+    // RedirectSignal handling splits by environment:
+    //
+    // - SSR (no window): re-throw so the Fizz shell fails and the server
+    //   pipeline catch block can produce a proper HTTP 3xx response. See
+    //   design/04-authorization.md.
+    //
+    // - Client (window exists): a RedirectSignal that leaked into the RSC
+    //   Flight payload during client navigation would otherwise bubble past
+    //   every error boundary to `window.onerror`, which in dev triggers the
+    //   Vite error overlay (false positive — navigation itself works).
+    //   Instead, ask the router to perform an SPA navigation to the target
+    //   and render nothing while it takes over. The router's own catch path
+    //   handles cross-origin / hard navigations. See TIM-838.
     if (parsed?.type === 'redirect') {
-      throw error;
+      if (typeof window === 'undefined') {
+        throw error;
+      }
+      // Dedupe: React may render the error-boundary fallback path more
+      // than once for a single caught error (dev-mode double render, and
+      // additional boundaries above us in the tree). Only schedule the
+      // navigation on the first render that sees this error instance.
+      const alreadyHandled =
+        _handledRedirects.has(error) || _pendingRedirectLocation === parsed.location;
+      if (!alreadyHandled) {
+        _handledRedirects.add(error);
+        const router = getRouterOrNull();
+        if (router) {
+          _pendingRedirectLocation = parsed.location;
+          // Schedule the navigation outside the render phase to avoid
+          // setState-during-render warnings from router state updates.
+          queueMicrotask(() => {
+            router
+              .navigate(parsed.location, { replace: true })
+              .catch(() => {
+                // Fall back to a hard navigation if the soft navigation fails.
+                window.location.href = parsed.location;
+              })
+              .finally(() => {
+                _pendingRedirectLocation = null;
+              });
+          });
+        } else {
+          // No router available (shouldn't happen post-bootstrap) — fall
+          // back to a hard navigation so the user still ends up at the
+          // target.
+          window.location.href = parsed.location;
+        }
+      }
+      return null;
     }
 
     // If this boundary has a status filter, check whether the error matches.
@@ -148,23 +214,62 @@ export class TimberErrorBoundary extends Component<
       }
     }
 
-    // Report DenySignal handling to prevent page-level promotion — but only
-    // for slot boundaries. Segment boundaries (403.tsx, 4xx.tsx, error.tsx)
-    // must NOT set this flag, otherwise normal page/hold-window denies get
-    // swallowed as 200 with boundary HTML instead of the intended 4xx.
-    // Runs here in render() (not getDerivedStateFromError) so the status
-    // filter has already been applied — non-matching boundaries re-threw above.
-    // See LOCAL-298.
-    if (parsed?.type === 'deny' && this.props.isSlotBoundary) {
-      const ssrData = getSsrData();
-      if (ssrData?._navContext) {
-        ssrData._navContext._denyHandledByBoundary = true;
+    // Report DenySignal handling so the pipeline skips the redundant
+    // renderDenyPage() re-render — but ONLY when this boundary can fully
+    // handle the deny in-tree:
+    //
+    // ✅ TSX boundaries (fallbackComponent) — can receive runtime props
+    //    (status, dangerouslyPassData) dynamically in render()
+    // ❌ MDX boundaries (fallbackElement) — pre-rendered at tree-build time,
+    //    cannot receive runtime deny props. Must fall through to re-render.
+    //
+    // For qualifying segment boundaries: also set the HTTP status code from
+    // the DenySignal so the Response has the correct 4xx status. This runs
+    // synchronously during Fizz rendering, BEFORE onShellReady.
+    //
+    // For slot boundaries: set _denyHandledByBoundary but do NOT change
+    // statusCode — slot denials are graceful degradation.
+    //
+    // See TIM-664, LOCAL-298.
+    if (parsed?.type === 'deny') {
+      const canHandleInTree = this.props.fallbackElement == null;
+
+      if (canHandleInTree || this.props.isSlotBoundary) {
+        const ssrData = getSsrData();
+        if (ssrData?._navContext) {
+          ssrData._navContext._denyHandledByBoundary = true;
+          if (!this.props.isSlotBoundary) {
+            ssrData._navContext.statusCode = parsed.status;
+          }
+        }
       }
     }
 
+    // Pre-rendered fallback element (MDX status files) — render directly.
+    // MDX components are server components that cannot be passed as function
+    // props across the RSC→client boundary. Instead, they are pre-rendered
+    // as elements in the RSC environment and passed here as fallbackElement.
+    if (this.props.fallbackElement != null) {
+      return this.props.fallbackElement;
+    }
+
     // Render the fallback component with the right props shape.
     if (parsed?.type === 'deny') {
+      // Status-code file boundaries (404.tsx, 4xx.tsx, …) get the documented
+      // 4xx props. error.tsx boundaries (no status filter) get their
+      // documented { error, digest, reset } contract — plus the deny extras
+      // for dual-shape implementations. Without the error prop, an error.tsx
+      // reading error.message crashes on deny fall-through. See TIM-1081.
+      if (this.props.status != null) {
+        return createElement(this.props.fallbackComponent as never, {
+          status: parsed.status,
+          dangerouslyPassData: parsed.data,
+        });
+      }
       return createElement(this.props.fallbackComponent as never, {
+        error,
+        digest: null,
+        reset: this.reset,
         status: parsed.status,
         dangerouslyPassData: parsed.data,
       });
@@ -196,8 +301,8 @@ function parseDigest(error: Error): ParsedDigest | null {
     if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {
       return parsed as ParsedDigest;
     }
-  } catch {
-    // Not JSON — legacy or unknown digest format
+  } catch (e) {
+    console.debug('[timber] error digest is not valid JSON:', e instanceof Error ? e.message : e);
   }
   return null;
 }

package/src/client/error-reconstituter.tsx

@@ -0,0 +1,79 @@
+'use client';
+
+/**
+ * Reconstitutes a SerializableError into a real Error instance before
+ * passing to the user's error component.
+ *
+ * TSX error pages are 'use client' components that receive { error: Error, digest, reset }.
+ * Error objects are not RSC-serializable (React Flight throws "Only plain objects
+ * can be passed to Client Components"). This wrapper receives the error as a plain
+ * SerializableError object, reconstitutes a real Error instance, and passes it
+ * to the user's error component — ensuring error instanceof Error works correctly.
+ *
+ * See design/spike-TIM-565-unify-error-pages.md §"Edge Case B"
+ * See design/10-error-handling.md §"RSC → SSR for Error Pages via SerializableError"
+ */
+
+import { createElement, type ReactNode, type ComponentType } from 'react';
+
+/**
+ * Plain-object representation of an Error that can cross the RSC → client boundary.
+ * Stack is only included in dev mode (gated by isDevMode() on the server).
+ */
+export interface SerializableError {
+  message: string;
+  name: string;
+  stack?: string;
+}
+
+/**
+ * Props for the ErrorReconstituter wrapper component.
+ * All props are RSC-serializable:
+ * - error: plain object (SerializableError)
+ * - digest: plain JSON or null
+ * - reset: undefined (only meaningful on client after boundary catch)
+ * - component: client module reference (RSC Flight serializes as opaque ref)
+ * - status / dangerouslyPassData: set only when error.tsx serves a deny()
+ *   as the last entry in the 4xx fallback chain — forwarded so dual-shape
+ *   error.tsx implementations can branch on the deny status (TIM-1081)
+ */
+interface ErrorReconstituterProps {
+  error: SerializableError;
+  digest: { code: string; data: unknown } | null;
+  reset: undefined;
+  component: ComponentType<{
+    error: Error;
+    digest: { code: string; data: unknown } | null;
+    reset: (() => void) | undefined;
+    status?: number;
+    dangerouslyPassData?: unknown;
+  }>;
+  status?: number;
+  dangerouslyPassData?: unknown;
+}
+
+/**
+ * Reconstitute a SerializableError into a real Error instance and render
+ * the user's error component with the proper props.
+ */
+export function ErrorReconstituter({
+  error: serialized,
+  digest,
+  reset,
+  component,
+  status,
+  dangerouslyPassData,
+}: ErrorReconstituterProps): ReactNode {
+  // Reconstitute a real Error so instanceof checks work in user code
+  const error = Object.assign(new Error(serialized.message), {
+    name: serialized.name,
+    ...(serialized.stack != null ? { stack: serialized.stack } : {}),
+  });
+
+  return createElement(component, {
+    error,
+    digest,
+    reset,
+    ...(status != null ? { status, dangerouslyPassData } : {}),
+  });
+}

package/src/client/form.tsx

@@ -12,8 +12,8 @@
  */
 
 import { useActionState as reactUseActionState, useTransition } from 'react';
-import type { ActionResult, ValidationErrors } from '#/server/action-client';
-import type { FormFlashData } from '#/server/form-flash';
+import type { ActionFn, ActionResult, InputHint, ValidationErrors } from '../server/action-client';
+import type { FormFlashData } from '../server/form-flash';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -27,13 +27,15 @@ export type UseActionStateFn<TData> = (
 ) => Promise<ActionResult<TData>>;
 
 /**
- * Return type of useActionState — matches React 19's useActionState return.
- * [result, formAction, isPending]
+ * Return type of useActionState.
+ * [result, formAction, isPending, errors]
+ * The 4th element is auto-derived from result via useFormErrors logic.
  */
 export type UseActionStateReturn<TData> = [
   result: ActionResult<TData> | null,
   formAction: (formData: FormData) => void,
   isPending: boolean,
+  errors: FormErrorsResult,
 ];
 
 // ─── useActionState ──────────────────────────────────────────────────────
@@ -73,7 +75,13 @@ export function useActionState<TData>(
 ): UseActionStateReturn<TData> {
   // FormFlashData is structurally compatible with ActionResult at runtime —
   // the cast satisfies React's generic inference which would otherwise widen TData.
-  return reactUseActionState(action, initialState as ActionResult<TData> | null, permalink);
+  const [result, formAction, isPending] = reactUseActionState(
+    action,
+    initialState as ActionResult<TData> | null,
+    permalink
+  );
+  const errors = deriveFormErrors(result);
+  return [result, formAction, isPending, errors];
 }
 
 // ─── useFormAction ───────────────────────────────────────────────────────
@@ -90,15 +98,22 @@ export function useActionState<TData>(
  * </button>
  * ```
  */
-export function useFormAction<TData>(
-  action: (input: unknown) => Promise<ActionResult<TData>>
-): [(input?: unknown) => Promise<ActionResult<TData>>, boolean] {
+export function useFormAction<TData = unknown, TInput = unknown>(
+  action: ActionFn<TData, TInput> | ((input: TInput) => Promise<ActionResult<TData>>)
+): [
+  (
+    ...args: undefined extends TInput ? [input?: InputHint<TInput>] : [input: InputHint<TInput>]
+  ) => Promise<ActionResult<TData>>,
+  boolean,
+] {
   const [isPending, startTransition] = useTransition();
 
-  const execute = (input?: unknown): Promise<ActionResult<TData>> => {
+  const execute = (input?: InputHint<TInput>): Promise<ActionResult<TData>> => {
     return new Promise((resolve) => {
       startTransition(async () => {
-        const result = await action(input);
+        const result = await (action as (input: InputHint<TInput>) => Promise<ActionResult<TData>>)(
+          input as InputHint<TInput>
+        );
         resolve(result);
       });
     });
@@ -107,9 +122,9 @@ export function useFormAction<TData>(
   return [execute, isPending];
 }
 
-// ─── useFormErrors ──────────────────────────────────────────────────────
+// ─── Form error extraction ────────────────────────────────────────────────
 
-/** Return type of useFormErrors(). */
+/** Return type of the errors element in useActionState. */
 export interface FormErrorsResult {
   /** Per-field validation errors keyed by field name. */
   fieldErrors: Record<string, string[]>;
@@ -124,27 +139,11 @@ export interface FormErrorsResult {
 }
 
 /**
- * Extract per-field and form-level errors from an ActionResult.
- *
- * Pure function (no internal hooks) — follows React naming convention
- * since it's used in render. Accepts the result from `useActionState`
- * or flash data from `getFormFlash()`.
- *
- * @example
- * ```tsx
- * const [result, action, isPending] = useActionState(createTodo, null)
- * const errors = useFormErrors(result)
- *
- * return (
- *   <form action={action}>
- *     <input name="title" />
- *     {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
- *     {errors.formErrors.map(e => <p key={e}>{e}</p>)}
- *   </form>
- * )
- * ```
+ * Derive FormErrorsResult from an action result.
+ * Used internally by useActionState 4th tuple element.
+ * @internal — exported for test access only.
  */
-export function useFormErrors<TData>(
+export function deriveFormErrors<TData>(
   result:
     | ActionResult<TData>
     | {

package/src/client/history.ts

@@ -1,16 +1,17 @@
 // History Stack — stores RSC payloads by URL for instant back/forward navigation
 // See design/19-client-navigation.md § History Stack
 
-import type { HeadElement } from './head';
-
 // ─── Types ───────────────────────────────────────────────────────
 
 export interface HistoryEntry {
   /** The complete segment tree payload at the time of navigation */
   payload: unknown;
-  /** Resolved head elements for this page (title, meta tags). Null for SSR'd initial page. */
-  headElements?: HeadElement[] | null;
-  /** Route params for this page (for useParams). Null for SSR'd initial page. */
+  /**
+   * Route params for this page (for useSegmentParams). Every entry that can
+   * be replayed must carry them — the initial SSR entry gets them from the
+   * server-embedded __timber_params, navigation entries from X-Timber-Params,
+   * and revalidation overwrites preserve the current state (TIM-1037).
+   */
   params?: Record<string, string | string[]> | null;
 }
 
@@ -23,8 +24,11 @@ export interface HistoryEntry {
  * On forward navigation, the new page's payload is pushed onto the stack.
  * On popstate, the cached payload is replayed instantly.
  *
- * Scroll positions are stored in history.state (browser History API),
- * not in this stack — see design/19-client-navigation.md §Scroll Restoration.
+ * Entries are keyed by pathname + search. Used with the History API
+ * fallback and the Navigation API.
+ *
+ * Scroll positions are stored in history.state or Navigation API entry
+ * state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.
  *
  * Entries persist for the session duration (no expiry) and are cleared
  * when the tab is closed — matching browser back-button behavior.