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

package/src/server/ssr-render.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,7 +23,26 @@
 import type { ReactNode } from 'react';
 import { renderToReadableStream } from 'react-dom/server';
 
-import { formatSsrError } from './error-formatter.js';
+import { createRenderTimeout, RenderTimeoutError } from './render-timeout.ts';
+import { logRenderError, logStreamingError } from './logger.ts';
+import { isAbortError, noindexScript } from './render-utils.ts';
+
+/**
+ * React's production error sanitization message. When NODE_ENV=production,
+ * React replaces all error messages with this string in renderToReadableStream
+ * and renderToPipeableStream. The original error was already logged by the
+ * RSC onError handler — logging the sanitized version in SSR is duplicate noise.
+ */
+const REACT_PROD_ERROR_PREFIX = 'An error occurred in the Server Components render';
+
+/**
+ * Returns true if the error is React's sanitized production error.
+ * These are duplicates of errors already logged by the RSC onError handler
+ * with the full original message — logging them again in SSR adds noise.
+ */
+function isReactSanitizedError(error: unknown): boolean {
+  return error instanceof Error && error.message.startsWith(REACT_PROD_ERROR_PREFIX);
+}
 
 /**
  * Inline script that injects <meta name="robots" content="noindex"> into <head>.
@@ -25,96 +55,359 @@ import { formatSsrError } from './error-formatter.js';
  *
  * See design/05-streaming.md §"deny() inside Suspense"
  */
