@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.200

package/dist/server/ssr-bridge-types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * RSC ↔ SSR Bridge Contract
+ *
+ * This file defines the payload that crosses the RSC → SSR environment
+ * boundary. The RSC environment calls `handleSsr(rscStream, navContext)`
+ * in the SSR environment via `import.meta.viteRsc.import(...)` (see
+ * `rsc-entry/ssr-bridge.ts`). RSC and SSR are separate Vite module graphs
+ * with separate module instances, so every per-request field that SSR
+ * needs must be declared here and passed explicitly.
+ *
+ * Rules for changes to this file:
+ *
+ * 1. **Structurally serializable shape.** Fields must be values that can
+ *    cross the environment boundary as plain data or as platform-neutral
+ *    primitives (`Headers`, `ReadableStream`, `AbortSignal`, `Map`). Do
+ *    not add closures, class instances tied to RSC-only modules, or
+ *    anything whose identity must be preserved across the bridge.
+ *
+ * 2. **No runtime imports of RSC-only modules.** This file is read by
+ *    both environments at type-check time. Keep it type-only. Importing
+ *    an RSC-only runtime module here couples SSR to RSC internals.
+ *
+ * 3. **Shape changes are public-surface changes.** Adding, removing, or
+ *    renaming a field is a change to the contract between two
+ *    independently-built bundles. Update every caller in the same PR —
+ *    do not rely on back-compat shims.
+ *
+ * See `design/02-rendering-pipeline.md` §"RSC → SSR → Client Hydration"
+ * and `CLAUDE.md` §"RSC and SSR Are Separate Vite Environments".
+ */
+import type { CoercedParams } from '../shared/param-value.ts';
+import type { SlotParamsRecord } from '../shared/slot-params.ts';
+/**
+ * Navigation context passed from the RSC environment to SSR.
+ *
+ * Per-request state must be explicitly passed across the RSC→SSR
+ * environment boundary since they are separate Vite module graphs.
+ */
+export interface NavContext {
+    /** The requested pathname */
+    pathname: string;
+    /**
+     * The app-visible raw query string (`''` or `?…`), with the framework's
+     * `_rsc` cache key stripped — from `appVisibleSearch()`. The single
+     * representation of the request's search state on this contract: it feeds
+     * `NavigationProvider`, the nuqs SSR adapter, and the ALS-backed SSR data,
+     * so `useSearchParams()`, nuqs hooks, and `<Link preserveSearchParams>`
+     * read the identical value they will read from the address bar after
+     * hydration. The raw string preserves repeated keys (`?tag=a&tag=b`),
+     * which a collapsed `Record<string, string>` cannot represent — do not
+     * reintroduce one beside this field (TIM-1428).
+     */
+    search: string;
+    /** Extracted route segment params. Post-coercion, values may be non-string (TIM-1347). */
+    segmentParams: CoercedParams;
+    /**
+     * Per-slot segment params, keyed by slot tree path. Absent when the request
+     * rendered no slot with params of its own. Feeds `useSegmentParams(path)`
+     * during SSR and, via `__timber_slot_params`, after hydration (TIM-1285).
+     */
+    slotParams?: SlotParamsRecord;
+    /** The committed HTTP status code */
+    statusCode: number;
+    /** Response headers from middleware/proxy */
+    responseHeaders: Headers;
+    /** Pre-rendered metadata HTML to inject before </head> */
+    headHtml: string;
+    /** Inline JS for React's bootstrapScriptContent — kicks off module loading */
+    bootstrapScriptContent: string;
+    /**
+     * Request CSP nonce, generated when middleware read `ctx.nonce` for its
+     * `Content-Security-Policy` header (`getCspNonce()`). SSR passes it to
+     * Fizz (`nonce` option → bootstrap + runtime scripts), to the Flight
+     * decoder (preinit scripts), and to every timber-generated inline
+     * `<script>`. Undefined when no middleware asked for one, in which case
+     * the markup is byte-identical to a nonce-less render.
+     * See design/13-security.md §"Content Security Policy" (TIM-1414).
+     */
+    nonce?: string;
+    /** Tee'd RSC stream for client-side hydration (inlined into HTML) */
+    rscStream?: ReadableStream<Uint8Array>;
+    /** Max Suspense hold window (ms). SSR delays the first flush by this
+     *  duration, racing allReady so that fast-resolving boundaries render inline
+     *  without ever showing a fallback. Derived from route `deferSuspenseFor` exports.
+     *  See design/05-streaming.md §"deferSuspenseFor". */
+    deferSuspenseFor?: number;
+    /** Request abort signal. When the client disconnects (page refresh,
+     *  navigation away), this signal fires. Passed to renderToReadableStream
+     *  so React stops rendering and doesn't fire error boundaries for aborts. */
+    signal?: AbortSignal;
+    /** Request cookies as name→value pairs. Used by useCookie() during SSR
+     *  to return correct cookie values before hydration. */
+    cookies?: Map<string, string>;
+    /**
+     * Lazy thunk that produces the `<script>self.__timber_segments=…</script>`
+     * tag. Invoked by the SSR entry AFTER `renderSsrNodeStream` /
+     * `renderSsrStream` returns (shell ready ⇒ AccessGates settled), so the
+     * `getFirstDeniedSegmentIndex()` ALS value is authoritative. The result
+     * is appended to headHtml before the head injector runs.
+     *
+     * Undefined when client JS is disabled (no client to consume it).
+     * See TIM-1365, TIM-1359.
+     */
+    getHeadSegmentScript?: () => string;
+    /**
+     * Mutable flag: set by TimberErrorBoundary during SSR when it catches
+     * a DenySignal (via digest). This tells the RSC entry that the denial
+     * was contained by a slot error boundary and should NOT be promoted
+     * to a page-level deny. See LOCAL-298.
+     */
+    _denyHandledByBoundary?: boolean;
+    /**
+     * Mutable: SSR timing data populated by handleSsr().
+     * Read by the RSC entry to record sub-phase Server-Timing entries
+     * when `serverTiming: 'detailed'` is configured.
+     *
+     * This bridges the RSC→SSR environment boundary: the SSR entry populates
+     * these fields, the RSC entry reads them after callSsr() returns.
+     */
+    _ssrTimings?: {
+        /** Time to decode RSC stream (createFromReadableStream/createFromNodeStream) */
+        decodeMs: number;
+        /** Time for Fizz to render the shell (onShellReady) */
+        shellMs: number;
+        /** Time for pipe() to flush shell bytes to the output stream */
+        pipeMs: number;
+        /** Time to set up Node.js Transform pipeline / Web Stream transforms */
+        pipelineMs: number;
+        /** Total SSR time (decode → response ready) */
+        totalMs: number;
+        /** Whether the Node.js native stream path was used */
+        nodeStreams: boolean;
+    };
+    /**
+     * Signal that fires when an unhandled RSC error is detected.
+     * The Flight injector checks this before writing each script tag —
+     * when aborted, it stops injecting Flight data to prevent corrupted
+     * chunks from crashing the client's Flight decoder.
+     */
+    _errorSignal?: AbortSignal;
+    /**
+     * Mutable flag: set by the SSR entry when Fizz's `stream.allReady`
+     * settled before the `deferSuspenseFor` hold ended.
+     *
+     * When true, the RSC entry can skip its signal-promotion
+     * microtask-retry wait: Fizz allReady implies Flight closed its
+     * stream, which implies `onError` already fired for every rejected
+     * Flight task. Any DenySignal/RedirectSignal/RenderError in-tree has
+     * already been captured in `RenderSignals`.
+     *
+     * When false or undefined (hold timed out, no hold window, shell-only
+     * return, Node error path), no such guarantee — the RSC entry falls
+     * back to the bounded microtask retry loop.
+     *
+     * See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
+     * and design/spike-signal-promotion-protocol.md (Option 1).
+     */
+    _fizzAllReadyResolved?: boolean;
+}
+//# sourceMappingURL=ssr-bridge-types.d.ts.map

