@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7c7e4327

package/src/ssr/index.tsx

@@ -1,18 +1,6 @@
 import React from "react";
-import { renderSegments } from "../segment-system.js";
-import { filterSegmentOrder } from "../browser/react/filter-segment-order.js";
-import { ThemeProvider } from "../theme/ThemeProvider.js";
-import { NonceContext } from "../browser/react/nonce-context.js";
-import { NavigationStoreContext } from "../browser/react/context.js";
-import type { NavigationStoreContextValue } from "../browser/react/context.js";
-import type { HandleData } from "../browser/types.js";
+import { createSsrRootComponent } from "./ssr-root.js";
 import type { ErrorPhase } from "../types.js";
-import type { ResolvedSegment } from "../types.js";
-import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
-import type {
-  EventController,
-  DerivedNavigationState,
-} from "../browser/event-controller.js";
 
 /**
  * Options for injectRSCPayload
@@ -40,6 +28,51 @@ interface ReactDOMReadableStream extends ReadableStream<Uint8Array> {
   allReady: Promise<void>;
 }
 
+/**
+ * Options for prerender from react-dom/static.edge
+ */
+interface PrerenderOptions {
+  signal?: AbortSignal;
+  bootstrapScriptContent?: string;
+  onError?: (error: unknown) => void;
+}
+
+/**
+ * Result of prerender from react-dom/static.edge. `postponed` is React's
+ * opaque resume state — non-null when the render was aborted with pending
+ * holes, null when the shell completed with nothing left to stream.
+ */
+interface PrerenderResult {
+  prelude: ReadableStream<Uint8Array>;
+  postponed: unknown;
+}
+
+/**
+ * prerender from react-dom/static.edge
+ */
+type PrerenderFn = (
+  element: React.ReactNode,
+  options?: PrerenderOptions,
+) => Promise<PrerenderResult>;
+
+/**
+ * Options for resume from react-dom/server.edge
+ */
+interface ResumeOptions {
+  onError?: (error: unknown) => void;
+  nonce?: string;
+}
+
+/**
+ * resume from react-dom/server.edge — continues a prerendered render, emitting
+ * only the postponed holes.
+ */
+type ResumeFn = (
+  element: React.ReactNode,
+  postponedState: unknown,
+  options?: ResumeOptions,
+) => Promise<ReactDOMReadableStream>;
+
 /**
  * Options for the renderHTML function
  */
