@rangojs/router 0.0.0-experimental.144 → 0.0.0-experimental.146

package/src/segment-system.tsx

@@ -17,6 +17,28 @@ import {
   getMemoizedLoaderPromise,
 } from "./segment-loader-promise.js";
 
+/**
+ * Debug log for the segment tree build, gated on the baked flag. Runs on BOTH
+ * sides now, environment-tagged: `[Browser][segments]` lines up with the
+ * `[Browser][boot]` sequence around hydrateRoot; `[Server][segments]` exposes
+ * the SSR/RSC tree-build stalls (blocking loader awaits during fizz are what
+ * dominate MISS TTFB) that used to be invisible because the logs were
+ * window-gated. Server lines have no request correlation — segment-system is
+ * shared client code and cannot import request-context (node:async_hooks
+ * would enter the browser bundle) — so on a busy server, correlate by
+ * timestamp + segment ids.
+ */
+function segDebugLog(msg: string, details?: Record<string, unknown>): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const env = typeof window === "object" ? "[Browser]" : "[Server]";
+  const prefix = `${env}[segments] ${msg} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}
+
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
@@ -212,6 +234,17 @@ export async function renderSegments(
     rootLayout: RootLayout,
   } = options || {};
 
+  const segDebug = INTERNAL_RANGO_DEBUG;
+  const segDebugStart = segDebug ? performance.now() : 0;
+  if (segDebug) {
+    segDebugLog("renderSegments start", {
+      segments: segments.map((s) => `${s.id}:${s.type}`),
+      isAction: !!isAction,
+      forceAwait: !!forceAwait,
+      intercepts: interceptSegments?.length ?? 0,
+    });
+  }
+
   const temporalLazyRefs: Promise<any>[] = [];
   const normalizedSegments = restoreParallelLoaderMarkers(segments);
   const normalizedInterceptSegments = interceptSegments
@@ -272,6 +305,7 @@ export async function renderSegments(
       `Expected layout, route, error, or notFound segment, got ${node.segment.type}`,
     );
     const { component, id, params, loading } = node.segment;
+    const segNodeStart = segDebug ? performance.now() : 0;
 
     // Param-agnostic keys are opt-in via the transition() DSL (see
     // inTransitionScope above). A route (and its route-owned layouts) inside a
@@ -314,7 +348,13 @@ export async function renderSegments(
 
     let resolvedComponent = component;
     if (isAction && component instanceof Promise) {
+      const componentAwaitStart = segDebug ? performance.now() : 0;
       resolvedComponent = await component;
+      if (segDebug) {
+        segDebugLog(`segment ${id}: component awaited (action)`, {
+          ms: Math.round(performance.now() - componentAwaitStart),
+        });
+      }
     }
 
     let nodeContent: ReactNode = null;
@@ -331,9 +371,16 @@ export async function renderSegments(
       // suspends on mount inside the content still reveals a fallback (it is not
       // pre-resolved).
       const contentPromise = getMemoizedContentPromise(resolvedComponent);
-      const loadingContent: Promise<ReactNode> | ReactNode = forceAwait
-        ? await contentPromise
-        : contentPromise;
+      let loadingContent: Promise<ReactNode> | ReactNode = contentPromise;
+      if (forceAwait) {
+        const contentAwaitStart = segDebug ? performance.now() : 0;
+        loadingContent = await contentPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: content awaited (forceAwait)`, {
+            ms: Math.round(performance.now() - contentAwaitStart),
+          });
+        }
+      }
       nodeContent = createElement(RouteContentWrapper, {
         key: `suspense-loading-${id}`,
         content: loadingContent,
@@ -403,10 +450,25 @@ export async function renderSegments(
 
     if (loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
+      let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
+      if (forceAwait || isAction) {
+        const awaitStart = segDebug ? performance.now() : 0;
+        boundaryLoaderData = await loaderDataPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
+            loaderIds,
+            ms: Math.round(performance.now() - awaitStart),
+          });
+        }
+      } else if (segDebug) {
+        segDebugLog(
+          `segment ${id}: streaming loaders via LoaderBoundary (suspense)`,
+          { loaderIds },
+        );
+      }
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
-        loaderDataPromise:
-          forceAwait || isAction ? await loaderDataPromise : loaderDataPromise,
+        loaderDataPromise: boundaryLoaderData,
         loaderIds,
         fallback: loading,
         outletKey: key,
@@ -430,11 +492,30 @@ export async function renderSegments(
       );
 
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
+      // No loading() on this segment, so its loader data cannot stream behind
+      // a Suspense fallback — the tree build BLOCKS here until the data
+      // arrives. On the initial document this await runs before hydrateRoot.
+      const layoutAwaitStart = segDebug ? performance.now() : 0;
       const resolvedData = await buildLoaderPromise(layoutLoaders);
+      if (segDebug) {
+        segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
+          loaderIds: layoutLoaderIds,
+          ms: Math.round(performance.now() - layoutAwaitStart),
+        });
+      }
+      const decodeStart = segDebug ? performance.now() : 0;
       const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
       );
