@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/dist/client/browser-dev.d.ts

@@ -1,5 +1,6 @@
 /**
- * Dev-only browser helpers — server log replay and client error forwarding.
+ * Dev-only browser helpers — server log replay, client error forwarding,
+ * and compiling overlay.
  *
  * These are only active when import.meta.hot is available (Vite dev mode).
  * Extracted from browser-entry.ts to keep files under 500 lines.
@@ -18,6 +19,31 @@ export interface HotInterface {
  * a styled "[SERVER]" badge and call the matching console method.
  */
 export declare function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): void;
+/**
+ * Signal that an HMR/module update has started.
+ *
+ * If an update is already tracked, this increments the counter.
+ * The overlay is shown after SHOW_DELAY_MS to avoid flashing
+ * for fast updates.
+ *
+ * When the delay is 0 (E2E test override), the overlay is shown
+ * synchronously to eliminate the race where hideCompilingOverlay()
+ * clears the show timeout before it fires.
+ */
+export declare function showCompilingOverlay(): void;
+/**
+ * Signal that an HMR/module update has completed.
+ *
+ * When all pending updates are resolved, the overlay is hidden.
+ * If the overlay was never shown (update completed within the
+ * debounce window), the timeout is cleared — no visual flash.
+ *
+ * Test hook: if `window.__timber_hold_compiling_overlay` is true,
+ * the overlay stays visible. E2E tests use this to avoid a race
+ * where the RSC refresh completes between polling intervals,
+ * making the overlay impossible to observe.
+ */
+export declare function hideCompilingOverlay(): void;
 /**
  * Set up global error handlers that forward uncaught client-side
  * errors to the dev server via Vite's HMR channel.
@@ -26,4 +52,14 @@ export declare function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): voi
  * back as Vite '{ type: "error" }' payloads to trigger the overlay.
  */
 export declare function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): void;
+/**
+ * Detect errors whose `digest` marks them as a framework control-flow signal
+ * (RedirectSignal, DenySignal). These must never surface as dev overlays —
+ * they are expected during navigation and are handled by the error boundary
+ * and router. Exported for tests.
+ *
+ * See also: isControlFlowSignal() in server/primitives.ts (server-side,
+ * handles both instanceof and digest detection).
+ */
+export declare function isFrameworkSignalError(error: unknown): boolean;
 //# sourceMappingURL=browser-dev.d.ts.map