-const NOINDEX_SCRIPT =
-  '<script>document.head.appendChild(Object.assign(document.createElement("meta"),{name:"robots",content:"noindex"}))</script>';
+
+// ─── Platform Detection ──────────────────────────────────────────────────────
+//
+// Detect whether we're running on a platform with native Node.js streams.
+// On Node.js/Bun, `node:stream` is backed by C++ (libuv). On Cloudflare
+// Workers, `node:stream` via nodejs_compat is a JS polyfill — Web Streams
+// are the faster path there (V8-native C++ built-ins).
+//
+// We detect once at module load to avoid per-request overhead.
+// The check: process.versions.node exists AND we can import node:stream.
+// Cloudflare Workers with nodejs_compat may polyfill process.versions but
+// the streams won't be native. The Readable.toWeb check confirms native support.
+
+let _useNodeStreams = false;
+let _PassThrough: typeof import('node:stream').PassThrough | null = null;
+let _ReadableToWeb: ((readable: import('node:stream').Readable) => ReadableStream) | null = null;
+let _renderToPipeableStream: typeof import('react-dom/server').renderToPipeableStream | null = null;
+
+try {
+  // Dynamic imports to avoid bundling node:stream and the Node.js-specific
+  // react-dom/server entry for CF Workers builds.
+  // On Node.js/Bun this resolves to native C++ streams.
+  // On CF Workers this either fails or returns a JS polyfill.
+  const nodeStream = await import('node:stream');
+  if (
+    typeof nodeStream.PassThrough === 'function' &&
+    typeof nodeStream.Readable.toWeb === 'function' &&
+    // Real Node.js — not a polyfill. Polyfills typically don't set
+    // process.release.name to 'node'.
+    typeof process !== 'undefined' &&
+    process.release?.name === 'node'
+  ) {
+    // Dynamically import renderToPipeableStream from the Node.js-specific
+    // entry point. The SSR bundle resolves react-dom/server to the edge/browser
+    // export (which lacks renderToPipeableStream), so we import the .node file
+    // directly. This is safe because we're inside a process.release.name === 'node'
+    // guard — this code only runs on real Node.js.
+    const reactDomServer = await import('react-dom/server.node');
+    if (typeof reactDomServer.renderToPipeableStream === 'function') {
+      _useNodeStreams = true;
+      _PassThrough = nodeStream.PassThrough;
+      _ReadableToWeb = nodeStream.Readable.toWeb as (
+        readable: import('node:stream').Readable
+      ) => ReadableStream;
+      _renderToPipeableStream = reactDomServer.renderToPipeableStream;
+    }
+  }
+} catch {
+  // node:stream or renderToPipeableStream not available — use Web Streams path
+}
 
 /**
  * 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 async function renderSsrStream(
   element: ReactNode,
-  options?: { bootstrapScriptContent?: string; deferSuspenseFor?: number; signal?: AbortSignal }
+  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>> {
+  return renderViaReadableStream(element, options);
+}
+
+/** Whether the current platform uses native Node.js streams for SSR. */
+export const useNodeStreams = _useNodeStreams;
+
+// ─── Node.js Path: renderToPipeableStream ────────────────────────────────────
+//
+// Uses React's Node.js-native API. HTML chunks flow through C++ stream
+// buffers with zero Promise allocations per chunk. Returns a Node.js
+// Readable — the caller (ssr-entry.ts) pipes through Node.js Transform
+// streams for injectHead/injectRscPayload before converting to Web
+// ReadableStream at the Response boundary.
+
+/**
+ * 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 async 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> {
   const signal = options?.signal;
-  const stream = await renderToReadableStream(element, {
-    bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
-    signal,
-    onError(error: unknown) {
-      // Suppress logging for connection aborts — the user refreshed or
-      // navigated away, not an application error.
-      if (isAbortError(error) || signal?.aborted) return;
-      console.error('[timber] SSR render error:', formatSsrError(error));
-    },
+  const deferMs = options?.deferSuspenseFor;
+  const timeoutMs = options?.renderTimeoutMs;
+  const requestInfo = options?.requestInfo;
+  const onFizzAllReadyResolved = options?.onFizzAllReadyResolved;
+
+  return new Promise<import('node:stream').Readable>((resolve, reject) => {
+    const passthrough = new _PassThrough!();
+
+    let allReadyResolve: (() => void) | null = null;
+    let allReadyReject: ((reason?: unknown) => void) | null = null;
+    let allReadyFired = false;
+    const allReady = new Promise<void>((resolve, reject) => {
+      allReadyResolve = resolve;
+      allReadyReject = reject;
+    });
+    allReady.catch(() => {});
+
+    const { pipe, abort } = _renderToPipeableStream!(element, {
+      bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
+      nonce: options?.nonce,
+
+      onShellReady() {
+        if (deferMs && deferMs > 0) {
+          Promise.race([allReady, new Promise<void>((r) => setTimeout(r, deferMs))]).then(() => {
+            onFizzAllReadyResolved?.(allReadyFired);
+            pipe(passthrough);
+            resolve(passthrough);
+          });
+        } else {
+          // No hold — allReady has almost certainly not fired yet.
+          // Report false so the RSC entry runs the microtask retry loop.
+          onFizzAllReadyResolved?.(allReadyFired);
+          pipe(passthrough);
+          resolve(passthrough);
+        }
+      },
+
+      onAllReady() {
+        allReadyFired = true;
+        allReadyResolve?.();
+      },
+
+      onShellError(error: unknown) {
+        // Reject allReady so the render timeout is cancelled.
+        // Without this, a pre-shell failure leaves the timer
+        // running for the full timeout window.
+        allReadyReject?.(error);
+        reject(error);
+      },
+
+      onError(error: unknown) {
+        if (isAbortError(error) || signal?.aborted) return;
+        // Skip React's sanitized production errors — the original was
+        // already logged by the RSC onError with full details.
+        if (isReactSanitizedError(error)) return;
+        logRenderError({
+          method: requestInfo?.method ?? '',
+          path: requestInfo?.path ?? '',
+          error,
+        });
+      },
+    });
+
+    // Wire abort to both request signal AND render timeout.
+    // If the client stays connected but a downstream fetch hangs,
+    // the timeout ensures abort() is eventually called.
+    if (signal) {
+      if (signal.aborted) {
+        abort();
+      } else {
+        signal.addEventListener('abort', () => abort(), { once: true });
+      }
+    }
+
+    if (timeoutMs && timeoutMs > 0) {
+      const renderTimeout = createRenderTimeout(timeoutMs, signal);
+      renderTimeout.signal.addEventListener(
+        'abort',
+        () => {
+          logRenderError({
+            method: requestInfo?.method ?? '',
+            path: requestInfo?.path ?? '',
+            error: new Error(
+              `SSR render timed out after ${timeoutMs}ms — aborting. ` +
+                'A Suspense component or downstream fetch may be hanging.'
+            ),
+          });
+          abort(renderTimeout.signal.reason);
+        },
+        { once: true }
+      );
+      // Cancel the timeout when the render completes OR on pre-shell
+      // failure. Without the catch branch, onShellError → reject()
+      // would leave the timer running for the full timeout window.
+      allReady.then(
+        () => renderTimeout.cancel(),
+        () => renderTimeout.cancel()
+      );
+    }
   });
+}
+
+/** Convert a Node.js Readable to a Web ReadableStream (zero-copy bridge). */
+export function nodeReadableToWeb(
+  readable: import('node:stream').Readable
+): ReadableStream<Uint8Array> {
+  return _ReadableToWeb!(readable) as ReadableStream<Uint8Array>;
+}
+
+// ─── Web Streams Path: renderToReadableStream ────────────────────────────────
+//
+// Uses React's Web Streams API. On Cloudflare Workers, ReadableStream is a
+// V8-native C++ built-in, making this the fastest path for that platform.
+// On Node.js, Web Streams are a JS reimplementation — slower, but this path
+// is only used as a fallback when Node.js native streams aren't available.
+
+async function renderViaReadableStream(
+  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;
+    requestInfo?: { method: string; path: string };
+    onFizzAllReadyResolved?: (resolved: boolean) => void;
+  }
+): Promise<ReadableStream<Uint8Array>> {
+  const signal = options?.signal;
+  const timeoutMs = options?.renderTimeoutMs;
+  const requestInfo = options?.requestInfo;
+  const onFizzAllReadyResolved = options?.onFizzAllReadyResolved;
+
+  // If a render timeout is configured, create a combined signal that
+  // fires on either request abort OR timeout — whichever comes first.
+  let renderTimeout: import('./render-timeout.ts').RenderTimeout | null = null;
+  let effectiveSignal = signal;
+  if (timeoutMs && timeoutMs > 0) {
+    renderTimeout = createRenderTimeout(timeoutMs, signal);
+    effectiveSignal = renderTimeout.signal;
+  }
+
+  let stream: Awaited<ReturnType<typeof renderToReadableStream>>;
+  try {
+    stream = await renderToReadableStream(element, {
+      bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
+      nonce: options?.nonce,
+      signal: effectiveSignal,
+      onError(error: unknown) {
+        if (isAbortError(error) || effectiveSignal?.aborted) return;
+        if (error instanceof RenderTimeoutError) {
+          logRenderError({
+            method: requestInfo?.method ?? '',
+            path: requestInfo?.path ?? '',
+            error: new Error(
+              `SSR render timed out after ${timeoutMs}ms — aborting. ` +
+                'A Suspense component or downstream fetch may be hanging.'
+            ),
+          });
+          return;
+        }
+        // Skip React's sanitized production errors — the original was
+        // already logged by the RSC onError with full details.
+        if (isReactSanitizedError(error)) return;
+        logRenderError({
+          method: requestInfo?.method ?? '',
+          path: requestInfo?.path ?? '',
+          error,
+        });
+      },
+    });
+  } catch (error) {
+    // Pre-shell failure (e.g. RSC stream error). Cancel the render
+    // timeout so it doesn't leak a timer + abort callback for the
+    // full timeout window. Under repeated pre-shell failures this
+    // would accumulate unnecessary timers.
+    renderTimeout?.cancel();
+    throw error;
+  }
 
   // Prevent unhandled promise rejection from streaming-phase errors.
-  // React DOM Server exposes `allReady` — a promise that resolves when
-  // ALL content (including Suspense boundaries) has been rendered. If a
-  // streaming-phase error occurs (e.g. React boundary flush failure),
-  // `allReady` rejects independently of the stream. Without this catch,
-  // the rejection becomes an unhandled promise rejection that crashes
-  // the Node.js process.
   stream.allReady.catch(() => {});
 
+  // Cancel the render timeout once allReady resolves (render completed).
+  if (renderTimeout) {
+    stream.allReady.then(() => renderTimeout!.cancel()).catch(() => renderTimeout!.cancel());
+  }
+
   // deferSuspenseFor hold: delay the first read so React can resolve
   // fast-completing Suspense boundaries before we read the shell HTML.
-  // renderToReadableStream generates HTML lazily on pull — if we wait
-  // before reading, React resolves pending boundaries and inlines their
-  // content instead of serializing fallbacks. Race allReady against
-  // deferSuspenseFor so we don't wait longer than necessary.
   // See design/05-streaming.md §"deferSuspenseFor"
+  //
+  // While we're holding, also track whether `stream.allReady` settled
+  // before the timer. That boolean is the Option-1 signal-promotion
+  // short-circuit key — see NavContext._fizzAllReadyResolved and
+  // design/spike-signal-promotion-protocol.md.
+  let fizzAllReadyResolved = false;
+  const allReadyTap = stream.allReady.then(
+    () => {
+      fizzAllReadyResolved = true;
+    },
+    () => {
+      // allReady rejections are already swallowed above; keep false.
+    }
+  );
   const deferMs = options?.deferSuspenseFor;
   if (deferMs && deferMs > 0) {
-    await Promise.race([
-      stream.allReady,
-      new Promise<void>((resolve) => setTimeout(resolve, deferMs)),
-    ]);
+    await Promise.race([allReadyTap, new Promise<void>((resolve) => setTimeout(resolve, deferMs))]);
   }
+  onFizzAllReadyResolved?.(fizzAllReadyResolved);
 
-  // renderToReadableStream resolves after onShellReady by default.
-  // The stream is ready to read — the shell (everything outside
-  // Suspense boundaries) is available. Suspense content streams
-  // into the open connection as it resolves.
-  //
-  // Wrap the stream in an error-resilient transform. With progressive
-  // streaming, errors inside Suspense boundaries (e.g. deny() or throws
-  // in async components) cause React's stream to error during the flush
-  // phase. The onError callback logs the error, but the stream error
-  // would become an unhandled promise rejection and crash the process.
-  // The transform catches these post-shell streaming errors and closes
-  // the stream cleanly — the shell (with correct status code) has
-  // already been sent.
-  return wrapStreamWithErrorHandling(stream, signal);
+  return wrapStreamWithErrorHandling(stream, signal, options?.nonce);
 }
 