+      if (segDebug) {
+        const decodeMs = Math.round(performance.now() - decodeStart);
+        if (decodeMs > 0) {
+          segDebugLog(`segment ${id}: loader results decoded`, {
+            ms: decodeMs,
+          });
+        }
+      }
 
       if (parallelOwnedLoaders.length > 0) {
         const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
@@ -463,10 +544,27 @@ export async function renderSegments(
 
           p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
           const aggregated = getMemoizedLoaderPromise(ownedLoaders);
-          p.loaderDataPromise =
-            (forceAwait || isAction) && aggregated instanceof Promise
-              ? await aggregated
-              : aggregated;
+          if ((forceAwait || isAction) && aggregated instanceof Promise) {
+            const parallelAwaitStart = segDebug ? performance.now() : 0;
+            p.loaderDataPromise = await aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action)`,
+                {
+                  loaderIds: p.loaderIds,
+                  ms: Math.round(performance.now() - parallelAwaitStart),
+                },
+              );
+            }
+          } else {
+            p.loaderDataPromise = aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders streaming (suspense)`,
+                { loaderIds: p.loaderIds },
+              );
+            }
+          }
         }
       }
 
@@ -490,6 +588,16 @@ export async function renderSegments(
         children: content,
       });
     }
+
+    if (segDebug) {
+      segDebugLog(`segment ${id} built`, {
+        type: node.segment.type,
+        ms: Math.round(performance.now() - segNodeStart),
+        loaders: node.loaders.map((l) => l.loaderId).filter(Boolean),
+        hasLoading: loading !== undefined && loading !== null,
+        parallel: node.parallel.map((p) => p.id),
+      });
+    }
   }
 
   const errorBoundaryWrapped = createElement(RootErrorBoundary, {
@@ -524,6 +632,12 @@ export async function renderSegments(
     });
   }
 
+  if (segDebug) {
+    segDebugLog("renderSegments complete", {
+      ms: Math.round(performance.now() - segDebugStart),
+    });
+  }
+
   return result;
 }
 

package/src/server/request-context.ts

@@ -210,6 +210,53 @@ export interface RequestContext<
    */
   _shellLoaderSeed?: Map<string, unknown>;
 
