@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/client/error-boundary.tsx

@@ -6,8 +6,8 @@
  * Catches errors thrown by children and renders a fallback component
  * with the appropriate props based on error type:
  *   - DenySignal (4xx) → { status, data }
- *   - RenderError (5xx) → { error, digest, reset }
- *   - Unhandled error → { error, digest: null, reset }
+ *   - Unhandled error (500) → { error, digest, reset }, where `digest` is the
+ *     ID the server logged the error with (shared/error-digest.ts)
  *
  * The `status` prop controls which errors this boundary catches:
  *   - Specific code (e.g. 403) → only that status
@@ -19,10 +19,10 @@
  */
 
 import { Component, createContext, createElement, useContext, type ReactNode } from 'react';
-import { getSsrData } from './ssr-data.ts';
 import { getRouterOrNull } from './router-ref.ts';
 import { markStaleFromError } from './stale-client.ts';
 import { StatusPageMarker } from './status-page-marker.tsx';
+import { errorDigestId } from '../shared/error-digest.ts';
 import { leaveSpa } from './router-effects.ts';
 // Page unload detection: when the page is being torn down, error boundaries
 // suppress activation — the error is from the aborted connection, not the
@@ -60,14 +60,6 @@ interface DenyDigest {
   owners?: string[];
 }
 