package/dist/client/browser-dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-dev.d.ts","sourceRoot":"","sources":["../../src/client/browser-dev.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAqDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,IAAI,CAwBxE;AAID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,IAAI,CA8BhF"}
+{"version":3,"file":"browser-dev.d.ts","sourceRoot":"","sources":["../../src/client/browser-dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAqDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,IAAI,CAwBxE;AAoED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAmB3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAc3C;AAID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,IAAI,CAoChF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW9D"}

package/dist/client/browser-entry/action-dispatch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Server Action Dispatch — registers the callServer callback.
+ *
+ * When React encounters a server reference (from `'use server'` modules),
+ * it calls `callServer(id, args)` to dispatch the action to the server.
+ * The RSC plugin delegates to `globalThis.__viteRscCallServer` which is
+ * set by `setServerCallback`.
+ *
+ * The callback:
+ * 1. Serializes args via `encodeReply` (RSC wire format)
+ * 2. POSTs to the current URL with `Accept: text/x-component`
+ * 3. Decodes the RSC response stream
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ */
+export declare function setupServerActions(): void;
+//# sourceMappingURL=action-dispatch.d.ts.map

package/dist/client/browser-entry/action-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-dispatch.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/action-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,wBAAgB,kBAAkB,IAAI,IAAI,CAuGzC"}

package/dist/client/browser-entry/hmr.d.ts

@@ -0,0 +1,21 @@
+/**
+ * HMR & Dev Tooling — dev-only wiring for hot module replacement.
+ *
+ * Handles:
+ * - RSC module invalidation (rsc:update → router.refresh())
+ * - Dev warnings forwarded from server via WebSocket
+ * - Server console log replay in browser
+ * - Client error forwarding to Vite error overlay
+ *
+ * See design/21-dev-server.md §"HMR Wiring"
+ */
+import type { RouterInstance } from '#client-internal';
+/**
+ * Set up HMR and dev tool integration.
+ *
+ * Reads `import.meta.hot` to register dev-only event listeners.
+ * In production builds, `import.meta.hot` is undefined and this
+ * function is a no-op.
+ */
+export declare function setupHmr(router: RouterInstance): void;
+//# sourceMappingURL=hmr.d.ts.map

package/dist/client/browser-entry/hmr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmr.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/hmr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAavD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAqCrD"}

package/dist/client/browser-entry/hydrate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Hydration — pre-hydration sequence and React root creation.
+ *
+ * Handles two paths:
+ * 1. RSC payload available: hydrateRoot with NavigationProvider wrapping
+ * 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
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+import type { TopLoaderConfig } from '../top-loader.js';
+import type { RscStreamResult } from './rsc-stream.js';
+interface HydrateOptions {
+    /** RSC stream result (null if no inlined payload) */
+    rscResult: RscStreamResult | null;
+    /** Runtime config from virtual:timber-config */
+    config: {
+        topLoader?: TopLoaderConfig;
+    };
+}
+/**
+ * Run the pre-hydration sequence: read server-embedded params and
+ * set navigation state. Must be called AFTER initRouter().
+ */
+export declare function runPreHydration(): void;
+/**
+ * Hydrate the React tree or set up deferred root creation.
+ *
+ * When an RSC payload is available, wraps it with NavigationProvider +
+ * TimberNuqsAdapter + NavigationRoot and calls hydrateRoot on the
+ * document.
+ *
+ * When no RSC payload is available (JS-only client), sets up deferred
+ * navigation so the first client navigation creates the React root.
+ */
+export declare function hydrateApp({ rscResult, config }: HydrateOptions): void;
+export {};
+//# sourceMappingURL=hydrate.d.ts.map

package/dist/client/browser-entry/hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAcH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAwCvD,UAAU,cAAc;IACtB,qDAAqD;IACrD,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,gDAAgD;IAChD,MAAM,EAAE;QAAE,SAAS,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAiBtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,IAAI,CAyEtE"}

package/dist/client/browser-entry/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Browser Entry — Client-side hydration and navigation bootstrap.
+ *
+ * This is the thin orchestrator that coordinates the bootstrap sequence.
+ * Each responsibility is extracted into a focused module:
+ *
+ *   action-dispatch.ts  — server action callServer callback
+ *   rsc-stream.ts       — __timber_f chunk handling + ReadableStream
+ *   router-init.ts      — createRouter + Navigation API setup
+ *   hydrate.ts          — pre-hydration sequence + hydrateRoot/createRoot
+ *   post-hydration.ts   — history stack, segment cache, popstate, scroll
+ *   hmr.ts              — dev-only HMR + error forwarding
+ *   scroll.ts           — getScrollY helper
+ *
+ * Bootstrap call order contract:
+ *
+ *   1. setupServerActions()      — register callServer (independent)
+ *   2. createRscPayloadStream()  — decode inlined RSC payload
+ *   3. createTimberRouter()      — create router + Navigation API
+ *   4. runPreHydration()         — set params + navigation state
+ *   5. hydrateApp()              — hydrateRoot or deferred createRoot
+ *   6. setupPostHydration()      — history stack, popstate, scroll
+ *   7. setupHmr()                — dev-only HMR wiring
+ *   8. timber-ready signal       — E2E test readiness indicator
+ *
+ * Design docs: 18-build-system.md §"Entry Files", 19-client-navigation.md
+ */
+import 'virtual:timber-search-params-registry';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/browser-entry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAQH,OAAO,uCAAuC,CAAC"}

package/dist/client/browser-entry/post-hydration.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Post-Hydration Wiring — history stack, segment cache, popstate, scroll.
+ *
+ * Sets up everything that needs to happen after the React root exists:
+ * - Stores initial page in history stack for instant back navigation
+ * - Initializes scroll state for the initial entry
+ * - Populates segment cache from server-embedded metadata
+ * - Registers popstate handler for back/forward navigation
+ * - Sets up debounced scroll position saving
+ *
+ * See design/19-client-navigation.md §"History Stack"
+ */
+import type { RouterInstance } from '#client-internal';
+import type { NavigationApiController } from '../navigation-api.js';
+interface PostHydrationOptions {
+    router: RouterInstance;
+    navApiController: NavigationApiController | null;
+    /** Decoded RSC element from initial SSR (null if no RSC payload) */
+    initialElement: unknown;
+}
+/**
+ * Wire up post-hydration event handlers and state.
+ */
+export declare function setupPostHydration({ router, navApiController, initialElement, }: PostHydrationOptions): void;
+export {};
+//# sourceMappingURL=post-hydration.d.ts.map

package/dist/client/browser-entry/post-hydration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hydration.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/post-hydration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE,UAAU,oBAAoB;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACjD,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,gBAAgB,EAChB,cAAc,GACf,EAAE,oBAAoB,GAAG,IAAI,CA6E7B"}

package/dist/client/browser-entry/router-init.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Router Initialization — creates the timber router with all dependencies.
+ *
+ * Wires up RouterDeps (fetch, history, scroll, RSC decoding, render
+ * callbacks) and optionally sets up Navigation API integration.
+ *
+ * See design/19-client-navigation.md §"Navigation API Integration"
+ */
+import type { RouterInstance } from '#client-internal';
+import { type NavigationApiController } from '../navigation-api.js';
+export interface RouterInitOptions {
+    initialElement?: unknown;
+    clientSegmentCache?: boolean;
+}
+export interface RouterInitResult {
+    router: RouterInstance;
+    navApiController: NavigationApiController | null;
+}
+/**
+ * Create and register the global timber router.
+ *
+ * Must be called before hydrateRoot so `useRouter()` works during
+ * the initial render (methods lazily resolve the router at invocation,
+ * not render time, but initRouter must still run first).
+ */
+export declare function createTimberRouter(options?: RouterInitOptions): RouterInitResult;
+//# sourceMappingURL=router-init.d.ts.map

package/dist/client/browser-entry/router-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-init.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/router-init.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAc,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAUnE,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,uBAAuB,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,CA+OhF"}

package/dist/client/browser-entry/rsc-stream.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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"
+ */
+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 declare function createRscPayloadStream(): RscStreamResult | null;
+//# sourceMappingURL=rsc-stream.d.ts.map

package/dist/client/browser-entry/rsc-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-stream.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/rsc-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,GAAG,IAAI,CA+H/D"}

package/dist/client/browser-entry/scroll.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function scrollToHashTarget(hash: string): boolean;
+export declare function getScrollY(): number;
+//# sourceMappingURL=scroll.d.ts.map

package/dist/client/browser-entry/scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/scroll.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAaxD;AAED,wBAAgB,UAAU,IAAI,MAAM,CAQnC"}

package/dist/client/error-boundary.d.ts

@@ -18,17 +18,24 @@
 import { Component, type ReactNode } from 'react';
 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;

package/dist/client/error-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../src/client/error-boundary.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AA6CjE,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,iBAAiB,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,SAAS,CAAC;IACrD;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,UAAU,wBAAwB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAID,qBAAa,mBAAoB,SAAQ,SAAS,CAChD,wBAAwB,EACxB,wBAAwB,CACzB;gBACa,KAAK,EAAE,wBAAwB;IAK3C,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,wBAAwB;IAYvE,kBAAkB,CAAC,SAAS,EAAE,wBAAwB,GAAG,IAAI;IAS7D,mDAAmD;IACnD,OAAO,CAAC,KAAK,CAEX;IAEF,MAAM,IAAI,SAAS;CAyDpB"}
+{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../src/client/error-boundary.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AA8CjE,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,SAAS,CAAC;IACtD;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,UAAU,wBAAwB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAkBD,qBAAa,mBAAoB,SAAQ,SAAS,CAChD,wBAAwB,EACxB,wBAAwB,CACzB;IACC,YAAY,KAAK,EAAE,wBAAwB,EAG1C;IAED,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,wBAAwB,CAUtE;IAED,kBAAkB,CAAC,SAAS,EAAE,wBAAwB,GAAG,IAAI,CAO5D;IAED,mDAAmD;IACnD,OAAO,CAAC,KAAK,CAEX;IAEF,MAAM,IAAI,SAAS,CA2IlB;CACF"}

package/dist/client/error-boundary.js

@@ -1,6 +1,7 @@
 "use client";
 "use client";
-import { n as getSsrData } from "../_chunks/ssr-data-MjmprTmO.js";
+import { n as getSsrData } from "../_chunks/ssr-data-BOWsq18U.js";
+import { n as getRouterOrNull } from "../_chunks/router-ref-CtmF-aPv.js";
 import { Component, createElement } from "react";
 //#region src/client/error-boundary.tsx
 /**
@@ -29,6 +30,8 @@ if (typeof window !== "undefined") {
 		_isUnloading = true;
 	});
 }
+var _handledRedirects = /* @__PURE__ */ new WeakSet();
+var _pendingRedirectLocation = null;
 var TimberErrorBoundary = class extends Component {
 	constructor(props) {
 		super(props);
@@ -64,19 +67,51 @@ var TimberErrorBoundary = class extends Component {
 		if (!this.state.hasError || !this.state.error) return this.props.children;
 		const error = this.state.error;
 		const parsed = parseDigest(error);
-		if (parsed?.type === "redirect") throw error;
+		if (parsed?.type === "redirect") {
+			if (typeof window === "undefined") throw error;
+			if (!(_handledRedirects.has(error) || _pendingRedirectLocation === parsed.location)) {
+				_handledRedirects.add(error);
+				const router = getRouterOrNull();
+				if (router) {
+					_pendingRedirectLocation = parsed.location;
+					queueMicrotask(() => {
+						router.navigate(parsed.location, { replace: true }).catch(() => {
+							window.location.href = parsed.location;
+						}).finally(() => {
+							_pendingRedirectLocation = null;
+						});
+					});
+				} else window.location.href = parsed.location;
+			}
+			return null;
+		}
 		if (this.props.status != null) {
 			const errorStatus = getErrorStatus(parsed, error);
 			if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) throw error;
 		}
-		if (parsed?.type === "deny" && this.props.isSlotBoundary) {
-			const ssrData = getSsrData();
-			if (ssrData?._navContext) ssrData._navContext._denyHandledByBoundary = true;
+		if (parsed?.type === "deny") {
+			if (this.props.fallbackElement == null || this.props.isSlotBoundary) {
+				const ssrData = getSsrData();
+				if (ssrData?._navContext) {
+					ssrData._navContext._denyHandledByBoundary = true;
+					if (!this.props.isSlotBoundary) ssrData._navContext.statusCode = parsed.status;
+				}
+			}
+		}
+		if (this.props.fallbackElement != null) return this.props.fallbackElement;
+		if (parsed?.type === "deny") {
+			if (this.props.status != null) return createElement(this.props.fallbackComponent, {
+				status: parsed.status,
+				dangerouslyPassData: parsed.data
+			});
+			return createElement(this.props.fallbackComponent, {
+				error,
+				digest: null,
+				reset: this.reset,
+				status: parsed.status,
+				dangerouslyPassData: parsed.data
+			});
 		}
-		if (parsed?.type === "deny") return createElement(this.props.fallbackComponent, {
-			status: parsed.status,
-			dangerouslyPassData: parsed.data
-		});
 		const digest = parsed?.type === "render-error" ? {
 			code: parsed.code,
 			data: parsed.data
@@ -98,7 +133,9 @@ function parseDigest(error) {
 	try {
 		const parsed = JSON.parse(raw);
 		if (parsed && typeof parsed === "object" && typeof parsed.type === "string") return parsed;
-	} catch {}
+	} catch (e) {
+		console.debug("[timber] error digest is not valid JSON:", e instanceof Error ? e.message : e);
+	}
 	return null;
 }
 /**

package/dist/client/error-boundary.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-boundary.js","names":[],"sources":["../../src/client/error-boundary.tsx"],"sourcesContent":["'use client';\n\n/**\n * Framework-injected React error boundary.\n *\n * Catches errors thrown by children and renders a fallback component\n * with the appropriate props based on error type:\n *   - DenySignal (4xx) → { status, dangerouslyPassData }\n *   - RenderError (5xx) → { error, digest, reset }\n *   - Unhandled error → { error, digest: null, reset }\n *\n * The `status` prop controls which errors this boundary catches:\n *   - Specific code (e.g. 403) → only that status\n *   - Category (400) → any 4xx\n *   - Category (500) → any 5xx\n *   - Omitted → catches everything (error.tsx behavior)\n *\n * See design/10-error-handling.md §\"Status-Code Files\"\n */\n\nimport { Component, createElement, type ReactNode } from 'react';\nimport { getSsrData } from './ssr-data.js';\n\n// ─── Page Unload Detection ───────────────────────────────────────────────────\n// Track whether the page is being unloaded (user refreshed or navigated away).\n// When this is true, error boundaries suppress activation — the error is from\n// the aborted connection, not an application error.\nlet _isUnloading = false;\nif (typeof window !== 'undefined') {\n  window.addEventListener('beforeunload', () => {\n    _isUnloading = true;\n  });\n  window.addEventListener('pagehide', () => {\n    _isUnloading = true;\n  });\n}\n\n// ─── Digest Types ────────────────────────────────────────────────────────────\n\n/** Structured digest returned by RSC onError for DenySignal. */\ninterface DenyDigest {\n  type: 'deny';\n  status: number;\n  data: unknown;\n}\n\n/** Structured digest returned by RSC onError for RenderError. */\ninterface RenderErrorDigest {\n  type: 'render-error';\n  code: string;\n  data: unknown;\n  status: number;\n}\n\n/** Structured digest returned by RSC onError for RedirectSignal. */\ninterface RedirectDigest {\n  type: 'redirect';\n  location: string;\n  status: number;\n}\n\ntype ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;\n\n// ─── Props & State ───────────────────────────────────────────────────────────\n\nexport interface TimberErrorBoundaryProps {\n  /** The component to render when an error is caught. */\n  fallbackComponent: (...args: unknown[]) => ReactNode;\n  /**\n   * Status code filter. If set, only catches errors matching this status.\n   * 400 = any 4xx, 500 = any 5xx, specific number = exact match.\n   */\n  status?: number;\n  /**\n   * When true, catching a DenySignal sets _denyHandledByBoundary on the\n   * nav context to prevent page-level deny promotion. Only slot catch-all\n   * boundaries should set this — segment boundaries (403.tsx, 4xx.tsx,\n   * error.tsx) must NOT, otherwise normal page denies get swallowed.\n   */\n  isSlotBoundary?: boolean;\n  children: ReactNode;\n}\n\ninterface TimberErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n// ─── Component ───────────────────────────────────────────────────────────────\n\nexport class TimberErrorBoundary extends Component<\n  TimberErrorBoundaryProps,\n  TimberErrorBoundaryState\n> {\n  constructor(props: TimberErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): TimberErrorBoundaryState {\n    // Suppress error boundaries during page unload (refresh/navigate away).\n    // The aborted connection causes React's streaming hydration to error,\n    // but the page is about to be replaced — showing an error boundary\n    // would be a jarring flash for the user.\n    if (_isUnloading) {\n      return { hasError: false, error: null };\n    }\n\n    return { hasError: true, error };\n  }\n\n  componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {\n    // Reset error state when children change (e.g. client-side navigation).\n    // Without this, navigating from one error page to another keeps the\n    // stale error — getDerivedStateFromError doesn't re-fire for new children.\n    if (this.state.hasError && prevProps.children !== this.props.children) {\n      this.setState({ hasError: false, error: null });\n    }\n  }\n\n  /** Reset the error state so children re-render. */\n  private reset = () => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    if (!this.state.hasError || !this.state.error) {\n      return this.props.children;\n    }\n\n    const error = this.state.error;\n    const parsed = parseDigest(error);\n\n    // RedirectSignal errors must propagate through all error boundaries\n    // so the SSR shell fails and the pipeline catch block can produce a\n    // proper HTTP redirect response. See design/04-authorization.md.\n    if (parsed?.type === 'redirect') {\n      throw error;\n    }\n\n    // If this boundary has a status filter, check whether the error matches.\n    // Non-matching errors re-throw so an outer boundary can catch them.\n    if (this.props.status != null) {\n      const errorStatus = getErrorStatus(parsed, error);\n      if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) {\n        // Re-throw: this boundary doesn't handle this error.\n        throw error;\n      }\n    }\n\n    // Report DenySignal handling to prevent page-level promotion — but only\n    // for slot boundaries. Segment boundaries (403.tsx, 4xx.tsx, error.tsx)\n    // must NOT set this flag, otherwise normal page/hold-window denies get\n    // swallowed as 200 with boundary HTML instead of the intended 4xx.\n    // Runs here in render() (not getDerivedStateFromError) so the status\n    // filter has already been applied — non-matching boundaries re-threw above.\n    // See LOCAL-298.\n    if (parsed?.type === 'deny' && this.props.isSlotBoundary) {\n      const ssrData = getSsrData();\n      if (ssrData?._navContext) {\n        ssrData._navContext._denyHandledByBoundary = true;\n      }\n    }\n\n    // Render the fallback component with the right props shape.\n    if (parsed?.type === 'deny') {\n      return createElement(this.props.fallbackComponent as never, {\n        status: parsed.status,\n        dangerouslyPassData: parsed.data,\n      });\n    }\n\n    // 5xx / RenderError / unhandled error\n    const digest =\n      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;\n\n    return createElement(this.props.fallbackComponent as never, {\n      error,\n      digest,\n      reset: this.reset,\n    });\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\n/**\n * Parse the structured digest from the error.\n * React sets `error.digest` from the string returned by RSC's onError.\n */\nfunction parseDigest(error: Error): ParsedDigest | null {\n  const raw = (error as { digest?: string }).digest;\n  if (typeof raw !== 'string') return null;\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {\n      return parsed as ParsedDigest;\n    }\n  } catch {\n    // Not JSON — legacy or unknown digest format\n  }\n  return null;\n}\n\n/**\n * Extract the HTTP status code from a parsed digest or error message.\n * Falls back to message pattern matching for errors without a digest.\n */\nfunction getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {\n  if (parsed?.type === 'deny') return parsed.status;\n  if (parsed?.type === 'render-error') return parsed.status;\n  if (parsed?.type === 'redirect') return parsed.status;\n\n  // Fallback: parse DenySignal message pattern for errors that lost their digest\n  const match = error.message.match(/^Access denied with status (\\d+)$/);\n  if (match) return parseInt(match[1], 10);\n\n  // Unhandled errors are implicitly 500\n  return 500;\n}\n\n/**\n * Check whether an error's status matches the boundary's status filter.\n * Category markers (400, 500) match any status in that range.\n */\nfunction statusMatches(boundaryStatus: number, errorStatus: number): boolean {\n  // Category catch-all: 400 matches any 4xx, 500 matches any 5xx\n  if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;\n  if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;\n  // Exact match\n  return boundaryStatus === errorStatus;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA2BA,IAAI,eAAe;AACnB,IAAI,OAAO,WAAW,aAAa;AACjC,QAAO,iBAAiB,sBAAsB;AAC5C,iBAAe;GACf;AACF,QAAO,iBAAiB,kBAAkB;AACxC,iBAAe;GACf;;AAwDJ,IAAa,sBAAb,cAAyC,UAGvC;CACA,YAAY,OAAiC;AAC3C,QAAM,MAAM;AACZ,OAAK,QAAQ;GAAE,UAAU;GAAO,OAAO;GAAM;;CAG/C,OAAO,yBAAyB,OAAwC;AAKtE,MAAI,aACF,QAAO;GAAE,UAAU;GAAO,OAAO;GAAM;AAGzC,SAAO;GAAE,UAAU;GAAM;GAAO;;CAGlC,mBAAmB,WAA2C;AAI5D,MAAI,KAAK,MAAM,YAAY,UAAU,aAAa,KAAK,MAAM,SAC3D,MAAK,SAAS;GAAE,UAAU;GAAO,OAAO;GAAM,CAAC;;;CAKnD,cAAsB;AACpB,OAAK,SAAS;GAAE,UAAU;GAAO,OAAO;GAAM,CAAC;;CAGjD,SAAoB;AAClB,MAAI,CAAC,KAAK,MAAM,YAAY,CAAC,KAAK,MAAM,MACtC,QAAO,KAAK,MAAM;EAGpB,MAAM,QAAQ,KAAK,MAAM;EACzB,MAAM,SAAS,YAAY,MAAM;AAKjC,MAAI,QAAQ,SAAS,WACnB,OAAM;AAKR,MAAI,KAAK,MAAM,UAAU,MAAM;GAC7B,MAAM,cAAc,eAAe,QAAQ,MAAM;AACjD,OAAI,eAAe,QAAQ,CAAC,cAAc,KAAK,MAAM,QAAQ,YAAY,CAEvE,OAAM;;AAWV,MAAI,QAAQ,SAAS,UAAU,KAAK,MAAM,gBAAgB;GACxD,MAAM,UAAU,YAAY;AAC5B,OAAI,SAAS,YACX,SAAQ,YAAY,yBAAyB;;AAKjD,MAAI,QAAQ,SAAS,OACnB,QAAO,cAAc,KAAK,MAAM,mBAA4B;GAC1D,QAAQ,OAAO;GACf,qBAAqB,OAAO;GAC7B,CAAC;EAIJ,MAAM,SACJ,QAAQ,SAAS,iBAAiB;GAAE,MAAM,OAAO;GAAM,MAAM,OAAO;GAAM,GAAG;AAE/E,SAAO,cAAc,KAAK,MAAM,mBAA4B;GAC1D;GACA;GACA,OAAO,KAAK;GACb,CAAC;;;;;;;AAUN,SAAS,YAAY,OAAmC;CACtD,MAAM,MAAO,MAA8B;AAC3C,KAAI,OAAO,QAAQ,SAAU,QAAO;AACpC,KAAI;EACF,MAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,MAAI,UAAU,OAAO,WAAW,YAAY,OAAO,OAAO,SAAS,SACjE,QAAO;SAEH;AAGR,QAAO;;;;;;AAOT,SAAS,eAAe,QAA6B,OAA6B;AAChF,KAAI,QAAQ,SAAS,OAAQ,QAAO,OAAO;AAC3C,KAAI,QAAQ,SAAS,eAAgB,QAAO,OAAO;AACnD,KAAI,QAAQ,SAAS,WAAY,QAAO,OAAO;CAG/C,MAAM,QAAQ,MAAM,QAAQ,MAAM,oCAAoC;AACtE,KAAI,MAAO,QAAO,SAAS,MAAM,IAAI,GAAG;AAGxC,QAAO;;;;;;AAOT,SAAS,cAAc,gBAAwB,aAA8B;AAE3E,KAAI,mBAAmB,IAAK,QAAO,eAAe,OAAO,eAAe;AACxE,KAAI,mBAAmB,IAAK,QAAO,eAAe,OAAO,eAAe;AAExE,QAAO,mBAAmB"}
+{"version":3,"file":"error-boundary.js","names":[],"sources":["../../src/client/error-boundary.tsx"],"sourcesContent":["'use client';\n\n/**\n * Framework-injected React error boundary.\n *\n * Catches errors thrown by children and renders a fallback component\n * with the appropriate props based on error type:\n *   - DenySignal (4xx) → { status, dangerouslyPassData }\n *   - RenderError (5xx) → { error, digest, reset }\n *   - Unhandled error → { error, digest: null, reset }\n *\n * The `status` prop controls which errors this boundary catches:\n *   - Specific code (e.g. 403) → only that status\n *   - Category (400) → any 4xx\n *   - Category (500) → any 5xx\n *   - Omitted → catches everything (error.tsx behavior)\n *\n * See design/10-error-handling.md §\"Status-Code Files\"\n */\n\nimport { Component, createElement, type ReactNode } from 'react';\nimport { getSsrData } from './ssr-data.js';\nimport { getRouterOrNull } from './router-ref.js';\n\n// ─── Page Unload Detection ───────────────────────────────────────────────────\n// Track whether the page is being unloaded (user refreshed or navigated away).\n// When this is true, error boundaries suppress activation — the error is from\n// the aborted connection, not an application error.\nlet _isUnloading = false;\nif (typeof window !== 'undefined') {\n  window.addEventListener('beforeunload', () => {\n    _isUnloading = true;\n  });\n  window.addEventListener('pagehide', () => {\n    _isUnloading = true;\n  });\n}\n\n// ─── Digest Types ────────────────────────────────────────────────────────────\n\n/** Structured digest returned by RSC onError for DenySignal. */\ninterface DenyDigest {\n  type: 'deny';\n  status: number;\n  data: unknown;\n}\n\n/** Structured digest returned by RSC onError for RenderError. */\ninterface RenderErrorDigest {\n  type: 'render-error';\n  code: string;\n  data: unknown;\n  status: number;\n}\n\n/** Structured digest returned by RSC onError for RedirectSignal. */\ninterface RedirectDigest {\n  type: 'redirect';\n  location: string;\n  status: number;\n}\n\ntype ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;\n\n// ─── Props & State ───────────────────────────────────────────────────────────\n\nexport interface TimberErrorBoundaryProps {\n  /** The component to render when an error is caught. */\n  fallbackComponent?: (...args: unknown[]) => ReactNode;\n  /**\n   * Pre-rendered fallback element. Used for MDX status files which are server\n   * components and cannot be passed as function props across the RSC→client\n   * boundary. When set, rendered directly instead of calling fallbackComponent.\n   *\n   * See design/10-error-handling.md §\"Status-Code File Variants\" — MDX status\n   * files are server components by default (zero client JS).\n   */\n  fallbackElement?: ReactNode;\n  /**\n   * Status code filter. If set, only catches errors matching this status.\n   * 400 = any 4xx, 500 = any 5xx, specific number = exact match.\n   */\n  status?: number;\n  /**\n   * When true, this boundary wraps a parallel slot. Slot denials are\n   * graceful degradation — they must NOT change the HTTP status code.\n   */\n  isSlotBoundary?: boolean;\n  children: ReactNode;\n}\n\ninterface TimberErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n// Module-level guard: the first boundary to catch a given redirect digest\n// schedules the navigation and marks it handled here. Subsequent renders\n// (React retries the error-boundary render path multiple times in dev, and\n// outer boundaries that also see the error) become no-ops, preventing\n// duplicate router.navigate() calls.\nconst _handledRedirects = new WeakSet<object>();\n\n// Companion guard keyed by location: client-render redirect() (the\n// next/navigation shim) throws a FRESH error instance on every render\n// attempt, and React replays the errored render — so the WeakSet alone\n// would schedule the navigation twice. While a navigation to a location\n// is pending, further redirect errors for the same location are no-ops.\nlet _pendingRedirectLocation: string | null = null;\n\n// ─── Component ───────────────────────────────────────────────────────────────\n\nexport class TimberErrorBoundary extends Component<\n  TimberErrorBoundaryProps,\n  TimberErrorBoundaryState\n> {\n  constructor(props: TimberErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): TimberErrorBoundaryState {\n    // Suppress error boundaries during page unload (refresh/navigate away).\n    // The aborted connection causes React's streaming hydration to error,\n    // but the page is about to be replaced — showing an error boundary\n    // would be a jarring flash for the user.\n    if (_isUnloading) {\n      return { hasError: false, error: null };\n    }\n\n    return { hasError: true, error };\n  }\n\n  componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {\n    // Reset error state when children change (e.g. client-side navigation).\n    // Without this, navigating from one error page to another keeps the\n    // stale error — getDerivedStateFromError doesn't re-fire for new children.\n    if (this.state.hasError && prevProps.children !== this.props.children) {\n      this.setState({ hasError: false, error: null });\n    }\n  }\n\n  /** Reset the error state so children re-render. */\n  private reset = () => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    if (!this.state.hasError || !this.state.error) {\n      return this.props.children;\n    }\n\n    const error = this.state.error;\n    const parsed = parseDigest(error);\n\n    // RedirectSignal handling splits by environment:\n    //\n    // - SSR (no window): re-throw so the Fizz shell fails and the server\n    //   pipeline catch block can produce a proper HTTP 3xx response. See\n    //   design/04-authorization.md.\n    //\n    // - Client (window exists): a RedirectSignal that leaked into the RSC\n    //   Flight payload during client navigation would otherwise bubble past\n    //   every error boundary to `window.onerror`, which in dev triggers the\n    //   Vite error overlay (false positive — navigation itself works).\n    //   Instead, ask the router to perform an SPA navigation to the target\n    //   and render nothing while it takes over. The router's own catch path\n    //   handles cross-origin / hard navigations. See TIM-838.\n    if (parsed?.type === 'redirect') {\n      if (typeof window === 'undefined') {\n        throw error;\n      }\n      // Dedupe: React may render the error-boundary fallback path more\n      // than once for a single caught error (dev-mode double render, and\n      // additional boundaries above us in the tree). Only schedule the\n      // navigation on the first render that sees this error instance.\n      const alreadyHandled =\n        _handledRedirects.has(error) || _pendingRedirectLocation === parsed.location;\n      if (!alreadyHandled) {\n        _handledRedirects.add(error);\n        const router = getRouterOrNull();\n        if (router) {\n          _pendingRedirectLocation = parsed.location;\n          // Schedule the navigation outside the render phase to avoid\n          // setState-during-render warnings from router state updates.\n          queueMicrotask(() => {\n            router\n              .navigate(parsed.location, { replace: true })\n              .catch(() => {\n                // Fall back to a hard navigation if the soft navigation fails.\n                window.location.href = parsed.location;\n              })\n              .finally(() => {\n                _pendingRedirectLocation = null;\n              });\n          });\n        } else {\n          // No router available (shouldn't happen post-bootstrap) — fall\n          // back to a hard navigation so the user still ends up at the\n          // target.\n          window.location.href = parsed.location;\n        }\n      }\n      return null;\n    }\n\n    // If this boundary has a status filter, check whether the error matches.\n    // Non-matching errors re-throw so an outer boundary can catch them.\n    if (this.props.status != null) {\n      const errorStatus = getErrorStatus(parsed, error);\n      if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) {\n        // Re-throw: this boundary doesn't handle this error.\n        throw error;\n      }\n    }\n\n    // Report DenySignal handling so the pipeline skips the redundant\n    // renderDenyPage() re-render — but ONLY when this boundary can fully\n    // handle the deny in-tree:\n    //\n    // ✅ TSX boundaries (fallbackComponent) — can receive runtime props\n    //    (status, dangerouslyPassData) dynamically in render()\n    // ❌ MDX boundaries (fallbackElement) — pre-rendered at tree-build time,\n    //    cannot receive runtime deny props. Must fall through to re-render.\n    //\n    // For qualifying segment boundaries: also set the HTTP status code from\n    // the DenySignal so the Response has the correct 4xx status. This runs\n    // synchronously during Fizz rendering, BEFORE onShellReady.\n    //\n    // For slot boundaries: set _denyHandledByBoundary but do NOT change\n    // statusCode — slot denials are graceful degradation.\n    //\n    // See TIM-664, LOCAL-298.\n    if (parsed?.type === 'deny') {\n      const canHandleInTree = this.props.fallbackElement == null;\n\n      if (canHandleInTree || this.props.isSlotBoundary) {\n        const ssrData = getSsrData();\n        if (ssrData?._navContext) {\n          ssrData._navContext._denyHandledByBoundary = true;\n          if (!this.props.isSlotBoundary) {\n            ssrData._navContext.statusCode = parsed.status;\n          }\n        }\n      }\n    }\n\n    // Pre-rendered fallback element (MDX status files) — render directly.\n    // MDX components are server components that cannot be passed as function\n    // props across the RSC→client boundary. Instead, they are pre-rendered\n    // as elements in the RSC environment and passed here as fallbackElement.\n    if (this.props.fallbackElement != null) {\n      return this.props.fallbackElement;\n    }\n\n    // Render the fallback component with the right props shape.\n    if (parsed?.type === 'deny') {\n      // Status-code file boundaries (404.tsx, 4xx.tsx, …) get the documented\n      // 4xx props. error.tsx boundaries (no status filter) get their\n      // documented { error, digest, reset } contract — plus the deny extras\n      // for dual-shape implementations. Without the error prop, an error.tsx\n      // reading error.message crashes on deny fall-through. See TIM-1081.\n      if (this.props.status != null) {\n        return createElement(this.props.fallbackComponent as never, {\n          status: parsed.status,\n          dangerouslyPassData: parsed.data,\n        });\n      }\n      return createElement(this.props.fallbackComponent as never, {\n        error,\n        digest: null,\n        reset: this.reset,\n        status: parsed.status,\n        dangerouslyPassData: parsed.data,\n      });\n    }\n\n    // 5xx / RenderError / unhandled error\n    const digest =\n      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;\n\n    return createElement(this.props.fallbackComponent as never, {\n      error,\n      digest,\n      reset: this.reset,\n    });\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\n/**\n * Parse the structured digest from the error.\n * React sets `error.digest` from the string returned by RSC's onError.\n */\nfunction parseDigest(error: Error): ParsedDigest | null {\n  const raw = (error as { digest?: string }).digest;\n  if (typeof raw !== 'string') return null;\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {\n      return parsed as ParsedDigest;\n    }\n  } catch (e) {\n    console.debug('[timber] error digest is not valid JSON:', e instanceof Error ? e.message : e);\n  }\n  return null;\n}\n\n/**\n * Extract the HTTP status code from a parsed digest or error message.\n * Falls back to message pattern matching for errors without a digest.\n */\nfunction getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {\n  if (parsed?.type === 'deny') return parsed.status;\n  if (parsed?.type === 'render-error') return parsed.status;\n  if (parsed?.type === 'redirect') return parsed.status;\n\n  // Fallback: parse DenySignal message pattern for errors that lost their digest\n  const match = error.message.match(/^Access denied with status (\\d+)$/);\n  if (match) return parseInt(match[1], 10);\n\n  // Unhandled errors are implicitly 500\n  return 500;\n}\n\n/**\n * Check whether an error's status matches the boundary's status filter.\n * Category markers (400, 500) match any status in that range.\n */\nfunction statusMatches(boundaryStatus: number, errorStatus: number): boolean {\n  // Category catch-all: 400 matches any 4xx, 500 matches any 5xx\n  if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;\n  if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;\n  // Exact match\n  return boundaryStatus === errorStatus;\n}\n"],"mappings":"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"}

package/dist/client/error-reconstituter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { 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 declare function ErrorReconstituter({ error: serialized, digest, reset, component, status, dangerouslyPassData, }: ErrorReconstituterProps): ReactNode;
+export {};
+//# sourceMappingURL=error-reconstituter.d.ts.map

package/dist/client/error-reconstituter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-reconstituter.d.ts","sourceRoot":"","sources":["../../src/client/error-reconstituter.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAE1E;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,UAAU,uBAAuB;IAC/B,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/C,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;QACvB,KAAK,EAAE,KAAK,CAAC;QACb,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;QAC/C,KAAK,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;QAChC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,mBAAmB,CAAC,EAAE,OAAO,CAAC;KAC/B,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EAAE,UAAU,EACjB,MAAM,EACN,KAAK,EACL,SAAS,EACT,MAAM,EACN,mBAAmB,GACpB,EAAE,uBAAuB,GAAG,SAAS,CAarC"}