+// ─── Shared Utilities ────────────────────────────────────────────────────────
+
 /**
  * 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
@@ -123,7 +416,8 @@ export async function renderSsrStream(
 /** @internal Exported for testing only. */
 export function wrapStreamWithErrorHandling(
   stream: ReadableStream<Uint8Array>,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  nonce?: string
 ): ReadableStream<Uint8Array> {
   const reader = stream.getReader();
   const encoder = new TextEncoder();
@@ -138,19 +432,12 @@ export function wrapStreamWithErrorHandling(
         }
         controller.enqueue(value);
       } catch (error) {
-        // Connection abort (user refreshed or navigated away) — close
-        // silently without logging. This is not an application error.
         if (isAbortError(error) || signal?.aborted) {
           controller.close();
           return;
         }
-        // Streaming-phase error (e.g. React boundary flush failure,
-        // deny() or throw inside Suspense after flush).
-        // The shell has already been sent with status 200. Inject a
-        // noindex meta tag so search engines don't index this error page,
-        // then close cleanly. See design/05-streaming.md.
-        console.error('[timber] SSR streaming error (post-shell):', formatSsrError(error));
-        controller.enqueue(encoder.encode(NOINDEX_SCRIPT));
+        logStreamingError({ error });
+        controller.enqueue(encoder.encode(noindexScript(nonce)));
         controller.close();
       }
     },