package/dist/server/ssr-bridge-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-bridge-types.d.ts","sourceRoot":"","sources":["../../src/server/ssr-bridge-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,aAAa,EAAE,aAAa,CAAC;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,MAAM,MAAM,CAAC;IAEpC;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QACZ,gFAAgF;QAChF,QAAQ,EAAE,MAAM,CAAC;QACjB,uDAAuD;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,gEAAgE;QAChE,MAAM,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,UAAU,EAAE,MAAM,CAAC;QACnB,+CAA+C;QAC/C,OAAO,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IAEF;;;;;OAKG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC;IAE3B;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC"}

package/dist/server/ssr-entry.d.ts

@@ -11,49 +11,7 @@
  *
  * Design docs: 18-build-system.md §"Entry Files", 02-rendering-pipeline.md
  */
-/**
- * Navigation context passed from the RSC environment to SSR.
- *
- * Per-request state must be explicitly passed across the RSC→SSR
- * environment boundary since they are separate Vite module graphs.
- */
-export interface NavContext {
-    /** The requested pathname */
-    pathname: string;
-    /** Extracted route params (catch-all segments produce string[]) */
-    params: Record<string, string | string[]>;
-    /** Search params from the URL */
-    searchParams: Record<string, string>;
-    /** The committed HTTP status code */
-    statusCode: number;
-    /** Response headers from middleware/proxy */
-    responseHeaders: Headers;
-    /** Pre-rendered metadata HTML to inject before </head> */
-    headHtml: string;
-    /** Inline JS for React's bootstrapScriptContent — kicks off module loading */
-    bootstrapScriptContent: string;
-    /** Tee'd RSC stream for client-side hydration (inlined into HTML) */
-    rscStream?: ReadableStream<Uint8Array>;
-    /** Max Suspense hold window (ms). SSR delays the first flush by this
-     *  duration, racing allReady so that fast-resolving boundaries render inline
-     *  without ever showing a fallback. Derived from route `deferSuspenseFor` exports.
-     *  See design/05-streaming.md §"deferSuspenseFor". */
-    deferSuspenseFor?: number;
-    /** Request abort signal. When the client disconnects (page refresh,
-     *  navigation away), this signal fires. Passed to renderToReadableStream
-     *  so React stops rendering and doesn't fire error boundaries for aborts. */
-    signal?: AbortSignal;
-    /** Request cookies as name→value pairs. Used by useCookie() during SSR
-     *  to return correct cookie values before hydration. */
-    cookies?: Map<string, string>;
-    /**
-     * Mutable flag: set by TimberErrorBoundary during SSR when it catches
-     * a DenySignal (via digest). This tells the RSC entry that the denial
-     * was contained by a slot error boundary and should NOT be promoted
-     * to a page-level deny. See LOCAL-298.
-     */
-    _denyHandledByBoundary?: boolean;
-}
+import type { NavContext } from './ssr-bridge-types.ts';
 /**
  * Handle SSR: decode an RSC stream and render it to hydration-ready HTML.
  *

package/dist/server/ssr-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA6BH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CA4EnB;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA+BH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAiDxD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAsNnB;eAEc,SAAS"}

package/dist/server/ssr-render.d.ts

@@ -5,6 +5,17 @@
  * independently of the Vite RSC plugin runtime (which provides
  * createFromReadableStream for decoding RSC streams).
  *
+ * Uses a platform-adaptive rendering strategy:
+ * - **Node.js / Bun**: `renderToPipeableStream` — React pipes HTML chunks
+ *   through Node.js native streams (C++ implementation). Each chunk flows
+ *   through libuv buffers with zero Promise overhead.
+ * - **Cloudflare Workers / Edge**: `renderToReadableStream` — React outputs
+ *   to Web Streams which are V8-native C++ built-ins on these platforms.
+ *
+ * The detection is automatic at runtime. Both paths produce a Web
+ * `ReadableStream<Uint8Array>` so downstream transforms (injectHead,
+ * injectRscPayload, compression) work identically regardless of platform.
+ *
  * Design docs: 02-rendering-pipeline.md §"Single-Pass Rendering",
  *              18-build-system.md §"Entry Files"
  */