-/** Structured digest returned by RSC onError for RenderError. */
-interface RenderErrorDigest {
-  type: 'render-error';
-  code: string;
-  data: unknown;
-  status: number;
-}
-
 /** Structured digest returned by RSC onError for RedirectSignal. */
 interface RedirectDigest {
   type: 'redirect';
@@ -75,7 +67,7 @@ interface RedirectDigest {
   status: number;
 }
 
-type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
+type ParsedDigest = DenyDigest | RedirectDigest;
 
 // ─── Props & State ───────────────────────────────────────────────────────────
 
@@ -89,7 +81,8 @@ export interface TimberErrorBoundaryProps {
   status?: number;
   /**
    * When true, this boundary wraps a parallel slot. Slot denials are
-   * graceful degradation — they must NOT change the HTTP status code.
+   * graceful degradation: the boundary claims any addressed deny that
+   * reaches it and leaves the page's segment chain unmarked.
    */
   isSlotBoundary?: boolean;
   /**
@@ -297,7 +290,7 @@ export class TimberErrorBoundary extends Component<
       throw error;
     }
     // The terminal is where that flow ends on the client. A non-deny row
-    // nothing claimed — a RenderError or a plain crash on a route with no
+    // nothing claimed — a crash on a route with no
     // matching `error.tsx` — has no page to render in-SPA; React would
     // unmount the root. So the terminal does what the router does for an
     // error envelope (design/10 §"Error Page Rendering for Client
@@ -335,27 +328,6 @@ export class TimberErrorBoundary extends Component<
       }
     }
 
-    // Report DenySignal handling so the pipeline skips the redundant
-    // renderDenyPage() re-render.
-    //
-    // For 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 ssrData = getSsrData();
-      if (ssrData?._navContext) {
-        ssrData._navContext._denyHandledByBoundary = true;
-        if (!this.props.isSlotBoundary) {
-          ssrData._navContext.statusCode = parsed.status;
-        }
-      }
-    }
-
     return this.markStatusPage(this.renderFallback(parsed, error));
   }
 
@@ -383,13 +355,10 @@ export class TimberErrorBoundary extends Component<
       });
     }
 
-    // 5xx / RenderError / unhandled error
-    const digest =
-      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;
-
+    // Unhandled error (500)
     return createElement(this.props.fallbackComponent as never, {
       error,
-      digest,
+      digest: errorDigestId(error),
       reset: this.reset,
     });
   }
@@ -458,7 +427,6 @@ function denyError(status: number, original: Error): Error {
  */
 function getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {
   if (parsed?.type === 'deny') return parsed.status;
-  if (parsed?.type === 'render-error') return parsed.status;
   if (parsed?.type === 'redirect') return parsed.status;
 
   // Fallback: parse DenySignal message pattern for errors that lost their digest

package/src/client/error-reconstituter.tsx

@@ -30,7 +30,7 @@ export interface SerializableError {
  * Props for the ErrorReconstituter wrapper component.
  * All props are RSC-serializable:
  * - error: plain object (SerializableError)
- * - digest: plain JSON or null
+ * - digest: the server log's correlation ID for the error, or null
  * - reset: undefined (only meaningful on client after boundary catch)
  * - component: client module reference (RSC Flight serializes as opaque ref)
  * - status / data: set only when error.tsx serves a deny()
@@ -39,11 +39,11 @@ export interface SerializableError {
  */
 interface ErrorReconstituterProps {
   error: SerializableError;
-  digest: { code: string; data: unknown } | null;
+  digest: string | null;
   reset: undefined;
   component: ComponentType<{
     error: Error;
-    digest: { code: string; data: unknown } | null;
+    digest: string | null;
     reset: (() => void) | undefined;
     status?: number;
     data?: unknown;
@@ -64,10 +64,15 @@ export function ErrorReconstituter({
   status,
   data,
 }: ErrorReconstituterProps): ReactNode {
-  // Reconstitute a real Error so instanceof checks work in user code
+  // Reconstitute a real Error so instanceof checks work in user code.
+  // `new Error()` captures a stack of wherever this component renders — in
+  // SSR that is the server's bundle paths and React internals. Production
+  // serializes no stack (design/13-security.md), so the stack is set to the
+  // header line alone: nothing about the server, and the same string in SSR
+  // and on the client (TIM-1551).
   const error = Object.assign(new Error(serialized.message), {
     name: serialized.name,
-    ...(serialized.stack != null ? { stack: serialized.stack } : {}),
+    stack: serialized.stack ?? `${serialized.name}: ${serialized.message}`,
   });
 
   return createElement(component, {

package/src/client/history.ts

@@ -3,6 +3,7 @@
 
 import type { ParamsSource } from '../shared/payload-root.ts';
 import type { SegmentInfo } from '../shared/segment-info.ts';
+import { routerUrlKey } from './router-url.ts';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -42,7 +43,10 @@ export interface HistoryEntry {
  * On forward navigation, the new page's payload is pushed onto the stack.
  * On popstate, the cached payload is replayed instantly.
  *
- * Entries are keyed by pathname + search. Used with the History API
+ * Entries are keyed by pathname + search in the browser's own spelling
+ * (`routerUrlKey`), whatever spelling a caller passes: an entry stored by
+ * `navigate('/café')` is found by a traversal that reads `/caf%C3%A9` off
+ * the address bar, and `/a?` is `/a` (TIM-1541). Used with the History API
  * fallback and the Navigation API.
  *
  * Scroll positions are stored in history.state or Navigation API entry
@@ -63,6 +67,7 @@ export class HistoryStack {
   }
 
   push(url: string, entry: HistoryEntry): void {
+    url = routerUrlKey(url);
     // Push runs when a page becomes current (or hydration seeds it). Promote
     // replacements too, so the current page always survives overflow.
     this.entries.delete(url);
@@ -74,6 +79,7 @@ export class HistoryStack {
   }
 
   get(url: string): HistoryEntry | undefined {
+    url = routerUrlKey(url);
     const entry = this.entries.get(url);
     if (entry) {
       this.entries.delete(url);
@@ -84,34 +90,42 @@ export class HistoryStack {
 
   /** Presence checks (such as hover prefetch probes) do not promote entries. */
   has(url: string): boolean {
-    return this.entries.has(url);
+    return this.entries.has(routerUrlKey(url));
   }
 
   delete(url: string): boolean {
-    return this.entries.delete(url);
+    return this.entries.delete(routerUrlKey(url));
   }
 
   /**
-   * Evict all cached payloads (TIM-1476). Called after a server action
-   * that revalidated data — history entries are equally stale since they
-   * replay on back/forward without a server check. Clearing forces a
-   * fresh fetch on the next traversal.
+   * Delete all entries whose pathname matches `pathname` (TIM-1465).
+   * Used by `invalidatePath` when the invalidation target has no search
+   * string — `/products` should evict `/products?page=1` too, because
+   * `revalidatePath('/products')` invalidates the route regardless of
+   * query.
+   */
+  deleteByPathname(pathname: string): void {
+    pathname = routerUrlKey(pathname);
+    for (const url of this.entries.keys()) {
+      const qIndex = url.indexOf('?');
+      const urlPathname = qIndex === -1 ? url : url.slice(0, qIndex);
+      if (urlPathname === pathname) {
+        this.entries.delete(url);
+      }
+    }
+  }
+
+  /**
+   * Evict every entry (TIM-1476). Called after a server action that
+   * revalidated data — history entries are equally stale since they replay
+   * on back/forward without a server check. Clearing forces a fresh fetch on
+   * the next traversal.
    *
-   * The current URL's `segmentInfo` is preserved (payload nulled) so
-   * `applyActionResult` can read it to maintain the segment cache
-   * across the piggybacked revalidation. Other branches (reval.paths-
-   * only, redirect) do not call `applyActionResult`, so their entries
-   * are fully removed (codex on #1131 round 2).
+   * The current page's entry goes too. Nothing reads it for anything but a
+   * replay: the segment metadata a revalidation needs is the committer's
+   * record of the current page, not this stack's (TIM-1541).
    */
-  clearExcept(currentUrl: string): void {
-    const currentEntry = this.entries.get(currentUrl);
+  clear(): void {
     this.entries.clear();
-    if (currentEntry) {
-      this.entries.set(currentUrl, {
-        payload: null,
-        params: currentEntry.params,
-        segmentInfo: currentEntry.segmentInfo,
-      });
-    }
   }
 }

package/src/client/index.ts

@@ -7,7 +7,6 @@
 
 // JsonSerializable moved to @timber-js/app/codec as the single canonical path.
 // Re-export removed per TIM-721.
-export type { RenderErrorDigest } from './types.ts';
 
 // Navigation
 export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link.tsx';

package/src/client/internal.ts

@@ -18,13 +18,12 @@ export type {
   RouterDeps,
   RouterPhase,
   RscDecoder,
-  RootRenderer,
 } from './router-types.ts';
 export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref.ts';
 export type { NavigationEpoch } from './router-lifecycle.ts';
 
 // ── SSR bridge ───────────────────────────────────────────────────────────
-export { setSsrData, clearSsrData, getSsrData } from './ssr-data.ts';
+export { registerSsrDataProvider, getSsrData } from './ssr-data.ts';
 export type { SsrData } from './ssr-data.ts';
 
 // ── Segment context ──────────────────────────────────────────────────────
@@ -44,11 +43,7 @@ export type { HistoryEntry } from './history.ts';
 export { useSearchParams } from './use-search-params.ts';
 
 // ── Navigation context ───────────────────────────────────────────────────
-export {
-  NavigationProvider,
-  getNavigationState,
-  setNavigationState,
-} from './navigation-context.ts';
+export { NavigationProvider } from './navigation-context.ts';
 export type { NavigationState } from './navigation-context.ts';
 
 // ── Query states (internal binder) ───────────────────────────────────────

package/src/client/navigation-commit.ts

@@ -14,7 +14,8 @@ import { buildSegmentTree, type SegmentCache } from './segment-cache.ts';
 import type { HistoryStack } from './history.ts';
 import type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
 import type { ParamsSource } from '../shared/payload-root.ts';
-import { setNavigationState, type NavigationState } from './navigation-context.ts';
+import type { NavigationState } from './navigation-context.ts';
+import { parseRouterUrl } from './router-url.ts';
 import {
   statusPageRendered,
   _setStatusPageRendered,
@@ -128,10 +129,11 @@ function hasSkippedSlot(segmentInfo: SegmentInfo[] | null | undefined): boolean
 }
 
 /**
- * The metadata a history entry keeps. `skipped` describes the *response*
- * — "this slot's content was omitted" — and the entry stores no such
- * payload (it stores null). Left on the entry, the flag outlives the
- * response: `applyActionResult()` reuses the entry's metadata beside a full
+ * The metadata a committed page keeps — on its history entry, and as the
+ * current page's `committedSegmentInfo()`. `skipped` describes the
+ * *response* — "this slot's content was omitted" — and neither stores such
+ * a payload (the entry stores null). Kept, the flag outlives the response:
+ * `applyActionResult()` reuses the current page's metadata beside a full
  * re-render and would have that judged non-replayable too.
  */
 function storedSegmentInfo(segmentInfo: SegmentInfo[] | null | undefined) {
@@ -153,17 +155,30 @@ export interface PreparedNavigation {
 export interface NavigationCommitter {
   prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation;
   currentStateTree(): StateTree | undefined;
-  updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void;
+  /**
+   * The segment metadata of the page the last commit made current, as that
+   * commit recorded it — null when it carried none.
+   *
+   * Server-action responses carry no segment metadata, so a revalidation
+   * re-renders the current page with this. It is the committer's own record
+   * rather than a history-stack lookup: the stack is keyed by the URL string
+   * a navigation was asked for, and the current page is known by
+   * `window.location`'s spelling of it, and the two need not agree
+   * (`/a?` against `/a`, a percent-encoded path against a decoded one).
+   */
+  committedSegmentInfo(): SegmentInfo[] | null;
+  /** Whether segment reuse is currently suppressed (TIM-1466). */
+  isSegmentReuseSuppressed(): boolean;
+  /** Lift segment reuse suppression after fresh data has been fetched (TIM-1466). */
+  restoreSegmentReuse(): void;
 }
 
 /**
  * Derive the navigation state (pathname + search) a URL renders with.
  *
- * Pure: publishing it — the module-level fallback for tests and SSR, and the
- * globalThis bridge — is `prepareNavigation`'s commit, which runs only once
- * the render is known to have won (TIM-1301). Callers pass the returned value
- * explicitly to renderRoot/wrapPayload, so a render never depends on the
- * publish having happened first.
+ * Pure. The value travels with the tree it describes — callers pass it to
+ * `wrapPayload`, and the router's record of the displayed tree keeps it
+ * beside that tree — so there is no store to publish it to (TIM-1541).
  */
 export function deriveNavigationState(url: string): NavigationState {
   // Params are not part of it. They travel with the payload and are published
@@ -171,7 +186,7 @@ export function deriveNavigationState(url: string): NavigationState {
   // also what clears the previous route's — a route with no params of its own
   // still publishes an empty record (TIM-1294/TIM-1297, and the clearing
   // requirement from TIM-1285).
-  const parsed = new URL(url, 'http://localhost');
+  const parsed = parseRouterUrl(url);
   return { pathname: parsed.pathname || '/', search: parsed.search };
 }
 
@@ -183,6 +198,9 @@ export function createNavigationCommitter(deps: {
 }): NavigationCommitter {
   const { segmentCache, historyStack } = deps;
 
+  // See `committedSegmentInfo`. Written only by a commit.
+  let committedSegmentInfo: SegmentInfo[] | null = null;
+
   // See `reportStatusPageRendered`: a status page that commits with no
   // navigation to consume the report still empties the cache.
   _setOnStatusPageRendered(() => segmentCache.clear());
@@ -195,8 +213,7 @@ export function createNavigationCommitter(deps: {
    * navigation. What the flag gates is which parts get serialized — see
    * `currentStateTree`.
    */
-  function updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void {
-    if (!segmentInfo || segmentInfo.length === 0) return;
+  function updateSegmentCache(segmentInfo: SegmentInfo[]): void {
     const tree = buildSegmentTree(segmentInfo);
     if (tree) {
       segmentCache.set('/', tree);
@@ -204,7 +221,9 @@ export function createNavigationCommitter(deps: {
   }
 
   return {
-    updateSegmentCache,
+    committedSegmentInfo: () => committedSegmentInfo,
+    isSegmentReuseSuppressed: () => segmentCache.isReuseSuppressed(),
+    restoreSegmentReuse: () => segmentCache.restoreReuse(),
 
     /**
      * The X-Timber-State-Tree to send with the next RSC request.
@@ -236,9 +255,13 @@ export function createNavigationCommitter(deps: {
      * the URL and is what the incoming tree is *rendered* with, plus a
      * `commit` thunk that performs the writes that make a page current:
      * 1. Segment cache — update from server-provided segment metadata
-     * 2. Navigation state — pathname/search for usePathname/useSearchParams
+     * 2. The current page's segment metadata (`committedSegmentInfo`)
      * 3. History stack — store the payload for instant back/forward replay
      *
+     * Pathname and search are not written here: they are the returned
+     * `navState`, which the tree renders with and the router's record of the
+     * displayed tree keeps (browser-entry/router-init.ts `publishTree`).
+     *
      * Nothing is written until `commit()` runs, and on a transitioned
      * navigation it runs only once the transition is known to have won — see
      * `renderViaTransition` and `NavigationRoot`. A navigation superseded
@@ -281,12 +304,12 @@ export function createNavigationCommitter(deps: {
             segmentCache.clear();
           }
 
-          setNavigationState(navState);
+          committedSegmentInfo = storedSegmentInfo(segmentInfo) ?? null;
 
           historyStack.push(url, {
             payload,
             params: opts.params,
-            segmentInfo: storedSegmentInfo(segmentInfo),
+            segmentInfo: committedSegmentInfo,
           });
         },
       };

package/src/client/navigation-context.ts

@@ -12,8 +12,8 @@
  *
  * Segment params are NOT here — see the note on NavigationState below.
  *
- * By wrapping the RSC payload element in NavigationProvider inside
- * renderRoot(), the context value and the element tree are passed to
+ * By wrapping the RSC payload element in NavigationProvider inside the
+ * router's `renderTree` (browser-entry/router-init.ts), the context value and the element tree are passed to
  * reactRoot.render() in the same call — atomic by construction.
  * All consumers (usePathname, useSearchParams) see the new values in the
  * same render pass as the new tree.
@@ -43,7 +43,6 @@
  */
 
 import { createContext, useContext, createElement, type ReactNode } from 'react';
-import type { SlotParamsRecord } from '../shared/slot-params.ts';
 
 // ---------------------------------------------------------------------------
 // Context type
@@ -118,7 +117,7 @@ export interface NavigationProviderProps {
 /**
  * Wraps children with NavigationContext.Provider.
  *
- * Used in browser-entry.ts renderRoot to wrap the RSC payload element
+ * Used in browser-entry/router-init.ts `renderTree` to wrap the RSC payload element
  * so that navigation state updates atomically with the tree render.
  */
 export function NavigationProvider({
@@ -128,41 +127,6 @@ export function NavigationProvider({
   return createElement(getOrCreateContext().Provider, { value }, children);
 }
 
-// ---------------------------------------------------------------------------
-// Module-level state for renderRoot to read
-// ---------------------------------------------------------------------------
-
-/**
- * Navigation state communicated between the router and renderRoot.
- *
- * The router calls setNavigationState() before renderRoot(). The
- * renderRoot callback reads via getNavigationState() to create the
- * NavigationProvider with the correct params/pathname.
- *
- * This is NOT used by hooks directly — hooks read from React context.
- *
- * Stored on globalThis (like the context instances above) because the
- * router lives in one chunk while renderRoot lives in another. Module-
- * level variables would be separate per chunk.
- */
-const NAV_STATE_KEY = Symbol.for('__timber_nav_state');
-
-function _getNavStateStore(): { current: NavigationState } {
-  const g = globalThis as Record<symbol, unknown>;
-  if (!g[NAV_STATE_KEY]) {
-    g[NAV_STATE_KEY] = { current: { pathname: '/', search: '' } };
-  }
-  return g[NAV_STATE_KEY] as { current: NavigationState };
-}
-
-export function setNavigationState(state: NavigationState): void {
-  _getNavStateStore().current = state;
-}
-
-export function getNavigationState(): NavigationState {
-  return _getNavStateStore().current;
-}
-
 // ---------------------------------------------------------------------------
 // Pending navigation state lives in the router, not here
 // ---------------------------------------------------------------------------

package/src/client/react-root.ts

@@ -27,8 +27,9 @@ import type { TopLoaderConfig } from './top-loader.tsx';
 export interface ReactRootHost {
   /**
    * Hydrate the server HTML with `element` as the initial tree. Nothing is
-   * published on that commit — the address bar, pathname and history already
-   * describe the page the server sent.
+   * published on that commit — the router made the page current before
+   * handing it over (`RouterInstance.hydrate`), and React may never commit
+   * it: an early render switches the root to client rendering.
    */
   hydrate(element: ReactNode, options?: HydrationOptions): void;
   /**