@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/server/ssr-bridge-types.ts

@@ -0,0 +1,145 @@
+/**
+ * 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.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
+
+/**
+ * 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 segment params. Post-coercion, values may be non-string (TIM-1347). */
+  segmentParams: CoercedParams;
+  /** Search params from the URL */
+  searchParams: Record<string, string>;
+  /**
+   * 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;
+  /** 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;
+}

package/src/server/ssr-entry.ts

@@ -14,17 +14,69 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
-import { createFromReadableStream } from '#/rsc-runtime/ssr.js';
+// TIM-949: Populate the codec registry so server-rendered <Link> components
+// use codec.serialize() instead of String() fallback for URL interpolation.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import schemaCodecs from 'virtual:timber-schema';
+import { setLinkCodecs } from '../params/codec-registry.js';
+setLinkCodecs(schemaCodecs);
+import {
+  createFromReadableStream,
+  createFromNodeStream,
+  hasNodeStreamDecode,
+} from '../rsc-runtime/ssr.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-import { renderSsrStream, buildSsrResponse } from './ssr-render.js';
-import { formatSsrError } from './error-formatter.js';
+import {
+  renderSsrStream,
+  renderSsrNodeStream,
+  nodeReadableToWeb,
+  useNodeStreams,
+  buildSsrResponse,
+} from './ssr-render.js';
+import { logRenderError } from './logger.js';
 import { SsrStreamError } from './primitives.js';
-import { injectHead, injectRscPayload } from './html-injectors.js';
-import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
+import { createBufferedTransformStream, injectHead, injectRscPayload } from './html-injectors.js';
+import { wrapSsrElement } from './ssr-wrappers.js';
 import { withSpan } from './tracing.js';
-import { setCurrentParams } from '#/client/use-params.js';
-import { registerSsrDataProvider, type SsrData } from '#/client/ssr-data.js';
+import { setCurrentParams } from '../client/use-segment-params.js';
+import { registerSsrDataProvider, type SsrData } from '../client/ssr-data.js';
+import { readPayloadTree } from '../shared/payload-root.js';
+import type { NavContext } from './ssr-bridge-types.js';
+
+// Pre-import Node.js stream modules at module load time — not per-request.
+// Dynamic imports of node-stream-transforms and node:stream/promises were
+// costing 3-17ms per request due to module resolution overhead.
+let _nodeStreamImports: {
+  createNodeBufferedTransform: typeof import('./node-stream-transforms.js').createNodeBufferedTransform;
+  createNodeHeadInjector: typeof import('./node-stream-transforms.js').createNodeHeadInjector;
+  createNodeMoveSuffixTransform: typeof import('./node-stream-transforms.js').createNodeMoveSuffixTransform;
+  createNodeFlightInjector: typeof import('./node-stream-transforms.js').createNodeFlightInjector;
+  runNodePipelineWithErrorHandling: typeof import('./node-stream-transforms.js').runNodePipelineWithErrorHandling;
+  ReadableFromWeb: (
+    webStream: import('stream/web').ReadableStream
+  ) => import('node:stream').Readable;
+} | null = null;
+
+if (useNodeStreams) {
+  try {
+    const [transforms, stream] = await Promise.all([
+      import('./node-stream-transforms.js'),
+      import('node:stream'),
+    ]);
+    _nodeStreamImports = {
+      createNodeBufferedTransform: transforms.createNodeBufferedTransform,
+      createNodeHeadInjector: transforms.createNodeHeadInjector,
+      createNodeMoveSuffixTransform: transforms.createNodeMoveSuffixTransform,
+      createNodeFlightInjector: transforms.createNodeFlightInjector,
+      runNodePipelineWithErrorHandling: transforms.runNodePipelineWithErrorHandling,
+      ReadableFromWeb: (webStream: import('stream/web').ReadableStream) =>
+        stream.Readable.fromWeb(webStream) as import('node:stream').Readable,
+    };
+  } catch {
+    // Fall back to Web Streams path
+  }
+}
 
 // ─── SSR Data ALS ─────────────────────────────────────────────────────────
 //
@@ -39,50 +91,6 @@ const ssrDataAls = new AsyncLocalStorage<SsrData>();
 // Register the ALS-backed provider so getSsrData() reads from ALS.
 registerSsrDataProvider(() => ssrDataAls.getStore());
 
-/**
- * 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;
-}
-
 /**
  * Handle SSR: decode an RSC stream and render it to hydration-ready HTML.
  *
@@ -117,7 +125,8 @@ export async function handleSsr(
       pathname: navContext.pathname,
       searchParams: navContext.searchParams,
       cookies: navContext.cookies ?? new Map(),
-      params: navContext.params,
+      params: navContext.segmentParams,
+      slotParams: navContext.slotParams,
       _navContext: navContext,
     };
 
@@ -127,57 +136,186 @@ export async function handleSsr(
     // Client hooks read from getSsrData() which delegates to this
     // ALS store via the registered provider.
     return ssrDataAls.run(ssrData, async () => {
-      // Also set the module-level currentParams for useParams().
+      // Also set the module-level currentParams for useSegmentParams().
       // useParams reads from getSsrData() during SSR (ALS-backed),
       // but setCurrentParams is kept for the client-side path where
       // the segment router updates params on navigation.
-      setCurrentParams(navContext.params);
+      setCurrentParams(navContext.segmentParams);
 
       // Decode the RSC stream into a React element tree.
       // createFromReadableStream resolves client component references
       // (from "use client" modules) using the SSR environment's module
       // map, importing the actual components for server-side rendering.
-      const element = createFromReadableStream(rscStream) as React.ReactNode;
+      const _ssrStart = performance.now();
+
+      // Decode the RSC stream into a React element tree.
+      // On Node.js: convert Web ReadableStream → Node Readable → createFromNodeStream
+      //   (eliminates Promise-per-chunk overhead from Web Streams reader)
+      // On Workers: createFromReadableStream (Web Streams are V8-native C++ there)
+      let root: unknown;
+      if (hasNodeStreamDecode && _nodeStreamImports) {
+        const nodeRscStream = _nodeStreamImports.ReadableFromWeb(
+          rscStream as import('stream/web').ReadableStream
+        );
+        root = createFromNodeStream(nodeRscStream);
+      } else {
+        root = createFromReadableStream(rscStream);
+      }
+      // The payload root is `{ tree, params, slotParams }` — params ride
+      // beside the tree rather than in a provider around it (TIM-1297). SSR
+      // renders the tree; the params it needs are already in `ssrData` above,
+      // which is where `useSegmentParams()` reads them from during SSR. The
+      // client renders its own provider over the same records.
+      const element = Promise.resolve(root).then(readPayloadTree) as React.ReactNode;
+      const _decodeEnd = performance.now();
 
-      // Wrap with a server-safe nuqs adapter so that 'use client' components
-      // that call nuqs hooks (useQueryStates, useQueryState) can SSR correctly.
-      // The client-side TimberNuqsAdapter (injected by browser-entry.ts) takes
-      // over after hydration. This provider supplies the request's search params
-      // as a static snapshot so nuqs renders the right initial values on the server.
-      const wrappedElement = withNuqsSsrAdapter(navContext.searchParams, element);
+      // Wrap with the same component tree structure as the client hydration
+      // tree (NavigationRoot → TopLoader →
+      // TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider).
+      // This ensures useId() produces matching IDs on both sides, preventing
+      // hydration mismatches in libraries like Radix UI. See TIM-532.
+      const hasTopLoader = _runtimeConfig.topLoader?.enabled !== false;
+      const wrappedElement = wrapSsrElement(element, navContext.searchParams, hasTopLoader);
 
       // Render to HTML stream (waits for onShellReady).
-      // Pass bootstrapScriptContent so React injects a non-deferred <script>
-      // in the shell HTML. This executes immediately during parsing — even
-      // while Suspense boundaries are still streaming — triggering module
-      // loading via dynamic import() so hydration can start early.
+      //
+      // Two paths based on platform:
+      // - Node.js: renderToPipeableStream → Node Transform pipeline → Readable.toWeb() → Response
+      //   Entire pipeline stays in C++ native streams until the Response boundary.
+      // - Workers: renderToReadableStream → Web TransformStream pipeline → Response
+      //   Web Streams are V8-native C++ built-ins on Workers.
+      if (_nodeStreamImports) {
+        // Node.js fast path: full pipeline in native streams
+        const {
+          createNodeBufferedTransform,
+          createNodeHeadInjector,
+          createNodeMoveSuffixTransform,
+          createNodeFlightInjector,
+          runNodePipelineWithErrorHandling,
+        } = _nodeStreamImports;
+
+        const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
+        const requestInfo = { method: 'GET', path: navContext.pathname };
+
+        let nodeHtmlStream: import('node:stream').Readable;
+        try {
+          nodeHtmlStream = await renderSsrNodeStream(wrappedElement, {
+            bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
+            deferSuspenseFor: navContext.deferSuspenseFor,
+            signal: navContext.signal,
+            renderTimeoutMs,
+            requestInfo,
+            onFizzAllReadyResolved: (resolved) => {
+              navContext._fizzAllReadyResolved = resolved;
+            },
+          });
+        } catch (renderError) {
+          logRenderError({ ...requestInfo, error: renderError });
+          throw new SsrStreamError(
+            'SSR renderToReadableStream failed due to RSC stream error',
+            renderError
+          );
+        }
+        const _renderEnd = performance.now();
+
+        // React 19.3+ emits <!DOCTYPE html> automatically when the root
+        // element is <html>, so no framework-level doctype prepend needed.
+        //
+        // Pipeline: buffer → headInjector → flightInjector → moveSuffix → output
+        //
+        // 1. buffer: coalesces Fizz micro-chunks into coherent fragments (TIM-528)
+        // 2. headInjector: injects metadata before </head>
+        // 3. flightInjector: interleaves RSC scripts between HTML chunks (TIM-529)
+        // 4. moveSuffix: strips </body></html>, re-emits at end (TIM-530)
+        //
+        // Post-shell error handling lives in the pump, not in a pipeline
+        // stage: pipeline() destroys every stage on failure, so only an
+        // output kept outside the pipeline can append the noindex script
+        // and close cleanly (TIM-1019).
+        // Resolve the lazy segment script now that the shell is ready
+        // (AccessGates have settled, ALS deny index is authoritative).
+        const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
+        const bufferedTransform = createNodeBufferedTransform();
+        const headInjector = createNodeHeadInjector(resolvedHeadHtml);
+        const flightInjector = createNodeFlightInjector(navContext.rscStream, {
+          renderTimeoutMs,
+          errorSignal: navContext._errorSignal,
+        });
+        const moveSuffix = createNodeMoveSuffixTransform();
+
+        const output = runNodePipelineWithErrorHandling(
+          nodeHtmlStream,
+          [bufferedTransform, headInjector, flightInjector, moveSuffix],
+          navContext.signal
+        );
+        const _pipelineEnd = performance.now();
+
+        // Record SSR sub-timings for Server-Timing header (detailed mode).
+        navContext._ssrTimings = {
+          decodeMs: Math.round(_decodeEnd - _ssrStart),
+          shellMs: Math.round(_renderEnd - _decodeEnd),
+          pipeMs: 0, // pipe() timing is inside renderSsrNodeStream
+          pipelineMs: Math.round(_pipelineEnd - _renderEnd),
+          totalMs: Math.round(_pipelineEnd - _ssrStart),
+          nodeStreams: true,
+        };
+
+        const webStream = nodeReadableToWeb(output);
+        return buildSsrResponse(webStream, navContext.statusCode, navContext.responseHeaders);
+      }
+
+      // Web Streams path (CF Workers / fallback)
+      const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
+      const requestInfo = { method: 'GET', path: navContext.pathname };
       let htmlStream: ReadableStream<Uint8Array>;
       try {
         htmlStream = await renderSsrStream(wrappedElement, {
           bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
           deferSuspenseFor: navContext.deferSuspenseFor,
           signal: navContext.signal,
+          renderTimeoutMs,
+          requestInfo,
+          onFizzAllReadyResolved: (resolved) => {
+            navContext._fizzAllReadyResolved = resolved;
+          },
         });
       } catch (renderError) {
-        // SSR shell rendering failed — the RSC stream contained an error
-        // that wasn't caught by any error boundary in the decoded tree.
-        // Wrap in SsrStreamError so the RSC entry can handle it without
-        // re-executing server components via renderDenyPage.
-        // See LOCAL-293.
-        console.error(
-          '[timber] SSR shell failed from RSC stream error:',
-          formatSsrError(renderError)
-        );
+        logRenderError({ ...requestInfo, error: renderError });
         throw new SsrStreamError(
           'SSR renderToReadableStream failed due to RSC stream error',
           renderError
         );
       }
 
-      // Inject metadata into <head>, then interleave RSC payload chunks
-      // into the body as they arrive from the tee'd RSC stream.
-      let outputStream = injectHead(htmlStream, navContext.headHtml);
-      outputStream = injectRscPayload(outputStream, navContext.rscStream);
+      const _renderEnd = performance.now();
+
+      // Pipeline: buffer → injectHead → injectRscPayload
+      //
+      // The buffered transform coalesces Fizz micro-chunks into coherent
+      // HTML fragments so downstream transforms never see chunk boundaries
+      // mid-tag. This prevents RSC script injection from breaking HTML
+      // structure (TIM-527).
+      // Resolve the lazy segment script now that the shell is ready
+      // (AccessGates have settled, ALS deny index is authoritative).
+      const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
+      let outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
+      outputStream = injectHead(outputStream, resolvedHeadHtml);
+      outputStream = injectRscPayload(
+        outputStream,
+        navContext.rscStream,
+        renderTimeoutMs,
+        navContext._errorSignal
+      );
+      const _pipelineEnd = performance.now();
+
+      navContext._ssrTimings = {
+        decodeMs: Math.round(_decodeEnd - _ssrStart),
+        shellMs: Math.round(_renderEnd - _decodeEnd),
+        pipeMs: 0,
+        pipelineMs: Math.round(_pipelineEnd - _renderEnd),
+        totalMs: Math.round(_pipelineEnd - _ssrStart),
+        nodeStreams: false,
+      };
 
       // Build and return the Response.
       return buildSsrResponse(outputStream, navContext.statusCode, navContext.responseHeaders);