@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/dist/server/slot-subtree-contain.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Slot subtree containment — keeps a nested `deny()` inside its slot.
+ *
+ * `SafeSlotPage` (slot-resolver.ts) catches a `DenySignal` thrown by the slot
+ * page's own body and returns the slot's fallback instead, which is what makes
+ * slot denial graceful degradation at HTTP 200. That catch covers only the
+ * function it calls. Every server component in the tree the page *returns*
+ * runs later, as its own Flight task, and a deny there reaches Flight's global
+ * `onError` — where it is indistinguishable from a main-route deny. Production
+ * Flight hands `onError` nothing but the error object (no task, no key path,
+ * no component stack; it even clears its request storage around the call), so
+ * nothing at that point can recover where the throw came from, and the status
+ * commit in `rsc-payload.ts` would take it for a page-level deny and answer 4xx.
+ *
+ * The only place the origin is known is *before* the component runs. So this
+ * module rewrites the tree a slot component returns: each server-component
+ * element is replaced by an element of `ContainedSlotComponent`, which invokes
+ * the original, catches `DenySignal`, and substitutes the slot fallback in that
+ * component's place. The wrapper rewrites its own output the same way, so
+ * containment follows the tree however deep it renders — one walk per
+ * component result, once each. No Flight error row, no signal, no client
+ * boundary involvement: the deny never leaves the slot, on the payload path
+ * and the document path alike.
+ *
+ * What is NOT contained, deliberately: anything other than `DenySignal`.
+ * `RedirectSignal` must still reach the pipeline (TIM-554), and a plain error
+ * still takes the slot's catch-all boundary. A thrown thenable — `use()` on a
+ * pending promise — passes through untouched so Flight can suspend the task.
+ *
+ * Flight's `renderElement` does not only invoke plain functions: it unwraps
+ * `memo` (renders `.type`), `forwardRef` (calls `.render`), and `lazy`
+ * (runs `_init`, then renders what it resolved to). A server component behind
+ * any of those is invoked all the same, so its deny would escape too. The walk
+ * therefore resolves an element type the way Flight would — down to the
+ * function Flight would call — and wraps that.
+ *
+ * See design/02-rendering-pipeline.md §"Slot Access Failure = Graceful
+ * Degradation", TIM-1450.
+ */
+import { type ReactNode } from 'react';
+/**
+ * Contain every server component in the tree a slot component returned.
+ *
+ * `fallback` is the slot's deny fallback (`default.tsx`, or nothing) and
+ * replaces exactly the component that denied — siblings that already rendered
+ * stay, the same way a deny scoped by a Suspense boundary behaves on the main
+ * route.
+ *
+ * `opaque` is an element the caller built and has already contained, which
+ * the walk must leave alone: a slot layout passes the `children` element it
+ * received, so the page beneath it is not wrapped a second time.
+ */
+export declare function containSlotSubtree(tree: ReactNode, fallback: ReactNode, opaque?: ReactNode): ReactNode;
+//# sourceMappingURL=slot-subtree-contain.d.ts.map

package/dist/server/slot-subtree-contain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-subtree-contain.d.ts","sourceRoot":"","sources":["../../src/server/slot-subtree-contain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAsD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAsN3F;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,SAAS,EACnB,MAAM,CAAC,EAAE,SAAS,GACjB,SAAS,CAEX"}

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