@@ -12,56 +23,92 @@ import type { ReactNode } from 'react';
 /**
  * Render a React element tree to a ReadableStream of HTML.
  *
- * Uses renderToReadableStream (NOT renderToString) for streaming SSR.
+ * Automatically selects the optimal rendering path for the platform:
+ * - Node.js/Bun: `renderToPipeableStream` → Node.js native streams → `Readable.toWeb()`
+ * - CF Workers/Edge: `renderToReadableStream` → native Web Streams
+ *
  * The returned stream begins yielding after onShellReady — everything
  * outside <Suspense> boundaries is in the shell.
  *
- * With progressive streaming, the RSC stream is piped directly to SSR
- * without buffering. If deny() was called outside a Suspense boundary,
- * the RSC stream encodes an error in the shell — renderToReadableStream
- * rejects, and the RSC entry catches this to render a deny page with
- * the correct HTTP status code. If deny() was inside Suspense, the shell
- * succeeds (200 committed) and the error streams as an error boundary.
- *
  * @param element - The React element tree decoded from the RSC stream
  * @param options - Optional configuration
- * @param options.bootstrapScriptContent - Inline JS injected by React as a
- *   non-deferred `<script>` in the shell HTML. Executes immediately during
- *   parsing — even while Suspense boundaries are still streaming. Used to
- *   kick off module loading via dynamic `import()` so hydration can start
- *   before the HTML stream closes.
  * @returns A ReadableStream of HTML bytes with hydration markers
  */
 export declare function renderSsrStream(element: ReactNode, options?: {
     bootstrapScriptContent?: string;
+    /** Request CSP nonce — stamped by Fizz on the bootstrap and runtime scripts. */
+    nonce?: string;
     deferSuspenseFor?: number;
     signal?: AbortSignal;
+    renderTimeoutMs?: number;
+    /** Request info threaded into render-error logs (method/path). */
+    requestInfo?: {
+        method: string;
+        path: string;
+    };
+    /**
+     * Fired synchronously when the render function is about to resolve
+     * (i.e. at hold-end / shell-ready). `resolved` reports whether Fizz's
+     * `stream.allReady` had already settled by that moment. Callers use
+     * this to decide whether signal promotion can be short-circuited.
+     * See NavContext._fizzAllReadyResolved.
+     */
+    onFizzAllReadyResolved?: (resolved: boolean) => void;
 }): Promise<ReadableStream<Uint8Array>>;