@@ -160,29 +447,14 @@ export function wrapStreamWithErrorHandling(
   });
 }
 
-/**
- * Check if an error is an abort error (connection closed by client).
- *
- * When the browser aborts a request (page refresh, navigation away),
- * the AbortSignal fires and React/streams throw an AbortError. This
- * is not an application error — suppress it from error boundaries and logs.
- */
-function isAbortError(error: unknown): boolean {
-  if (error instanceof DOMException && error.name === 'AbortError') return true;
-  if (error instanceof Error && error.name === 'AbortError') return true;
-  return false;
-}
-
 /**
  * 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 function buildSsrResponse(
   htmlStream: ReadableStream<Uint8Array>,

package/src/server/ssr-wrappers.tsx

@@ -0,0 +1,162 @@
+/**
+ * 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 { createElement, Fragment, type ReactNode } from 'react';
+import { withNuqsSsrAdapter } from './nuqs-ssr-provider.tsx';
+import { NavigationProvider } from '../client/navigation-context.ts';
+import { PayloadRoot } from '../client/params-context.ts';
+
+/**
+ * SSR equivalent of NavigationRoot.
+ *
+ * On the client, the router renders NavigationRoot via `root.render` in a transition,
+ * rendering `Fragment(TopLoader, element)` — or the element alone when the top
+ * loader is disabled.
+ *
+ * The Fragment is the part that matters: it forks, so it advances React's tree
+ * context. Both sides must agree on whether it is there, which is why
+ * `hasTopLoader` is threaded in from the same config the client reads.
+ */
+function SsrNavigationRoot({
+  children,
+  hasTopLoader,
+}: {
+  children?: ReactNode;
+  hasTopLoader: boolean;
+}): ReactNode {
+  if (hasTopLoader) {
+    return createElement(Fragment, null, createElement(SsrTopLoader, null), children);
+  }
+  return children as ReactNode;
+}
+
+/**
+ * SSR equivalent of TopLoader.
+ * Exists as a fiber node to match the client tree depth; renders nothing.
+ */
+function SsrTopLoader(): ReactNode {
+  return null;
+}
+
+/**
+ * SSR equivalent of TimberNuqsAdapter component boundary.
+ * The actual NuqsAdapterProvider (from createAdapterProvider) is added
+ * inside this wrapper via withNuqsSsrAdapter, matching the client's
+ * TimberNuqsAdapter → NuqsAdapterProvider nesting.
+ */
+function SsrNuqsWrapper({ search, children }: { search: string; children?: ReactNode }): ReactNode {
+  // withNuqsSsrAdapter creates a NuqsAdapterProvider (from createAdapterProvider),
+  // which is the same component factory used by TimberNuqsAdapter on the client.
+  // Both produce the same internal component boundary depth.
+  return withNuqsSsrAdapter(search, children);
+}
+
+/** 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 function wrapSsrElement(element: ReactNode, opts: SsrWrapOptions): ReactNode {
+  // Build inside-out to match the client's createElement chain in
+  // hydrate.ts / router-init.ts renderTree().
+
+  // 1. Innermost: PayloadRoot publishes the payload's params over the tree.
+  const withParams = createElement(PayloadRoot, { source: opts.paramsSource }, element);
+
+  // 2. NavigationProvider with the request's address-bar state.
+  const withNav = createElement(
+    NavigationProvider,
+    { value: { pathname: opts.pathname, search: opts.search } },
+    withParams
+  );
+
+  // 3. TimberNuqsAdapter equivalent (wraps withNuqsSsrAdapter for the actual nuqs provider)
+  const withNuqs = createElement(SsrNuqsWrapper, { search: opts.search }, withNav);
+
+  // 4. Outermost: NavigationRoot equivalent (the TopLoader fork)
+  return createElement(SsrNavigationRoot, { hasTopLoader: opts.hasTopLoader }, withNuqs);
+}