@@ -0,0 +1,198 @@
+/**
+ * RSC ↔ SSR Bridge Contract
+ *
+ * This file defines what crosses the RSC ↔ SSR environment boundary: the
+ * `NavContext` input and the `SsrRenderResult` output. 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.
+ *
+ * The ALS stores are the exception to "separate instances": `als-registry.ts`
+ * anchors them on `globalThis`, and SSR runs inside the RSC request's
+ * async context, so an SSR module that imported `request-context.ts` would
+ * read live RSC state. The framework's SSR code must not — that is the
+ * coupling this contract removes — and `tests/ssr-import-boundary.test.ts`
+ * holds the SSR entry's import graph to it (its allowlist names the one
+ * registry reader permitted). User `'use client'` code rendered in SSR can
+ * still reach request state through public APIs (`redirect()`, a
+ * `defineCookie()` cookie's `get()`); that test does not cover them.
+ *
+ * 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. The one
+ *    sanctioned exception is `NavContext.getHeadSegmentScript`.
+ *
+ * 1a. **Directional.** `NavContext` is input. Anything SSR produces for
+ *    RSC is returned in `SsrRenderResult`, not written back onto the
+ *    context. SSR never writes to a `NavContext` or through one. That
+ *    includes `responseHeaders`: it is the pipeline's bag, passed by
+ *    reference, and SSR copies it before adding response-local headers.
+ *    RSC-side code may still write the bag after `handleSsr()` returns
+ *    (a promoted redirect's `Location`, for one); that is the pipeline
+ *    using its own bag, not a return channel.
+ *
+ * 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".
+ */
+/**
+ * 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;
+    /** 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.
+     *
+     * This is the bridge's one sanctioned exception to rule 1 (no closures).
+     * SSR must not import the RSC request state that holds the
+     * denied-segment index (tests/ssr-import-boundary.test.ts), and evaluating
+     * it eagerly, before AccessGates settle, would serialize a
+     * non-authoritative index. See
+     * design/49-explicit-subsystem-boundaries.md §"Decision: the head-segment
+     * callback stays". Do not add a second one.
+     */
+    getHeadSegmentScript?: () => string;
+    /**
+     * 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;
+}
+/**
+ * SSR sub-phase timings, recorded by `handleSsr()` and turned into
+ * `Server-Timing` entries by the RSC renderer when
+ * `serverTiming: 'detailed'` is configured.
+ */
+export interface SsrTimings {
+    /** Time to decode the RSC stream (createFromReadableStream/createFromNodeStream) */
+    decodeMs: number;
+    /** Time for Fizz to render the shell (onShellReady, plus any hold window) */
+    shellMs: number;
+    /** Time to set up the 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;
+}
+/**
+ * What `handleSsr()` returns to the RSC environment.
+ *
+ * Directional and terminal: every field is produced by the SSR entry and
+ * settled by the time `handleSsr()` resolves. Do not add request inputs
+ * (those belong on `NavContext`) or methods here.
+ *
+ * `response.status` is not an SSR decision. It echoes
+ * `NavContext.statusCode`, and response status has exactly two owners,
+ * both in the RSC environment:
+ *
+ * 1. the `statusCode` on the `NavContext` itself, seeded by whichever
+ *    RSC-side renderer builds it before `callSsr()`: 200 from
+ *    `rsc-entry/ssr-renderer.ts`, the deny status from `renderDenyPage()`,
+ *    the error status from `rsc-entry/error-renderer.ts`; and
+ * 2. the post-`callSsr()` `getDenyStatus()` override in
+ *    `rsc-entry/ssr-renderer.ts`, which rebuilds the `Response` with the
+ *    status an in-tree `AccessGate`/`PageDenyBoundary` denial recorded
+ *    in the RSC-side ALS (TIM-666).
+ *
+ * The override reads RSC state after SSR returns; it is not a write back
+ * across the bridge. No SSR-side code (error boundaries included) sets a
+ * status: Fizz never renders a class boundary's fallback on the document
+ * path (design/spike-TIM-1441-eliminate-second-pass.md F1/F2), so there
+ * is nothing in-tree to report. See design/49 §"A2".
+ */
+export interface SsrRenderResult {
+    /** The HTML document response, streaming the post-shell remainder. */
+    response: Response;
+    timings: SsrTimings;
+    /**
+     * Whether Fizz's `stream.allReady` settled before the
+     * `deferSuspenseFor` hold ended.
+     *
+     * When true, the RSC renderer skips its signal-promotion microtask
+     * retry: Fizz allReady implies Flight closed its stream, which implies
+     * `onError` already fired for every rejected Flight task, so every
+     * DenySignal/RedirectSignal in the tree is already captured.
+     *
+     * When false (hold timed out, no hold window, shell-only return), there
+     * is no such guarantee and the renderer falls back to the bounded retry.
+     * Settled before `handleSsr()` resolves: `onFizzAllReadyResolved` fires
+     * synchronously just before the render-stream promise resolves.
+     *
+     * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,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;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAAoB,CAAC,EAAE,MAAM,MAAM,CAAC;IAEpC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,UAAU,CAAC;IACpB;;;;;;;;;;;;;;;;OAgBG;IACH,oBAAoB,EAAE,OAAO,CAAC;CAC/B"}

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, SsrRenderResult } from './ssr-bridge-types.ts';
 /**
  * Handle SSR: decode an RSC stream and render it to hydration-ready HTML.
  *
@@ -63,18 +21,21 @@ export interface NavContext {
  * 2. Render the decoded tree to HTML via renderToReadableStream (streaming)
  * 3. Wait for onShellReady before flushing (handled by renderSsrStream)
  * 4. Inject metadata into <head> and client scripts before </body>
- * 5. Return Response with navContext.statusCode and navContext.responseHeaders
+ * 5. Return the Response (navContext.statusCode, navContext.responseHeaders)
+ *    with the SSR sub-phase timings and whether Fizz allReady settled
+ *    within the hold window
  *
  * The RSC stream is piped progressively — not buffered. For deny() outside
  * Suspense, the RSC stream encodes an error in the shell region, causing
  * renderToReadableStream to reject. The error propagates back to the RSC
- * entry which renders the deny page. For deny() inside Suspense, the shell
+ * entry, which rethrows the captured DenySignal for the pipeline to render
+ * the deny page. For deny() inside Suspense, the shell
  * succeeds and the error streams as a React error boundary after flush.
  *
  * @param rscStream - The ReadableStream from the RSC environment
  * @param navContext - Per-request state passed across RSC→SSR boundary
- * @returns A Response containing the HTML stream with hydration markers
+ * @returns The HTML Response with hydration markers, plus SSR diagnostics
  */
-export declare function handleSsr(rscStream: ReadableStream<Uint8Array>, navContext: NavContext): Promise<Response>;
+export declare function handleSsr(rscStream: ReadableStream<Uint8Array>, navContext: NavContext): Promise<SsrRenderResult>;
 export default handleSsr;
 //# sourceMappingURL=ssr-entry.d.ts.map

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,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAiDzE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,eAAe,CAAC,CA2L1B;eAEc,SAAS"}

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

@@ -5,63 +5,96 @@
  * 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"
  */
 import type { ReactNode } from 'react';
+/** Options shared by both SSR render paths (Node streams and Web Streams). */
+export interface SsrStreamOptions {
+    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
+     * allReady had already settled by that moment. The SSR entry returns it
+     * as `SsrRenderResult.fizzAllReadyResolved` so the RSC renderer can
+     * decide whether signal promotion can be short-circuited.
+     */
+    onFizzAllReadyResolved?: (resolved: boolean) => void;
+}
 /**
  * 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;
-    deferSuspenseFor?: number;
-    signal?: AbortSignal;
-}): Promise<ReadableStream<Uint8Array>>;
+export declare function renderSsrStream(element: ReactNode, options?: SsrStreamOptions): 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?: SsrStreamOptions): 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. The
+ * default goes on a response-local copy: `responseHeaders` is the
+ * pipeline's shared bag, handed over on `NavContext`, and SSR only reads
+ * it (design/49 §"A2").
  */
 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;AAkGvC,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,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;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,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,gBAAgB,GACzB,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;AAqGD;;;;;;;;;;;;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;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,QAAQ,CAOV"}

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()`.
+ *
+ * **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"}