@@ -71,7 +104,7 @@ export interface SSRRenderOptions {
  */
 export interface SSRDependencies<TEnv = unknown> {
   /**
-   * createFromReadableStream from @vitejs/plugin-rsc/ssr
+   * createFromReadableStream from @rangojs/router/internal/deps/ssr
    */
   createFromReadableStream: <T>(
     stream: ReadableStream<Uint8Array>,
@@ -86,7 +119,7 @@ export interface SSRDependencies<TEnv = unknown> {
   ) => Promise<ReactDOMReadableStream>;
 
   /**
-   * injectRSCPayload from rsc-html-stream/server
+   * injectRSCPayload from @rangojs/router/internal/deps/html-stream-server
    */
   injectRSCPayload: (
     rscStream: ReadableStream<Uint8Array>,
@@ -99,6 +132,18 @@ export interface SSRDependencies<TEnv = unknown> {
    */
   loadBootstrapScriptContent: () => Promise<string>;
 
+  /**
+   * prerender from react-dom/static.edge. Optional; required only by
+   * {@link createShellCaptureHandler} for PPR shell capture.
+   */
+  prerender?: PrerenderFn;
+
+  /**
+   * resume from react-dom/server.edge. Optional; required only by
+   * {@link createShellResumeHandler} for resuming a postponed shell.
+   */
+  resume?: ResumeFn;
+
   /**
    * Optional callback invoked when an error occurs during SSR rendering.
    *
@@ -119,94 +164,165 @@ export interface SSRDependencies<TEnv = unknown> {
 }
 
 /**
- * RSC payload type (minimal interface for SSR)
+ * Default guard for how long capture waits on the caller's `quiesce` signal
+ * before forcing the abort that freezes the shell. This is the ONLY wall-clock
+ * on the capture path and it is a pathological guard — it should never fire once
+ * the caller's `quiesce` is a task-quantized, frozen-byte signal (the capture
+ * gate in shell-capture.ts). See docs/design/ppr-shell-resume.md.
  */
-interface RscPayload {
-  metadata?: {
-    segments?: ResolvedSegment[];
-    rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
-    handles?: AsyncGenerator<HandleData, void, unknown>;
-    matched?: string[];
-    pathname?: string;
-    params?: Record<string, string>;
-    basename?: string;
-    themeConfig?: ResolvedThemeConfig | null;
-    initialTheme?: Theme;
-    version?: string;
-  };
-}
+const DEFAULT_SHELL_CAPTURE_MAX_WAIT_MS = 5000;
+
+/**
+ * Fixed number of macrotask hops between `quiesce` resolving and the abort. These
+ * give React's fizz worker turns to flush the settled shell into the prelude and
+ * mark still-pending boundaries as POSTPONED (rather than errored) before
+ * controller.abort() lands. Not a wall-clock wait.
+ *
+ * Why 16 and not the original 2: under the REPLAY-ONLY capture model
+ * (docs/design/ppr-shell-resume.md), the capture Flight render serializes ring-3
+ * cached segments that are ALREADY serialized, so it emits the whole shell payload
+ * in the first tick and the gate declares quiesce almost immediately (~a few ms).
+ * On the old fresh-execution path the Flight dribbled out as handlers ran, so
+ * Flight-quiet effectively meant "the shell has rendered" and 2 hops sufficed. Under
+ * replay, Flight-quiet fires BEFORE the fizz side has consumed the instant payload
+ * and rendered the shell to `<body>`, so the fizz needs a real buffer of turns after
+ * quiesce — otherwise the abort lands on an unrendered tree (empty prelude, root
+ * postpone) and the sanity gate refuses. Still task-based (masked loaders never
+ * emit, so more hops never lets a hole settle); a cold worker whose first
+ * attempt still under-renders heals on the in-place retry. Bounded by maxWaitMs.
+ */
+const POST_QUIESCE_TASK_HOPS = 16;
 
 /**
- * Consume an async generator and return a Promise that resolves with the final value.
- * Used for SSR where we need to await all handle data before rendering.
+ * Route an SSR error through the deps.onError notification callback with the
+ * "rendering" phase. Swallows callback failures so a broken reporter never
+ * masks the original error. Shared by renderHTML, capture, and resume so the
+ * onError contract is identical across all three handlers.
  */
-async function consumeAsyncGenerator(
-  generator: AsyncGenerator<HandleData, void, unknown>,
-): Promise<HandleData> {
-  let lastData: HandleData = {};
-  for await (const data of generator) {
-    lastData = data;
+function reportRenderError(
+  onError: SSRDependencies["onError"],
+  error: unknown,
+): void {
+  if (onError) {
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    try {
+      onError(errorObj, { phase: "rendering" });
+    } catch (callbackError) {
+      console.error("[SSRHandler.onError] Callback error:", callbackError);
+    }
   }
-  return lastData;
 }
 
 /**
- * Create a minimal event controller for SSR.
- * This provides the correct pathname so useNavigation returns the right value during SSR.
+ * Yield one macrotask. Used by capture to let React's fizz worker flush the
+ * shell and mark still-pending boundaries as postponed before the abort.
  */
-function createSsrEventController(opts: {
-  pathname: string;
-  params?: Record<string, string>;
-  handleData?: HandleData;
-  matched?: string[];
-}): EventController {
-  const location = new URL(opts.pathname, "http://localhost");
-  let params = opts.params ?? {};
-  const handleState = {
-    data: opts.handleData ?? {},
-    segmentOrder: filterSegmentOrder(opts.matched ?? []),
-  };
-  const state: DerivedNavigationState = {
-    state: "idle",
-    isStreaming: false,
-    isNavigating: false,
-    location,
-    pendingUrl: null,
-    inflightActions: [],
-  };
+function macrotask(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
 
-  return {
-    getState: () => state,
-    getLocation: () => location,
-    subscribe: () => () => {},
-    getActionState: () => ({
-      state: "idle",
-      actionId: null,
-      payload: null,
-      error: null,
-      result: null,
-    }),
-    subscribeToAction: () => () => {},
-    subscribeToHandles: () => () => {},
-    setHandleData: () => {},
-    getHandleState: () => handleState,
-    setParams: (nextParams) => {
-      params = nextParams;
-    },
-    getParams: () => params,
-    setLocation: () => {},
-    startNavigation: () => {
-      throw new Error("Navigation not supported during SSR");
-    },
-    abortNavigation: () => {},
-    startAction: () => {
-      throw new Error("Actions not supported during SSR");
+/**
+ * A timeout promise paired with a cancel() so the pending timer is cleared once
+ * the race is decided — otherwise the maxWait timer keeps the event loop alive
+ * for the full duration even after `quiesce` won.
+ */
+function createCancelableTimeout(ms: number): {
+  promise: Promise<void>;
+  cancel: () => void;
+} {
+  let id: ReturnType<typeof setTimeout> | undefined;
+  const promise = new Promise<void>((resolve) => {
+    id = setTimeout(resolve, ms);
+  });
+  return { promise, cancel: () => clearTimeout(id) };
+}
+
+/**
+ * Drain a ReadableStream fully into a single Uint8Array. Capture buffers the
+ * whole prelude so it can be stored and later prepended byte-for-byte.
+ */
+async function readStreamToUint8Array(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      total += value.length;
+    }
+  } catch (error) {
+    // Mid-read abort path (documented): the prelude stream errors with our
+    // abort reason while we are still reading it. Cancel the source before
+    // rethrowing so it is not left uncancelled; releaseLock always runs in
+    // finally. Mirrors src/rsc/rsc-rendering.ts's serve-side reader cleanup.
+    reader.cancel(error).catch(() => {});
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+
+/**
+ * A minimal HTML stream for the resume DATA variant: one empty chunk, then
+ * close.
+ *
+ * injectRSCPayload only resolves its internal flight-data promise (and thus
+ * only writes the Flight payload <script> pushes) from inside transform()'s
+ * scheduled callback. A stream that closes without ever emitting a chunk never
+ * runs transform, so its flush() awaits a promise that is never resolved and
+ * the output deadlocks. Emitting a single empty chunk runs transform once,
+ * which is enough for the payload to be written and the trailer appended.
+ */
+function createDataVariantHtmlStream(): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new Uint8Array(0));
+      controller.close();
     },
-    abortAllActions: () => {},
-    getCurrentNavigation: () => null,
-    getInflightActions: () => new Map(),
-    hadAnyConcurrentActions: () => false,
-  };
+  });
+}
+
+/**
+ * Options for the captureShellHTML function returned by
+ * {@link createShellCaptureHandler}.
+ */
+interface ShellCaptureOptions {
+  /** Caller-provided promise that resolves once the cached content settled. */
+  quiesce: Promise<void>;
+  /** Upper bound on how long to wait for `quiesce`. Default 5000ms. */
+  maxWaitMs?: number;
+}
+
+/**
+ * Result of a successful shell capture. `prelude` is the raw prelude bytes;
+ * `postponed` is React's resume state serialized to JSON, or null when the
+ * shell completed with no holes (the DATA variant).
+ */
+interface ShellCaptureResult {
+  prelude: Uint8Array;
+  postponed: string | null;
+}
+
+/**
+ * Options for the resumeShellHTML function returned by
+ * {@link createShellResumeHandler}.
+ */
+interface ShellResumeOptions {
+  /** JSON from capture; null selects the DATA variant (no fizz). */
+  postponed: string | null;
+  /** Nonce for CSP. */
+  nonce?: string;
 }
 
 /**
@@ -214,10 +330,10 @@ function createSsrEventController(opts: {
  *
  * @example
  * ```tsx
- * import { createSSRHandler } from "rsc-router/ssr";
- * import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+ * import { createSSRHandler } from "@rangojs/router/ssr";
+ * import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
  * import { renderToReadableStream } from "react-dom/server.edge";
- * import { injectRSCPayload } from "rsc-html-stream/server";
+ * import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
  *
  * export const renderHTML = createSSRHandler({
  *   createFromReadableStream,
@@ -255,81 +371,11 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // - rscStream2: For browser hydration (inject as __FLIGHT_DATA__)
       const [rscStream1, rscStream2] = rscStream.tee();
 
-      // Deserialize RSC stream to React tree
-      let payload: Promise<RscPayload> | undefined;
-      let handlesPromise: Promise<HandleData> | undefined;
-      let ssrContextValue: NavigationStoreContextValue | undefined;
-      function SsrRoot() {
-        payload ??= createFromReadableStream<RscPayload>(rscStream1);
-        const resolved = React.use(payload);
-
-        const themeConfig = resolved.metadata?.themeConfig ?? null;
-        const pathname = resolved.metadata?.pathname ?? "/";
-
-        // Await handles before creating SSR event controller so hooks can
-        // read request-local handle data via NavigationStoreContext.
-        // The handles property is an async generator that yields on each push
-        // Memoize the promise since async generators can only be iterated once
-        let handleData: HandleData = {};
-        if (resolved.metadata?.handles) {
-          handlesPromise ??= consumeAsyncGenerator(resolved.metadata.handles);
-          handleData = React.use(handlesPromise);
-        }
-
-        // Create SSR context with request-local pathname/params/handles.
-        ssrContextValue ??= {
-          store: null as any,
-          eventController: createSsrEventController({
-            pathname,
-            params: resolved.metadata?.params,
-            handleData,
-            matched: resolved.metadata?.matched,
-          }),
-          navigate: async () => {},
-          refresh: async () => {},
-          version: resolved.metadata?.version,
-          basename: resolved.metadata?.basename,
-        };
-
-        // Build content tree from segments.
-        // Order must match NavigationProvider: NavigationStoreContext > ThemeProvider > content
-        const reconstructedRoot = renderSegments(
-          resolved.metadata?.segments ?? [],
-          {
-            rootLayout: resolved.metadata?.rootLayout,
-          },
-        );
-        let content: React.ReactNode =
-          reconstructedRoot instanceof Promise
-            ? React.use(reconstructedRoot)
-            : reconstructedRoot;
-
-        // Wrap content with ThemeProvider if theme is enabled
-        if (themeConfig) {
-          content = (
-            <ThemeProvider
-              config={themeConfig}
-              initialTheme={resolved.metadata?.initialTheme}
-            >
-              {content}
-            </ThemeProvider>
-          );
-        }
-
-        // Wrap with NonceContext so client components (e.g. MetaTags) can
-        // apply CSP nonces to inline scripts during SSR. Always present to
-        // match the browser-side NavigationProvider tree shape for hydration.
-        content = (
-          <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
-        );
-
-        // Wrap with NavigationStoreContext for useNavigation hook
-        return (
-          <NavigationStoreContext.Provider value={ssrContextValue!}>
-            {content}
-          </NavigationStoreContext.Provider>
-        );
-      }
+      const SsrRoot = createSsrRootComponent({
+        createFromReadableStream,
+        rscStream: rscStream1,
+        nonce,
+      });
 
       // Get bootstrap script content
       const bootstrapScriptContent = await loadBootstrapScriptContent();
@@ -353,16 +399,250 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // Inject RSC payload into HTML as <script nonce="...">__FLIGHT_DATA__</script>
       return htmlStream.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
     } catch (error) {
-      // Invoke onError callback if provided
-      if (onError) {
-        const errorObj =
-          error instanceof Error ? error : new Error(String(error));
-        try {
-          onError(errorObj, { phase: "rendering" });
-        } catch (callbackError) {
-          console.error("[SSRHandler.onError] Callback error:", callbackError);
+      reportRenderError(onError, error);
+      throw error;
+    }
+  };
+}
+
+/**
+ * Create the PPR shell capture handler.
+ *
+ * captureShellHTML prerenders the shell over the (cached, loader-masked) Flight
+ * stream, aborts once the shell settles, and returns the prelude bytes plus the
+ * postponed resume state for storage. The stored pair is later served by
+ * {@link createShellResumeHandler}. See docs/design/ppr-shell-resume.md.
+ *
+ * Throws at creation if `deps.prerender` is missing — capture cannot run
+ * without react-dom/static.edge's prerender.
+ */
+export function createShellCaptureHandler<TEnv = unknown>(
+  deps: SSRDependencies<TEnv>,
+) {
+  const { createFromReadableStream, loadBootstrapScriptContent, prerender } =
+    deps;
+  const onError = deps.onError;
+
+  if (!prerender) {
+    throw new Error(
+      "[createShellCaptureHandler] Missing `prerender` dependency (react-dom/static.edge). " +
+        "PPR shell capture requires the prerender export; wire it in the SSR virtual entry.",
+    );
+  }
+
+  /**
+   * Prerender the shell and return the stored artifacts, or null when the
+   * shell degraded (root postpone / hung handles) and must not be cached.
+   *
+   * @param rscStream - Flight stream to render the shell over. Not teed and not
+   *   piped through injectRSCPayload: the hydration payload is produced fresh
+   *   per request by the resume/serve pass.
+   * @param opts - quiesce signal and maxWait guard.
+   */
+  return async function captureShellHTML(
+    rscStream: ReadableStream<Uint8Array>,
+    opts: ShellCaptureOptions,
+  ): Promise<ShellCaptureResult | null> {
+    const maxWaitMs = opts.maxWaitMs ?? DEFAULT_SHELL_CAPTURE_MAX_WAIT_MS;
+
+    // Arm the maxWaitMs deadline BEFORE the first await so it bounds the ENTIRE
+    // capture, the bootstrap-script load included. loadBootstrapScriptContent()
+    // used to run before the timer, so a hung/slow bootstrap load hung
+    // captureShellHTML with no upper bound and held the background capture task
+    // open. One deadline, shared by the bootstrap race below and the quiesce
+    // race, keeps the whole path "bounded by maxWaitMs like every quiesce input".
+    const deadline = createCancelableTimeout(maxWaitMs);
+    try {
+      // No nonce (nonce'd requests never reach capture); no formState.
+      const SsrRoot = createSsrRootComponent({
+        createFromReadableStream,
+        rscStream,
+      });
+
+      // Bootstrap load raced against the deadline. A load that never resolves
+      // within maxWaitMs is the same bounded no-shell degrade as a shell that
+      // never goes quiet: return null, do not hang. A load that REJECTS is a
+      // genuine error and still propagates (it is not the deadline). `null` is
+      // the deadline sentinel — disjoint from the load's `Promise<string>`, so
+      // the race narrows to `string | null` with no wrapper. The no-op catch
+      // keeps a late rejection off the unhandledRejection path when the deadline
+      // already won; a rejection that lands first still propagates out.
+      const load = loadBootstrapScriptContent();
+      load.catch(() => {});
+      const bootstrapScriptContent = await Promise.race([
+        load,
+        deadline.promise.then(() => null),
+      ]);
+      if (bootstrapScriptContent === null) {
+        return null;
+      }
+
+      // Start prerender first, then run the abort schedule concurrently. When
+      // holes are pending, prerender's promise settles only after abort(); when
+      // the shell completes with no holes it settles on its own and the later
+      // abort() is a harmless no-op (the DATA variant).
+      const controller = new AbortController();
+      // Private reason object: the deliberate abort is identified by object
+      // IDENTITY in both the onError below and the post-await catch. React
+      // propagates this EXACT object to onError for every still-pending boundary
+      // (verified identity-preserving), and rejects/errors the prelude with it.
+      const abortReason = { rangoShellCaptureAbort: true };
+      const prerenderPromise = prerender(<SsrRoot />, {
+        signal: controller.signal,
+        bootstrapScriptContent,
+        // Abort is how capture WORKS: once the shell is quiet we abort() to
+        // freeze the prelude and let the still-pending holes postpone. React
+        // reports the abort reason for each pending boundary through onError.
+        // Without an onError here React falls back to console.error, so every
+        // capture that still has a live hole at abort time (the normal case)
+        // dumps a stack once per pending boundary. That is EXPECTED degradation,
+        // so swallow OUR abort — matched by IDENTITY (error === abortReason).
+        // Discriminate by identity, NOT error.name: capture aborts before
+        // awaiting, so signal.aborted is unconditionally true and a name check
+        // swallowed genuine AbortError-named throws (a component's own
+        // fetch/AbortController cancellation) as if they were our abort. Genuine
+        // render errors are NOT our sentinel and still surface through
+        // deps.onError, the same channel renderHTML uses. See
+        // docs/design/ppr-shell-resume.md.
+        onError: (error: unknown) => {
+          if (error === abortReason) {
+            return;
+          }
+          reportRenderError(onError, error);
+        },
+      });
+      // Pre-attach a no-op catch: the real await sits AFTER quiesce + the
+      // post-quiesce hops, so an early prerender rejection (e.g. a bake-lane
+      // loader tripping the identity guard within milliseconds) would otherwise
+      // spend several turns handler-less and crash the worker as an unhandled
+      // rejection. The actual rejection handling still happens at the await
+      // below; this parallel handler only keeps the gap crash-free.
+      prerenderPromise.catch(() => {});
+
+      // Wait for the caller's quiesce signal, bounded by the SAME deadline. By
+      // the time it resolves the Flight input is byte-quiet and FROZEN by the
+      // capture gate (shell-capture.ts gateFlightForCapture), so there is no
+      // wall-clock debounce here — maxWaitMs is only the pathological guard for a
+      // shell that never goes quiet (a root postpone / hung handle).
+      await Promise.race([opts.quiesce, deadline.promise]);
+      // Fixed task hops before the abort: give React's fizz worker turns to flush
+      // the now-complete shell and mark the still-pending boundaries as POSTPONED
+      // rather than errored. Deterministic (the byte set is already frozen), so a
+      // fixed count of turns suffices — no wall-clock.
+      for (let i = 0; i < POST_QUIESCE_TASK_HOPS; i++) {
+        await macrotask();
+      }
+      controller.abort(abortReason);
+
+      // A hard prerender rejection (fatal shell error) propagates. Expected
+      // degradation surfaces three ways and all return null: a trivial prelude
+      // (sanity gate below), the prerender REJECTING with our abort reason, or
+      // the prelude STREAM erroring with our abort reason mid-read — both abort
+      // shapes happen when our own abort lands before the shell completed (seen
+      // on dev cold paths, where module transform / first-render latency
+      // outlasts flight quiesce; a later request re-captures against warm
+      // modules and succeeds).
+      let prelude: Uint8Array;
+      let postponed: unknown;
+      try {
+        const result = await prerenderPromise;
+        prelude = await readStreamToUint8Array(result.prelude);
+        postponed = result.postponed;
+      } catch (error) {
+        // Identity match: swallow ONLY our own deliberate abort
+        // (error === abortReason). Not error.name — capture aborts before this
+        // await, so signal.aborted is always true, and a name check let a
+        // genuine AbortError-named throw masquerade as our abort and degrade
+        // into a retryable no-shell, hiding real failures from reportCacheError.
+        if (error === abortReason) {
+          return null;
         }
+        throw error;
+      }
+
+      // Sanity gate: a prelude with no `<body` is the no-shell failure mode.
+      // Return null and store nothing; the request falls back to axis 1 and a
+      // later request re-captures. The dominant real-world cause is a loader
+      // route WITHOUT a route-level loading() boundary: renderSegments' loading-
+      // less branch awaits loader data at TREE-BUILD, so the masked loader pins
+      // the whole tree above <body> (root postpone). Root-postponing layouts and
+      // hung handles degrade the same way. shell-capture.ts logs a once-per-key
+      // warning so the eternal-MISS shape is diagnosable.
+      if (!new TextDecoder().decode(prelude).includes("<body")) {
+        return null;
+      }
+
+      return {
+        prelude,
+        postponed: postponed == null ? null : JSON.stringify(postponed),
+      };
+    } finally {
+      deadline.cancel();
+    }
+  };
+}
+
+/**
+ * Create the PPR shell resume handler.
+ *
+ * resumeShellHTML produces the per-request live portion of the document: for a
+ * postponed shell it resumes fizz over a fresh SsrRoot to emit only the holes;
+ * for the DATA variant it emits only the fresh Flight payload scripts. The
+ * caller (shell-cache middleware) prepends the stored prelude bytes to form the
+ * composite response. See docs/design/ppr-shell-resume.md.
+ */
+export function createShellResumeHandler<TEnv = unknown>(
+  deps: SSRDependencies<TEnv>,
+) {
+  const { createFromReadableStream, injectRSCPayload, resume, onError } = deps;
+
+  /**
+   * @param rscStream - Fresh full Flight stream for this request.
+   * @param opts - postponed state (null = DATA variant) and optional nonce.
+   */
+  return async function resumeShellHTML(
+    rscStream: ReadableStream<Uint8Array>,
+    opts: ShellResumeOptions,
+  ): Promise<ReadableStream<Uint8Array>> {
+    const { postponed, nonce } = opts;
+
+    try {
+      if (postponed === null) {
+        // DATA variant: the stored prelude is the complete shell. No fizz runs;
+        // feed injectRSCPayload a minimal HTML stream so its flush appends the
+        // fresh Flight payload scripts after the shell. The stream must emit at
+        // least one chunk — see createDataVariantHtmlStream.
+        return createDataVariantHtmlStream().pipeThrough(
+          injectRSCPayload(rscStream, { nonce }),
+        );
       }
+
+      if (!resume) {
+        throw new Error(
+          "[createShellResumeHandler] Missing `resume` dependency (react-dom/server.edge). " +
+            "Resuming a postponed shell requires the resume export; wire it in the SSR virtual entry.",
+        );
+      }
+
+      // Tee: one branch deserializes into the SsrRoot VDOM that resume() replays
+      // (a fresh instance is fine — replay matches structure, not identity), the
+      // other feeds the fresh hydration payload to injectRSCPayload.
+      const [rscStream1, rscStream2] = rscStream.tee();
+
+      const SsrRoot = createSsrRootComponent({
+        createFromReadableStream,
+        rscStream: rscStream1,
+        nonce,
+      });
+
+      const resumed = await resume(<SsrRoot />, JSON.parse(postponed), {
+        onError: (error) => reportRenderError(onError, error),
+        nonce,
+      });
+
+      return resumed.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
+    } catch (error) {
+      reportRenderError(onError, error);
       throw error;
     }
   };