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

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

@@ -28,11 +28,6 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
-// TIM-830: Populate the search-params registry eagerly so <Link> on the
-// client can serialize flat `Partial<T>` values synchronously during
-// render and click handlers. Side-effect-only import.
-// @ts-expect-error — virtual module provided by timber-routing plugin
-import 'virtual:timber-search-params-registry';
 // TIM-932: Populate the codec registry so Link's interpolateParams can
 // use codec.serialize() for URL construction. Side-effect-only import.
 // @ts-expect-error — virtual module provided by timber-routing plugin
@@ -40,11 +35,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 +60,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 +82,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 +98,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,
   });
 

package/src/client/browser-entry/router-init.ts

@@ -9,6 +9,8 @@
 
 import { createElement } from 'react';
 import { createFromFetch } from '../../rsc-runtime/browser.js';
+import { PayloadRoot } from '../params-context.js';
+import { readPublishedParams, type ParamsSource } from '../../shared/payload-root.js';
 import { createRouter, setGlobalRouter } from '#client-internal';
 import type { RouterDeps, RouterInstance } from '#client-internal';
 import type { NavigationState } from '#client-internal';
@@ -29,6 +31,8 @@ import { getScrollY, scrollToHashTarget } from './scroll.js';
 
 export interface RouterInitOptions {
   initialElement?: unknown;
+  /** The params the hydration payload published, beside `initialElement`. */
+  initialParams?: ParamsSource;
   clientSegmentCache?: boolean;
 }
 
@@ -58,6 +62,63 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
   // very first client navigation (before any wrapPayload call).
   let currentPayload: unknown = options?.initialElement ?? null;
 
+  // The params `currentPayload` is displayed with. Tracked beside it because
+  // the two render paths that do NOT receive a payload — a shallow search
+  // update and any re-wrap of the current tree — must republish the same
+  // record rather than dropping it. They are written together, in one place
+  // (`renderTree`), so they cannot come apart.
+  let currentParams: ParamsSource = options?.initialParams ?? readPublishedParams(undefined);
+
+  /**
+   * Build the client's wrapper chain around a tree. **The only place it is
+   * built.**
+   *
+   * Every render path goes through here — hydration builds the same chain in
+   * `hydrate.ts` against this shape, and a navigation, a shallow search
+   * update, a popstate replay and a revalidation all call this. That matters
+   * beyond tidiness: an element type present on one render and absent on the
+   * next changes the type at that position, so React unmounts and remounts
+   * everything below it, destroying the layout state partial navigation
+   * exists to preserve (caught by tests/e2e/segment-merge-navigation.test.ts
+   * when the params wrapper was conditional).
+   *
+   * `PayloadRoot` is *above* `currentPayload`, which on a partial navigation
+   * is the retained tree. That position is the whole design: it is the only
+   * provider a reader in a skipped layout can resolve to (TIM-1297).
+   *
+   * Pure — building the element does not make it the displayed one. Every
+   * caller pairs this with `publishTree` at the point the tree is actually
+   * handed to React, because a navigation builds its element before it is
+   * known to have won and a superseded one must leave `currentPayload`
+   * describing the route still on screen (TIM-1301).
+   */
+  function renderTree(
+    tree: unknown,
+    navState: NavigationState,
+    params: ParamsSource,
+    segmentUpdates?: Map<string, React.ReactNode>
+  ): React.ReactElement {
+    const withParams = createElement(PayloadRoot, { source: params }, tree as React.ReactNode);
+    const withNav = createElement(NavigationProvider, { value: navState }, withParams);
+    const withUpdates = createElement(
+      SegmentUpdateContext.Provider,
+      { value: segmentUpdates ?? EMPTY_SEGMENT_UPDATES },
+      withNav
+    );
+    return createElement(TimberNuqsAdapter, null, withUpdates);
+  }
+
+  /**
+   * Record the tree the client is now displaying, and the params published
+   * over it. Written together — the two paths that re-wrap without a fresh
+   * payload (a shallow search update, a partial navigation) read them back as
+   * a pair and would otherwise restore one route's tree with another's params.
+   */
+  function publishTree(tree: unknown, params: ParamsSource): void {
+    currentPayload = tree;
+    currentParams = params;
+  }
+
   // ─── History API Patch ──────────────────────────────────────────
   // Patch pushState/replaceState to detect external URL changes (nuqs
   // shallow updates, replaceUrl, third-party libraries). When the router