+/** Whether the current platform uses native Node.js streams for SSR. */
+export declare const useNodeStreams: boolean;
+/**
+ * Render via renderToPipeableStream, returning a Node.js Readable.
+ *
+ * The entire HTML rendering + post-processing pipeline stays in native
+ * Node.js streams (C++ backed). Only converted to Web ReadableStream
+ * at the very end for the Response body.
+ */
+export declare function renderSsrNodeStream(element: ReactNode, options?: {
+    bootstrapScriptContent?: string;
+    /** Request CSP nonce — stamped by Fizz on the bootstrap and runtime scripts. */
+    nonce?: string;
+    deferSuspenseFor?: number;
+    signal?: AbortSignal;
+    renderTimeoutMs?: number;
+    /** Request info threaded into render-error logs (method/path). */
+    requestInfo?: {
+        method: string;
+        path: string;
+    };
+    /**
+     * Fired synchronously at the moment `renderSsrNodeStream`'s returned
+     * Promise is about to resolve. `resolved` reports whether Fizz's
+     * `onAllReady` had already fired by then. See the twin callback on
+     * `renderSsrStream`.
+     */
+    onFizzAllReadyResolved?: (resolved: boolean) => void;
+}): Promise<import('node:stream').Readable>;
+/** Convert a Node.js Readable to a Web ReadableStream (zero-copy bridge). */
+export declare function nodeReadableToWeb(readable: import('node:stream').Readable): ReadableStream<Uint8Array>;
 /**
  * Wrap an HTML stream with error handling for the streaming phase.
  *
  * During progressive RSC→SSR streaming, errors in Suspense boundaries
  * (e.g. deny() inside Suspense, throws in async components) cause
- * React DOM's renderToReadableStream to error after the shell has been
- * flushed. Without this wrapper, the stream error becomes an unhandled
- * promise rejection that crashes the process.
+ * React DOM's stream to error after the shell has been flushed. Without
+ * this wrapper, the stream error becomes an unhandled promise rejection
+ * that crashes the process.
  *
  * The wrapper catches streaming-phase errors, logs them, and closes
  * the output stream cleanly. The shell (headers, status code, content
  * outside Suspense) has already been sent to the client.
  */
 /** @internal Exported for testing only. */