+  /**
+   * @internal Shell fast-path marker: makes the NEXT full match treat the whole
+   * matched route as an implicit doc-level cache() boundary (see
+   * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
+   * (a) the capture's derived context — with a record-only store so the
+   * capture's cacheRoute write lands in the snapshot, never the real store —
+   * and (b) a HIT tail's seeded context when the entry is eligible
+   * (!handlerLiveHoles), where the SeededShellStore serves the recorded doc
+   * entry and the match skips handler execution entirely. Routes with their
+   * own cache() config (including cache(false)) are never overridden: the
+   * marker only applies when the route tree derived NO cache scope.
+   */
+  _shellImplicitCache?: {
+    ttl?: number;
+    swr?: number;
+    store?: SegmentCacheStore;
+  };
+
+  /**
+   * @internal Handler-layer liveness observed DURING a shell capture, from
+   * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
+   * when a push made OUTSIDE a DSL loader scope carries a nested thenable
+   * (masked to a never-filling hole); (b) still-pending top-level handler
+   * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
+   * executing during the capture (loader-resolution.ts — its consumption-lane
+   * value would freeze on a handler-free HIT). captureAndStoreShell folds it
+   * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
+   * property of the capture's derived context only.
+   */
+  _shellCaptureHandleLiveness?: {
+    holes: boolean;
+    pendingPushes: number;
+    handlerInvokedLoader: boolean;
+  };
+
+  /**
+   * @internal Handle values pushed from a DSL loader scope DURING a shell
+   * capture (identity set; populated by the capture push wrapper in
+   * shell-capture.ts). cacheRoute threads it into captureHandles so those
+   * values stay out of cache-write handle records — loaders re-run fresh on
+   * every HIT, so replaying their captured (masked) values would duplicate
+   * the fresh push and stall the Flight handle encode. Own property of the
+   * capture's derived context only; render-time handle consumers are
+   * unaffected (the exclusion applies only at the captureHandles call site).
+   */
+  _shellCaptureLoaderHandleValues?: WeakSet<object>;
+
   /**
    * @internal Set (to the offending fn name) by the cookies()/headers()
    * capture guard when it throws DURING a capture render. Load-bearing for the

package/src/ssr/index.tsx

@@ -1,6 +1,11 @@
 import React from "react";
 import { createSsrRootComponent } from "./ssr-root.js";
+import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
+import { runWithPreinitNonce } from "./preinit-client-references.js";
 import type { ErrorPhase } from "../types.js";
+import type { HeadScriptsOption } from "../vite/plugin-types.js";
+
+export { installClientReferencePreinit } from "./preinit-client-references.js";
 
 /**
  * Options for injectRSCPayload
@@ -17,6 +22,7 @@ export interface InjectRSCPayloadOptions {
  */
 interface RenderToReadableStreamOptions {
   bootstrapScriptContent?: string;
+  bootstrapModules?: string[];
   nonce?: string;
   formState?: unknown;
 }