@@ -93,25 +154,20 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     if (currentSearch === navState.search) return;
     if (!currentPayload) return;
 
+    // A shallow search update does not re-render the tree from the server, so
+    // the params are unchanged — but they are the client's to publish now, and
+    // this path rebuilds the whole chain. Republishing `currentParams` is what
+    // keeps a `?q=` change from silently clearing the route's params
+    // (TIM-1285's failure mode, on a path that used to be exempt from it
+    // because the record lived inside the payload).
     const newNavState: NavigationState = {
-      params: navState.params,
       pathname: navState.pathname,
       search: currentSearch,
     };
     setNavigationState(newNavState);
 
-    const withNav = createElement(
-      NavigationProvider,
-      { value: newNavState },
-      currentPayload as React.ReactNode
-    );
-    const withUpdates = createElement(
-      SegmentUpdateContext.Provider,
-      { value: EMPTY_SEGMENT_UPDATES },
-      withNav
-    );
-    const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
-    transitionRender(wrapped);
+    publishTree(currentPayload, currentParams);
+    transitionRender(renderTree(currentPayload, newNavState, currentParams));
   }
 
   window.history.pushState = function (
@@ -179,58 +235,58 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     // Wraps with NavigationProvider + TimberNuqsAdapter.
     //
     // For navigation renders (navigate, refresh, popstate-with-fetch),
-    // navigateTransition is used instead — it wraps the entire navigation
-    // in a React transition with useOptimistic for the pending URL.
+    // navigateTransition is used instead — it hands the destination tree to
+    // React in a transition so the departing page stays visible.
     //
     // navState is passed explicitly by the router — no temporal coupling
     // with getNavigationState().
-    renderRoot: (element: unknown, navState: NavigationState) => {
-      currentPayload = element;
-      const withNav = createElement(
-        NavigationProvider,
-        { value: navState },
-        element as React.ReactNode
-      );
-      const withUpdates = createElement(
-        SegmentUpdateContext.Provider,
-        { value: EMPTY_SEGMENT_UPDATES },
-        withNav
-      );
-      const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
-      transitionRender(wrapped);
+    renderRoot: (element: unknown, navState: NavigationState, params: ParamsSource) => {
+      // These paths render what is already decided (a replay, a
+      // revalidation), so publishing here is the commit.
+      publishTree(element, params);
+      transitionRender(renderTree(element, navState, params));
     },
 
-    // Run a navigation inside a React transition with optimistic pending URL.
-    // The entire fetch + state update runs inside startTransition. useOptimistic
-    // shows the pending URL immediately and reverts to null when the transition
-    // commits (atomic with the new tree + params).
+    // Hand a navigation's tree to React in a transition (navigation-root.tsx).
+    // The fetch runs outside any transition scope; only the state update that
+    // hands the tree over is wrapped, and in a synchronous `startTransition`.
+    // Do NOT make this callback's caller an async React action — see the
+    // entanglement note in `navigateTransition` (TIM-1306, TIM-1307).
     //
     // The perform callback receives a wrapPayload function that wraps the
     // decoded RSC payload with NavigationProvider + NuqsAdapter. navState
     // is passed explicitly by the router — no getNavigationState() needed.
-    navigateTransition: (pendingUrl: string, perform) => {
-      return navigateTransition(pendingUrl, async () => {
-        const { element, decodePromise } = await perform(
+    navigateTransition: (url: string, perform) => {
+      return navigateTransition(url, async () => {
+        // What wrapPayload built, held until the transition wins. The client's
+        // record of the displayed tree is navigation state like any other, so
+        // it rides the same commit as the segment cache rather than being
+        // written as a side effect of building the element (TIM-1301).
+        let displayed: { tree: unknown; params: ParamsSource } | null = null;
+        const { element, decodePromise, commit } = await perform(
           (
             rawPayload: unknown,
             navState: NavigationState,
+            params: ParamsSource,
             segmentUpdates?: Map<string, unknown>
           ) => {
-            currentPayload = rawPayload;
-            const withNav = createElement(
-              NavigationProvider,
-              { value: navState },
-              rawPayload as React.ReactNode
-            );
-            const withUpdates = createElement(
-              SegmentUpdateContext.Provider,
-              { value: (segmentUpdates ?? EMPTY_SEGMENT_UPDATES) as Map<string, React.ReactNode> },
-              withNav
+            displayed = { tree: rawPayload, params };
+            return renderTree(
+              rawPayload,
+              navState,
+              params,
+              segmentUpdates as Map<string, React.ReactNode> | undefined
             );
-            return createElement(TimberNuqsAdapter, null, withUpdates);
           }
         );
-        return { element: element as React.ReactNode, decodePromise };
+        return {
+          element: element as React.ReactNode,
+          decodePromise,
+          commit: () => {
+            if (displayed) publishTree(displayed.tree, displayed.params);
+            commit();
+          },
+        };
       });
     },
 

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

@@ -13,12 +13,20 @@
 
 import { createFromReadableStream } from '../../rsc-runtime/browser.js';
 import { isPageUnloading } from '../unload-guard.js';
+import { splitPayloadRoot, type PublishedParams } from '../../shared/payload-root.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;
+  /**
+   * The params the same payload published beside that tree. A promise: the
+   * inlined Flight stream is still arriving when this runs, and hydration must
+   * not wait for it. `PayloadRoot` suspends on it at the position React was
+   * going to suspend on `element` anyway (TIM-1297).
+   */
+  params: Promise<PublishedParams>;
 }
 
 /**
@@ -152,6 +160,7 @@ export function createRscPayloadStream(): RscStreamResult | null {
     queueMicrotask(onDOMContentLoaded);
   }
 
-  const element = createFromReadableStream(rscPayload);
-  return { element };
+  const { tree, params } = splitPayloadRoot(createFromReadableStream(rscPayload));
+  // The stream is a thenable, so the split is asynchronous on both halves.
+  return { element: tree, params: params as Promise<PublishedParams> };
 }

package/src/client/error-boundary.tsx

@@ -21,20 +21,12 @@
 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).
-// When this is true, error boundaries suppress activation — the error is from
-// the aborted connection, not an application error.
-let _isUnloading = false;
-if (typeof window !== 'undefined') {
-  window.addEventListener('beforeunload', () => {
-    _isUnloading = true;
-  });
-  window.addEventListener('pagehide', () => {
-    _isUnloading = true;
-  });
-}
+import { markStaleFromError } from './stale-client.js';
+// Page unload detection: when the page is being torn down, error boundaries
+// suppress activation — the error is from the aborted connection, not the
+// application. unload-guard.ts is the single owner of that state; this module
+// used to keep its own copy, which drifted (TIM-1260).
+import { isPageUnloading } from './unload-guard.js';
 
 // ─── Digest Types ────────────────────────────────────────────────────────────
 
@@ -43,6 +35,12 @@ interface DenyDigest {
   type: 'deny';
   status: number;
   data: unknown;
+  /**
+   * Segment key of the segment that owns the matched deny page, present when
+   * an in-tree catch site matched a file it may not render at its own
+   * position and re-threw to reach the owner. See TIM-1356.
+   */
+  ownerKey?: string;
 }
 
 /** Structured digest returned by RSC onError for RenderError. */
@@ -86,6 +84,12 @@ export interface TimberErrorBoundaryProps {
    * graceful degradation — they must NOT change the HTTP status code.
    */
   isSlotBoundary?: boolean;
+  /**
+   * Segment key of the segment that declared this boundary. Only meaningful
+   * against a deny digest carrying an `ownerKey`. See the decline rule in
+   * `render()` and TIM-1356.
+   */
+  segmentKey?: string;
   children: ReactNode;
 }
 
@@ -124,13 +128,26 @@ export class TimberErrorBoundary extends Component<
     // The aborted connection causes React's streaming hydration to error,
     // but the page is about to be replaced — showing an error boundary
     // would be a jarring flash for the user.
-    if (_isUnloading) {
+    if (isPageUnloading()) {
       return { hasError: false, error: null };
     }
 
     return { hasError: true, error };
   }
 
+  componentDidCatch(error: Error): void {
+    // A stale bundle most often surfaces here rather than as a rejected
+    // navigation: a client reference missing from this build's manifest, or
+    // a lazily-imported chunk the CDN no longer has, thrown during render.
+    //
+    // Recording it is all that happens — this boundary still renders its
+    // fallback, and the recovery is the user's next navigation, which the
+    // router turns into a full document load. Reloading from here would be a
+    // page load the user did not ask for, on a page that may be mid-rollout
+    // and would come back just as stale (TIM-1275).
+    markStaleFromError(error);
+  }
+
   componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {
     // Reset error state when children change (e.g. client-side navigation).
     // Without this, navigating from one error page to another keeps the
@@ -204,6 +221,34 @@ export class TimberErrorBoundary extends Component<
       return null;
     }
 
+    // Owner-addressed denies: an in-tree catch site already resolved the
+    // fallback chain and matched a file it may not render at its own
+    // position, so it re-threw to reach the segment that owns that file.
+    // Every boundary but that one declines — otherwise the nearest boundary
+    // whose status filter happens to match catches first and renders the
+    // deny page at its own depth, wrapped in the layouts the hoist existed
+    // to skip, and from a different file than the chain chose. (Boundary
+    // nesting is per-segment `{status} → category → error`; the 4xx chain
+    // runs status files across ALL segments before any error.tsx, so a
+    // leaf error.tsx would otherwise beat a root 404.tsx.)
+    //
+    // Declining is the default: an unkeyed boundary — a slot boundary, or
+    // one from a construction site that builds no deny chains — never
+    // claims a deny addressed to a segment. See TIM-1356.
+    // `typeof === 'string'`, not a null check: the digest is untrusted JSON —
+    // `parseDigest` validates only `type`, and any component can set
+    // `error.digest` itself. A non-string `ownerKey` is unequal to every
+    // boundary's key, so a truthiness test would let one error decline its
+    // way past the entire tree and blank the page, where it would otherwise
+    // have hit the nearest matching boundary.
+    if (
+      parsed?.type === 'deny' &&
+      typeof parsed.ownerKey === 'string' &&
+      parsed.ownerKey !== this.props.segmentKey
+    ) {
+      throw error;
+    }
+
     // If this boundary has a status filter, check whether the error matches.
     // Non-matching errors re-throw so an outer boundary can catch them.
     if (this.props.status != null) {
@@ -267,7 +312,7 @@ export class TimberErrorBoundary extends Component<
         });
       }
       return createElement(this.props.fallbackComponent as never, {
-        error,
+        error: denyError(parsed.status, error),
         digest: null,
         reset: this.reset,
         status: parsed.status,
@@ -307,6 +352,30 @@ function parseDigest(error: Error): ParsedDigest | null {
   return null;
 }
 
+/**
+ * The Error an `error.tsx` serving a deny should receive.
+ *
+ * The error that actually arrives here is React's, not the framework's: a
+ * server-thrown error crossing Flight has its message and name replaced with
+ * a generic redacted string in production, by design. An `error.tsx` written
+ * per the docs branches on `error.message` — so handing it the redacted error
+ * gives it nothing to branch on, while the in-tree path hands the same file a
+ * `DenySignal` named error reading `Access denied with status <N>` (see
+ * `renderDenyEntry`). This reconstructs that shape from the digest, which is
+ * where the status already is.
+ *
+ * Derived from the status alone — no stack, no server data — so it is safe on
+ * the client for the same reason the digest is. See design/13-security.md
+ * §"Errors don't leak", TIM-1081.
+ */
+function denyError(status: number, original: Error): Error {
+  // A dev build may have preserved something more useful than the redaction.
+  if (original.name === 'DenySignal') return original;
+  const error = new Error(`Access denied with status ${status}`);
+  error.name = 'DenySignal';
+  return error;
+}
+
 /**
  * Extract the HTTP status code from a parsed digest or error message.
  * Falls back to message pattern matching for errors without a digest.

package/src/client/history.ts

@@ -1,7 +1,8 @@
 // History Stack — stores RSC payloads by URL for instant back/forward navigation
 // See design/19-client-navigation.md § History Stack
 
-import type { SegmentInfo } from './segment-cache';
+import type { ParamsSource } from '../shared/payload-root.js';
+import type { SegmentInfo } from '../shared/segment-info.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -9,12 +10,18 @@ export interface HistoryEntry {
   /** The complete segment tree payload at the time of navigation */
   payload: unknown;
   /**
-   * 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).
+   * The params that payload published. Replaying the tree republishes them,
+   * because the client owns the provider now and reads it from here
+   * (TIM-1297).
+   *
+   * Stored beside the tree but never *produced* beside it: both come out of
+   * one `splitPayloadRoot` on one decoded root and travel together through
+   * `prepareNavigation`, the only producer of an entry. That is the property
+   * that matters — when they were derived from separate channels, a replay
+   * could restore one route's tree with another route's params (TIM-1037,
+   * TIM-1285).
    */
-  params?: Record<string, string | string[]> | null;
+  params: ParamsSource;
   /**
    * Segment metadata for this page's route. Restored into the segment cache
    * on popstate cached replay so the next forward navigation computes a