-export declare function wrapStreamWithErrorHandling(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): ReadableStream<Uint8Array>;
+export declare function wrapStreamWithErrorHandling(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, nonce?: string): ReadableStream<Uint8Array>;
 /**
  * Build a Response from the SSR HTML stream with the correct
  * status code and headers from the navigation context.
  *
- * Sets content-type to text/html if not already set by middleware.
+ * React 19.3+ automatically emits `<!DOCTYPE html>` when the root
+ * element is `<html>`, so no framework-level doctype prepending is needed.
  *
- * @param htmlStream - The HTML stream from renderSsrStream
- * @param statusCode - The committed HTTP status code from RSC
- * @param responseHeaders - Response headers from middleware/proxy
- * @returns A Response ready to send to the client
+ * Sets content-type to text/html if not already set by middleware.
  */
 export declare function buildSsrResponse(htmlStream: ReadableStream<Uint8Array>, statusCode: number, responseHeaders: Headers): Response;
 //# sourceMappingURL=ssr-render.d.ts.map

package/dist/server/ssr-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr-render.d.ts","sourceRoot":"","sources":["../../src/server/ssr-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAmBvC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IAAE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC7F,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAmDrC;AAED;;;;;;;;;;;;GAYG;AACH,2CAA2C;AAC3C,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,UAAU,CAAC,CAkC5B;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,QAAQ,CASV"}
+{"version":3,"file":"ssr-render.d.ts","sourceRoot":"","sources":["../../src/server/ssr-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAsFvC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IACR,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,WAAW,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;CACtD,GACA,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAErC;AAED,wEAAwE;AACxE,eAAO,MAAM,cAAc,SAAkB,CAAC;AAU9C;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IACR,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,WAAW,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;CACtD,GACA,OAAO,CAAC,OAAO,aAAa,EAAE,QAAQ,CAAC,CAsGzC;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,aAAa,EAAE,QAAQ,GACvC,cAAc,CAAC,UAAU,CAAC,CAE5B;AA8GD;;;;;;;;;;;;GAYG;AACH,2CAA2C;AAC3C,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,cAAc,CAAC,UAAU,CAAC,CA2B5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,QAAQ,CASV"}

package/dist/server/ssr-wrappers.d.ts

@@ -0,0 +1,93 @@
+/**
+ * SSR wrapper chain — the same components the client hydration tree renders.
+ *
+ * During hydration, React's useId() generates deterministic IDs based on
+ * the component's position in the fiber tree. If the SSR tree has fewer
+ * wrapper components than the client hydration tree, every useId() call
+ * produces different IDs — causing hydration mismatches in libraries like
+ * Radix UI that rely on useId() internally.
+ *
+ * The client tree (`renderTree` in browser-entry/router-init.ts, used by
+ * hydrate.ts too) wraps the RSC element with:
+ *   NavigationRoot → Fragment(TopLoader, ...) →
+ *     TimberNuqsAdapter → NuqsAdapterProvider →
+ *       SlotContentCacheContext.Provider → SegmentUpdateContext.Provider →
+ *         NavigationProvider → PayloadRoot → ParamsProvider → element
+ *
+ * The SSR tree renders the REAL NavigationProvider and PayloadRoot rather
+ * than no-op mirrors (TIM-1424). Two consequences:
+ *
+ * 1. `usePathname()` / `useSearchParams()` resolve from NavigationContext
+ *    during SSR — the same code path as the browser — with the request's
+ *    pathname and raw search string. The raw string preserves repeated
+ *    query keys (`?tag=a&tag=b`) and, since TIM-1428, is the only
+ *    representation of search state here — it feeds the nuqs SSR adapter
+ *    too, so no collapsed record exists to drift from it.
+ * 2. `useSegmentParams()` resolves from ParamsContext, published by
+ *    PayloadRoot from the same payload root row the browser will read —
+ *    one derivation on both sides instead of two that must agree.
+ *
+ * Per-request isolation is by construction: the provider values are part
+ * of this request's element tree, so concurrent requests cannot observe
+ * each other's values — stronger than the ALS path, which remains for
+ * `useCookie()` and the `_navContext` status-code channel.
+ *
+ * **What actually shifts a useId is a fork, not depth.** `useId` derives from
+ * React's tree context, which only changes where a fiber has more than one
+ * child — here, `Fragment(TopLoader, element)`. A single-child wrapper, plain
+ * component or context provider, leaves every id below it unchanged; that is
+ * verified by tests/ssr-wrapper-parity.test.ts, not assumed. So the
+ * client-only `SegmentUpdateContext.Provider` and
+ * `SlotContentCacheContext.Provider` (single child each) have no mirror
+ * here and need none. Mirror a new wrapper only if it branches.
+ *
+ * Related issues: facebook/react#24669, radix-ui/primitives#3700
+ * See design/02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
+ */
+import { type ReactNode } from 'react';
+/** Per-request inputs for the SSR wrapper chain. */
+export interface SsrWrapOptions {
+    /** Request pathname for NavigationProvider. */
+    pathname: string;
+    /**
+     * Raw app-visible query string (`''` or `?…`) for NavigationProvider AND
+     * the nuqs SSR adapter — one representation, preserving repeated keys
+     * (`?tag=a&tag=b`) on both consumers (TIM-1428).
+     */
+    search: string;
+    /**
+     * The payload's params, or a thenable of them, for PayloadRoot — the
+     * `params` half of `splitPayloadRoot(root)`. Same source the browser
+     * hands to the same component during hydration.
+     */
+    paramsSource: unknown;
+    /** Whether the top loader is enabled (must match client config). */
+    hasTopLoader: boolean;
+}
+/**
+ * Wrap the SSR element tree with the same component boundaries as the
+ * client hydration tree — real providers, not mirrors — so hooks resolve
+ * identically on both sides and useId() matches.
+ *
+ * Client tree (browser-entry/hydrate.ts):
+ *   NavigationRoot
+ *     → Fragment(TopLoader, element)
+ *       → TimberNuqsAdapter
+ *         → NuqsAdapterProvider (from createAdapterProvider)
+ *           → SlotContentCacheContext.Provider (client-only, single child)
+ *             → SegmentUpdateContext.Provider  (client-only, single child)
+ *               → NavigationProvider
+ *                 → PayloadRoot → ParamsProvider
+ *                   → [RSC element]
+ *
+ * SSR tree (this function):
+ *   SsrNavigationRoot
+ *     → Fragment(SsrTopLoader, element)
+ *       → SsrNuqsWrapper
+ *         → NuqsAdapterProvider (from withNuqsSsrAdapter → createAdapterProvider)
+ *           → NavigationProvider              (real — same component)
+ *             → PayloadRoot → ParamsProvider  (real — same components)
+ *               → [RSC element]
+ */
+export declare function wrapSsrElement(element: ReactNode, opts: SsrWrapOptions): ReactNode;
+//# sourceMappingURL=ssr-wrappers.d.ts.map

package/dist/server/ssr-wrappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-wrappers.d.ts","sourceRoot":"","sources":["../../src/server/ssr-wrappers.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAkDhE,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,GAAG,SAAS,CAmBlF"}

package/dist/server/state-tree-diff.d.ts

@@ -13,31 +13,66 @@
  * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
  * See design/13-security.md §"State tree manipulation"
  */
+/** Parsed client state tree with segment paths and optional slot paths. */
+export interface ClientStateTree extends Set<string> {
+    slots?: Set<string> | null;
+    /**
+     * `app/` directory paths of the segments currently mounted on the client.
+     * Read only by interception scoping — never by the skip decisions.
+     * See design/07-routing.md §"Intercepting Routes" (TIM-1282).
+     */
+    treePaths?: Set<string> | null;
+}
 /**
  * Parse the X-Timber-State-Tree header from a request.
  *
- * Returns a Set of segment paths the client has cached, or null if
+ * Returns a Set of segment paths the client has cached (with an
+ * additional `slots` property for cached slot paths), or null if
  * the header is missing, malformed, or empty. Parsing happens before
  * renderToReadableStream — not inside the React render pass.
  *
- * @returns Set of sync segment paths, or null if no valid state tree
+ * @returns ClientStateTree with segments and slots, or null if no valid state tree
  */
-export declare function parseClientStateTree(req: Request): Set<string> | null;
+export declare function parseClientStateTree(req: Request): ClientStateTree | null;
 /**
  * Determine whether a segment's layout rendering can be skipped.
  *
  * A segment is skipped when ALL of the following are true:
- * 1. The client has the segment in its state tree (clientSegments contains urlPath)
- * 2. The layout is sync (not an async function — async layouts always re-render)
- * 3. The segment is NOT the leaf (pages are never cached across navigations)
+ * 1. The client sent a state tree (clientSegments is non-null)
+ * 2. The client has this segment cached (clientSegments contains urlPath)
+ * 3. The segment has a layout (otherwise nothing to skip)
+ * 4. The layout is sync (not an async function — async layouts may depend
+ *    on per-request data and must always re-render)
+ * 5. The segment is NOT the leaf (pages are never cached across navigations)
+ *
+ * Additional constraints enforced by the caller (buildRouteElement):
+ * - Must have a rendered layout below (so SegmentOutlet has content to show)
+ * - Skipped segments must form a contiguous prefix from root
  *
  * Access.ts still runs for skipped segments — this is enforced by the caller
- * (buildRouteElement) which runs all access checks before building the tree.
+ * which wraps with AccessGate regardless of skip status.
  *
- * @param urlPath - The segment's URL path (e.g., "/", "/dashboard")
+ * @param segmentKey - The segment's state-tree key from computeSegmentKeys()
  * @param layoutComponent - The loaded layout component function
  * @param isLeaf - Whether this is the leaf segment (page segment)
  * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
  */
-export declare function shouldSkipSegment(_urlPath: string, _layoutComponent: ((...args: unknown[]) => unknown) | undefined, _isLeaf: boolean, _clientSegments: Set<string> | null): boolean;
+export declare function shouldSkipSegment(segmentKey: string, layoutComponent: ((...args: unknown[]) => unknown) | undefined, isLeaf: boolean, clientSegments: Set<string> | null): boolean;
+/**
+ * Determine whether a parallel route slot can be skipped.
+ *
+ * A slot is skipped when the destination content key — computed from the
+ * owning segment's URL parts, the slot name, the matched entry file, and
+ * the slot's extracted params — is in the set of keys the client advertised.
+ *
+ * This replaced URL-based departing/destination diffing in TIM-1370.
+ * The previous approach reconstructed the client's state by re-matching a
+ * departing URL against each slot's sub-tree, which was a recurring bug
+ * source because the reconstruction could drift from the client's actual
+ * mounted state. The key-based approach is a single set-membership check.
+ *
+ * This is a performance optimization only, NOT a security boundary.
+ * Slot access.ts always runs via SlotAccessGate regardless.
+ */
+export declare function shouldSkipSlot(contentKey: string, clientSlotKeys: Set<string> | null): boolean;
 //# sourceMappingURL=state-tree-diff.d.ts.map

package/dist/server/state-tree-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAarE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAC/D,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GAClC,OAAO,CAeT"}
+{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,2EAA2E;AAC3E,MAAM,WAAW,eAAgB,SAAQ,GAAG,CAAC,MAAM,CAAC;IAClD,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAwBzE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAC9D,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACjC,OAAO,CAaT;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,OAAO,CAG9F"}

package/dist/server/static-generator.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Static site generator — enumerates routes and renders them to
+ * HTML + RSC flight payloads for `output: 'static'` mode.
+ *
+ * Runs INSIDE the built RSC bundle (same pattern as prebuilt-builder.ts)
+ * so it has access to the route manifest, page module loaders, and the
+ * request pipeline handler.
+ *
+ * For each page route:
+ *   - Renders HTML (Accept: text/html) for initial load
+ *   - Renders RSC flight (Accept: text/x-component) for client SPA nav
+ *
+ * For each API route (route.ts):
+ *   - Calls the GET handler and captures the response
+ *
+ * The caller (plugins/static-build.ts) handles file I/O — keeping
+ * node:fs out of the server bundle so it runs on Cloudflare Workers.
+ *
+ * Design docs: design/11-platform.md §"static output mode"
+ */
+import type { ManifestRoot, ManifestSegmentNode } from './route-matcher.ts';
+/** A single rendered static page ready for the caller to write to disk. */
+export interface StaticPageEntry {
+    /** The URL path (e.g., "/about", "/blog/first-post"). */
+    urlPath: string;
+    /** HTTP status code from the response. */
+    status: number;
+    /** Response headers. */
+    headers: Record<string, string>;
+    /** The response body as bytes. */
+    body: Uint8Array;
+    /** Content type for choosing file extension. */
+    contentType: string;
+    /**
+     * Whether this is an RSC flight payload (for client navigation)
+     * vs an HTML page (for initial load).
+     */
+    kind: 'html' | 'rsc' | 'api';
+}
+/** An error encountered during static generation. */
+export interface StaticGenerationError {
+    urlPath: string;
+    message: string;
+    status?: number;
+}
+/** A redirect discovered during static generation. */
+export interface StaticRedirectEntry {
+    /** The source URL path (e.g., "/old-page"). */
+    from: string;
+    /** The redirect target (Location header value). */
+    to: string;
+    /** HTTP status code (301, 302, 307, 308). */
+    status: number;
+}
+/** Result of the static generation pass. */
+export interface StaticGenerationSummary {
+    /** Total pages rendered (HTML + RSC pairs count as 2). */
+    rendered: number;
+    /** Pages that failed to render. */
+    errors: StaticGenerationError[];
+    /** Redirects from middleware/proxy that need platform redirect rules. */
+    redirects: StaticRedirectEntry[];
+    /**
+     * Non-fatal problems the build should surface. Unlike `errors`, these do not
+     * fail the build — they name a degraded outcome the developer can act on
+     * (e.g. the not-found probe answering with something other than a 404).
+     */
+    warnings: string[];
+}
+export interface StaticGenerationOptions {
+    /** Called for each rendered page/asset. File I/O is the caller's job. */
+    onEntry: (entry: StaticPageEntry) => Promise<void>;
+    /** Progress/warning logger. */
+    log?: (message: string) => void;
+    /** Timeout per page render in milliseconds. Default: 30000. */
+    renderTimeoutMs?: number;
+    /**
+     * When true and no user-authored sitemap exists, the generator will
+     * render `/sitemap.xml` (and any paginated sub-sitemaps) through the
+     * handler to capture auto-generated sitemaps in the static output.
+     */
+    autoSitemapEnabled?: boolean;
+}
+interface StaticUrl {
+    urlPath: string;
+    kind: 'page' | 'api';
+}
+/**
+ * Walk the manifest tree and collect all concrete URLs to render.
+ *
+ * Static routes produce their URL directly. Dynamic routes call
+ * `generateStaticSegmentParams()` from the page module. Dynamic routes
+ * without the export are a build error in static mode.
+ */
+export declare function enumerateStaticUrls(root: ManifestSegmentNode, log: (message: string) => void, timeoutMs?: number): Promise<{
+    urls: StaticUrl[];
+    errors: StaticGenerationError[];
+}>;
+/**
+ * Generate all static pages from the route manifest.
+ *
+ * For each page: renders HTML (for initial load) and RSC flight (for SPA nav).
+ * For each API route: calls the GET handler.
+ *
+ * Must run inside the built RSC bundle — the handler and manifest are
+ * module instances from this bundle's graph.
+ */
+export declare function generateStaticSite(manifest: ManifestRoot, handler: (req: Request) => Promise<Response>, options: StaticGenerationOptions): Promise<StaticGenerationSummary>;
+/** Extract /sitemap/N.xml URLs from a sitemap index XML. */
+export declare function discoverSubSitemapUrls(xml: string): string[];
+export {};
+//# sourceMappingURL=static-generator.d.ts.map