@timber-js/app 0.2.0-alpha.127 → 0.2.0-alpha.128

package/src/server/ssr-entry.ts

@@ -45,6 +45,7 @@ import { wrapSsrElement } from './ssr-wrappers.js';
 import { withSpan } from './tracing.js';
 import { setCurrentParams } from '../client/use-segment-params.js';
 import { registerSsrDataProvider, type SsrData } from '../client/ssr-data.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
@@ -98,81 +99,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;
-
-  /**
-   * 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;
-}
-
 /**
  * Handle SSR: decode an RSC stream and render it to hydration-ready HTML.
  *
@@ -207,7 +133,7 @@ export async function handleSsr(
       pathname: navContext.pathname,
       searchParams: navContext.searchParams,
       cookies: navContext.cookies ?? new Map(),
-      params: navContext.params,
+      params: navContext.segmentParams,
       _navContext: navContext,
     };
 
@@ -221,7 +147,7 @@ export async function handleSsr(
       // 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
@@ -280,6 +206,9 @@ export async function handleSsr(
             deferSuspenseFor: navContext.deferSuspenseFor,
             signal: navContext.signal,
             renderTimeoutMs,
+            onFizzAllReadyResolved: (resolved) => {
+              navContext._fizzAllReadyResolved = resolved;
+            },
           });
         } catch (renderError) {
           logRenderError({ method: '', path: '', error: renderError });
@@ -346,6 +275,9 @@ export async function handleSsr(
           deferSuspenseFor: navContext.deferSuspenseFor,
           signal: navContext.signal,
           renderTimeoutMs,
+          onFizzAllReadyResolved: (resolved) => {
+            navContext._fizzAllReadyResolved = resolved;
+          },
         });
       } catch (renderError) {
         logRenderError({ method: '', path: '', error: renderError });

package/src/server/ssr-render.ts

@@ -128,6 +128,14 @@ export async function renderSsrStream(
     deferSuspenseFor?: number;
     signal?: AbortSignal;
     renderTimeoutMs?: number;
+    /**
+     * 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);
@@ -158,17 +166,26 @@ export async function renderSsrNodeStream(
     deferSuspenseFor?: number;
     signal?: AbortSignal;
     renderTimeoutMs?: number;
+    /**
+     * 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 deferMs = options?.deferSuspenseFor;
   const timeoutMs = options?.renderTimeoutMs;
+  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;
@@ -181,16 +198,21 @@ export async function renderSsrNodeStream(
       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?.();
       },
 
@@ -271,10 +293,12 @@ async function renderViaReadableStream(
     deferSuspenseFor?: number;
     signal?: AbortSignal;
     renderTimeoutMs?: number;
+    onFizzAllReadyResolved?: (resolved: boolean) => void;
   }
 ): Promise<ReadableStream<Uint8Array>> {
   const signal = options?.signal;
   const timeoutMs = options?.renderTimeoutMs;
+  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.
@@ -329,13 +353,25 @@ async function renderViaReadableStream(
   // deferSuspenseFor hold: delay the first read so React can resolve
   // fast-completing Suspense boundaries before we read the shell HTML.
   // 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);
 
   return wrapStreamWithErrorHandling(stream, signal);
 }