@@ -34,6 +40,7 @@ interface ReactDOMReadableStream extends ReadableStream<Uint8Array> {
 interface PrerenderOptions {
   signal?: AbortSignal;
   bootstrapScriptContent?: string;
+  bootstrapModules?: string[];
   onError?: (error: unknown) => void;
 }
 
@@ -132,6 +139,17 @@ export interface SSRDependencies<TEnv = unknown> {
    */
   loadBootstrapScriptContent: () => Promise<string>;
 
+  /**
+   * Document script strategy; the generated virtual SSR entry threads the
+   * `rango({ headScripts })` plugin option here (canonical docs on
+   * `RangoBaseOptions.headScripts` in vite/plugin-types.ts). The
+   * bootstrapModules conversion runs ONLY on an explicit `"preinit"`:
+   * undefined keeps the inline bootstrap verbatim, so a custom SSR entry that
+   * never installed the preinit hook cannot drift into the half-converted
+   * state on upgrade (the generated entry always passes an explicit value).
+   */
+  headScripts?: HeadScriptsOption;
+
   /**
    * prerender from react-dom/static.edge. Optional; required only by
    * {@link createShellCaptureHandler} for PPR shell capture.
@@ -325,6 +343,47 @@ interface ShellResumeOptions {
   nonce?: string;
 }
 
+/**
+ * The exact shape plugin-rsc's loadBootstrapScriptContent returns in both dev
+ * and build: a single dynamic import of the browser entry, nothing else.
+ * Escapes/other statements never appear in that generated content; anything
+ * that doesn't match falls back to inline bootstrapScriptContent unchanged.
+ */
+const BOOTSTRAP_IMPORT_ONLY_RE =
+  /^\s*import\(\s*(["'])([^"'\\]+)\1\s*\)\s*;?\s*$/;
+
+/**
+ * Prefer bootstrapModules over the inline import() bootstrap. When the content
+ * is exactly `import("<entry-url>")`, hand Fizz the URL instead: React then
+ * emits a `<link rel="modulepreload" fetchpriority="low">` hint in the head
+ * plus the executing `<script type="module" src async>` at end of shell — the
+ * entry fetch starts with the first flushed bytes instead of when the parser
+ * reaches an opaque inline script that only reveals the URL once executed.
+ * Fizz stamps the request nonce on both tags (the inline form needed that
+ * too), and under PPR both land in the stored prelude; on resume React has
+ * already cleared the bootstrap fields from the postponed state, so nothing
+ * re-emits.
+ */
+function resolveBootstrapOptions(
+  content: string,
+  headScripts: SSRDependencies["headScripts"],
+): Pick<
+  RenderToReadableStreamOptions,
+  "bootstrapScriptContent" | "bootstrapModules"
+> {
+  // Explicit opt-in only: undefined (a custom SSR entry that predates the
+  // option, which also never installed the preinit hook) keeps the inline
+  // bootstrap byte-for-byte — converting by default would break CSPs that
+  // allowlist the known inline import() via a script hash.
+  if (headScripts !== "preinit") {
+    return { bootstrapScriptContent: content };
+  }
+  const match = BOOTSTRAP_IMPORT_ONLY_RE.exec(content);
+  return match
+    ? { bootstrapModules: [match[2]!] }
+    : { bootstrapScriptContent: content };
+}
+
 /**
  * Create an SSR handler that converts RSC streams to HTML.
  *
@@ -382,12 +441,16 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
 
       // Render React tree to HTML stream
       // Pass formState for useActionState progressive enhancement if provided
-      // Pass nonce for CSP if provided
-      const htmlStream = await renderToReadableStream(<SsrRoot />, {
-        bootstrapScriptContent,
-        formState,
-        nonce,
-      });
+      // Pass nonce for CSP if provided. runWithPreinitNonce makes the same
+      // nonce visible to the client-reference preinit hook (ALS — the hook is
+      // isolate-global, the nonce per request).
+      const htmlStream = await runWithPreinitNonce(nonce, () =>
+        renderToReadableStream(<SsrRoot />, {
+          ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
+          formState,
+          nonce,
+        }),
+      );
 
       // Wait for all Suspense boundaries to resolve when streamMode is "allReady".
       // This buffers the entire HTML before flushing — used for bots that
@@ -489,7 +552,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
       const abortReason = { rangoShellCaptureAbort: true };
       const prerenderPromise = prerender(<SsrRoot />, {
         signal: controller.signal,
-        bootstrapScriptContent,
+        ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
         // 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.
@@ -594,7 +657,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
 export function createShellResumeHandler<TEnv = unknown>(
   deps: SSRDependencies<TEnv>,
 ) {
-  const { createFromReadableStream, injectRSCPayload, resume, onError } = deps;
+  const { createFromReadableStream, resume, onError } = deps;
 
   /**
    * @param rscStream - Fresh full Flight stream for this request.
@@ -609,11 +672,12 @@ export function createShellResumeHandler<TEnv = unknown>(
     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.
+        // the eager injector pumps the fresh Flight payload scripts without
+        // needing an HTML chunk to trigger it (the stock injector deadlocked on
+        // a chunkless stream — see createDataVariantHtmlStream, kept for the
+        // batching invariant's sake).
         return createDataVariantHtmlStream().pipeThrough(
-          injectRSCPayload(rscStream, { nonce }),
+          injectRSCPayloadEager(rscStream, { nonce }),
         );
       }
 
@@ -635,12 +699,48 @@ export function createShellResumeHandler<TEnv = unknown>(
         nonce,
       });
 
-      const resumed = await resume(<SsrRoot />, JSON.parse(postponed), {
-        onError: (error) => reportRenderError(onError, error),
-        nonce,
-      });
-
-      return resumed.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
+      // EAGER injection (resume-only): the stored prelude — a complete document
+      // through </body></html> — is already on the wire ahead of this stream,
+      // so a Flight <script> is valid as the first tail byte. The stock
+      // injector waits for the first fizz chunk, which only appears when the
+      // first hole's loaders resolve — parking the whole hydration payload
+      // (root row included) behind the slowest live loader. See
+      // inject-rsc-eager.ts for the measured failure mode.
+      //
+      // EAGER HANDOVER: return the injector's readable BEFORE awaiting
+      // resume(). react-dom's resume() promise resolves only when the resumed
+      // shell (everything above the postponed holes) completes — which waits
+      // on the live loaders — so `await resume(...).pipeThrough(...)` parked
+      // the already-flowing Flight bytes a second time, behind the handshake
+      // instead of the stream (measured: injector output at +9ms, first tail
+      // byte on the wire at +735ms). Piping fizz in when it materializes lets
+      // serveShellHit start draining Flight immediately; pipeTo closes the
+      // writable on completion, which runs the injector's flush (trailer). A
+      // resume() rejection aborts the writable so the response errors instead
+      // of hanging.
+      const injector = injectRSCPayloadEager(rscStream2, { nonce });
+      void (async () => {
+        try {
+          // Nonce wrap mirrors renderHTML: client references first discovered
+          // during resume (holes the shell never rendered) preinit into the
+          // resumed stream and need the per-request nonce.
+          const resumed = await runWithPreinitNonce(nonce, () =>
+            resume(<SsrRoot />, JSON.parse(postponed), {
+              onError: (error) => reportRenderError(onError, error),
+              nonce,
+            }),
+          );
+          await resumed.pipeTo(injector.writable);
+        } catch (error) {
+          reportRenderError(onError, error);
+          try {
+            await injector.writable.abort(error);
+          } catch {
+            // Writable already errored/closed; the readable side has the error.
+          }
+        }
+      })();
+      return injector.readable;
     } catch (error) {
       reportRenderError(onError, error);
       throw error;

package/src/ssr/inject-rsc-eager.ts

@@ -0,0 +1,167 @@
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+
+/**
+ * Eager Flight-payload injector for the PPR resume path.
+ *
+ * rsc-html-stream's injectRSCPayload starts forwarding Flight chunks only from
+ * inside its first transform() callback — i.e. AFTER the first HTML chunk flows.
+ * That policy exists for the normal document path (a <script> must not precede
+ * the doctype). On a PPR shell HIT it parks the ENTIRE hydration payload: the
+ * resumed fizz render emits its first chunk only when the first hole's data
+ * resolves (live loaders — measured ~1.5s on SFCC-backed pages), while the
+ * Flight root row is ready within ~30ms of the tail render starting. The client
+ * cannot call hydrateRoot until that root row arrives, so the lazy start held
+ * hydration hostage to the slowest loader for no structural reason: the stored
+ * prelude (a complete document through </body></html>) is already on the wire
+ * before the tail, so every tail byte is foster-parented and a Flight <script>
+ * is valid as the FIRST tail byte.
+ *
+ * This injector starts pumping Flight chunks immediately in start(). Ordering
+ * safety is kept by serializing ALL writes through one promise chain: fizz
+ * chunks buffered within a tick flush as one atomic task (same batching idea as
+ * the stock injector — never inject between two partial HTML chunks), and each
+ * Flight script is its own task, so scripts land only between batches. The
+ * trailer is stripped from passing HTML and re-appended once, after both
+ * streams complete — identical to the stock contract.
+ *
+ * RESUME/DATA-VARIANT ONLY. The normal document path must keep the stock
+ * injector: there the first bytes are the document head, and an eager script
+ * would precede the doctype.
+ */
+
+const encoder = new TextEncoder();
+const TRAILER = "</body></html>";
+
+// Escape closing script tags and HTML comments in JS content (ported from
+// rsc-html-stream/server; escapes the "s" instead of the slash so a regexp
+// literal like `0</script/` stays valid JS).
+function escapeScript(script: string): string {
+  return script.replace(/<!--/g, "<\\!--").replace(/<\/(script)/gi, "</\\$1");
+}
+
+function writeScript(
+  controller: TransformStreamDefaultController<Uint8Array>,
+  jsExpr: string,
+  nonce: string | undefined,
+): void {
+  controller.enqueue(
+    encoder.encode(
+      `<script${nonce ? ` nonce="${nonce}"` : ""}>${escapeScript(
+        `(self.__FLIGHT_DATA||=[]).push(${jsExpr})`,
+      )}</script>`,
+    ),
+  );
+}
+
+export function injectRSCPayloadEager(
+  rscStream: ReadableStream<Uint8Array>,
+  options?: { nonce?: string },
+): TransformStream<Uint8Array, Uint8Array> {
+  const nonce = options?.nonce;
+  const htmlDecoder = new TextDecoder();
+  const t0 = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
+  let loggedFirstFlight = false;
+  let loggedFirstHtml = false;
+
+  // All output goes through this chain: one task per Flight script, one task
+  // per buffered-HTML batch. A script can therefore never split a batch.
+  let queue: Promise<void> = Promise.resolve();
+  const enqueueTask = (fn: () => void): Promise<void> => {
+    queue = queue.then(fn);
+    return queue;
+  };
+
+  let buffered: Uint8Array[] = [];
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  let rscDone: Promise<void> = Promise.resolve();
+
+  function flushBufferedHTML(
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): void {
+    if (INTERNAL_RANGO_DEBUG && !loggedFirstHtml && buffered.length > 0) {
+      loggedFirstHtml = true;
+      console.log(
+        `[Server][ppr] eager-inject: first resumed HTML batch +${Math.round(performance.now() - t0)}ms (abs ${Math.round(performance.now())})`,
+      );
+    }
+    for (const chunk of buffered) {
+      let buf = htmlDecoder.decode(chunk, { stream: true });
+      if (buf.endsWith(TRAILER)) buf = buf.slice(0, -TRAILER.length);
+      controller.enqueue(encoder.encode(buf));
+    }
+    const remaining = htmlDecoder.decode();
+    if (remaining.length) {
+      const out = remaining.endsWith(TRAILER)
+        ? remaining.slice(0, -TRAILER.length)
+        : remaining;
+      controller.enqueue(encoder.encode(out));
+    }
+    buffered.length = 0;
+    timeout = null;
+  }
+
+  async function pumpRSC(
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): Promise<void> {
+    const rscDecoder = new TextDecoder("utf-8", { fatal: true });
+    const reader = rscStream.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      // String when the chunk is valid unicode, base64 round-trip otherwise —
+      // same fallback the stock injector uses.
+      let jsExpr: string;
+      try {
+        jsExpr = JSON.stringify(rscDecoder.decode(value, { stream: true }));
+      } catch {
+        const base64 = JSON.stringify(
+          btoa(String.fromCodePoint(...(value as Uint8Array))),
+        );
+        jsExpr = `Uint8Array.from(atob(${base64}), m => m.codePointAt(0))`;
+      }
+      await enqueueTask(() => {
+        if (INTERNAL_RANGO_DEBUG && !loggedFirstFlight) {
+          loggedFirstFlight = true;
+          console.log(
+            `[Server][ppr] eager-inject: first flight script +${Math.round(performance.now() - t0)}ms (abs ${Math.round(performance.now())})`,
+          );
+        }
+        writeScript(controller, jsExpr, nonce);
+      });
+    }
+    const remaining = rscDecoder.decode();
+    if (remaining.length) {
+      await enqueueTask(() =>
+        writeScript(controller, JSON.stringify(remaining), nonce),
+      );
+    }
+  }
+
+  return new TransformStream<Uint8Array, Uint8Array>({
+    start(controller) {
+      // The eager part: pump Flight immediately, before any HTML arrives.
+      rscDone = pumpRSC(controller).catch((err) => {
+        try {
+          controller.error(err);
+        } catch {
+          // Stream already errored/closed; nothing to signal.
+        }
+      });
+    },
+    transform(chunk, controller) {
+      buffered.push(chunk);
+      if (timeout) return;
+      // Batch same-tick fizz chunks so a Flight script cannot land between two
+      // partial HTML chunks of one logical write (stock injector's invariant).
+      timeout = setTimeout(() => {
+        void enqueueTask(() => flushBufferedHTML(controller));
+      }, 0);
+    },
+    async flush(controller) {
+      await rscDone;
+      if (timeout) clearTimeout(timeout);
+      await enqueueTask(() => flushBufferedHTML(controller));
+      controller.enqueue(encoder.encode(TRAILER));
+    },
+  });
+}