npm - @uniflowed/router - Versions diffs - 0.0.0-alpha.8 → 0.1.0 - Mend

@uniflowed/router 0.0.0-alpha.8 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (49) hide show

package/action.js +324 -0
package/client.js +261 -7
package/handler.js +113 -99
package/http-client.js +104 -0
package/index.js +49 -6
package/instrumentation.js +92 -0
package/internal/action-endpoint.js +438 -0
package/internal/action-wire.js +608 -0
package/internal/base-path.js +175 -0
package/internal/boundaries.js +481 -0
package/internal/boundary-data.js +88 -0
package/internal/compose.js +490 -0
package/internal/deployment.js +160 -0
package/internal/devtools.js +131 -0
package/internal/diagnostics.js +169 -0
package/internal/error-view.js +193 -0
package/internal/flight-browser.js +242 -0
package/internal/flight-chunks.js +205 -0
package/internal/flight-rows.js +135 -0
package/internal/flight-ssr.js +91 -0
package/internal/flight.js +192 -0
package/internal/head.js +219 -0
package/internal/hydration.js +1085 -0
package/internal/inspector.js +626 -0
package/internal/native-links.js +67 -0
package/internal/native-tree.js +89 -0
package/internal/navigation-cache.js +181 -0
package/internal/payload-rows.js +270 -0
package/internal/payload.js +685 -0
package/internal/prepare-document.js +54 -0
package/internal/react-version.js +77 -0
package/internal/resolve.js +1617 -0
package/internal/resolved-summary.js +199 -0
package/internal/routing.js +478 -0
package/internal/runtime.js +1597 -1329
package/internal/server-instrumentation.js +12 -0
package/internal/server-route.js +58 -0
package/internal/shell.js +125 -0
package/internal/stream.js +754 -21
package/middleware.js +161 -22
package/native-navigation.js +217 -0
package/native.js +416 -0
package/package.json +48 -7
package/routing.js +51 -0
package/rsc-client.js +120 -0
package/rsc-ssr.js +637 -0
package/rsc.js +402 -0
package/server-components.js +159 -0
package/server.js +254 -106

package/internal/stream.js CHANGED Viewed

@@ -43,6 +43,9 @@ import * as React from "react";
 import * as ReactDOMServer from "react-dom/server";
 import * as ReactDOMStatic from "react-dom/static";
+import { createChunkEncoder } from "./flight-chunks.js";
+import { type StreamRecord, inspected } from "./inspector.js";
 /**
  * Where a document is written, when the host has a Node stream.
  *
@@ -125,8 +128,13 @@ export type DocumentShell = {|
    * `</head>` React writes.
    */
   readonly head: string,
-  /** Everything before the markup of an app that renders no document. */
+  /**
+   * For an app that renders no document: everything up to the point uf's own
+   * head can still take tags — so it ends *inside* an open `<head>`.
+   */
   readonly open: string,
+  /** The rest of that head, and everything up to the app's markup. */
+  readonly body: string,
   /** Everything after it. */
   readonly close: string,
 |};
@@ -293,16 +301,39 @@ function queueDestination(queue: ChunkQueue): NodeDestination {
  * React writes a document with no head at all — an app whose root layout is
  * `<html><body>` — the tags go in a head of uf's own, inserted after the
  * opening tag, which is what the browser would have synthesized anyway.
+ *
+ * The shell case waits for the end of the run of hoistable elements React
+ * opened with, because that is where *its* tags go — see [`hoisted`]. Both
+ * waits are bounded by the head, and both are the same idea: the head goes out
+ * once, and everything that belongs in it has to be in hand by then.
  */
 async function* assembled(
   chunks: AsyncGenerator<string, void, void>,
   shell: DocumentShell,
+  transformHead?: (html: string) => Promise<string>,
+  layout?: Layout,
 ): AsyncGenerator<string, void, void> {
   let held = "";
   let shape = "unknown";
+  // A document uf wraps is the only one whose root is not `<body>` itself.
+  const wrapped = () => {
+    if (layout != null) {
+      layout.rootDepth = advanced(NOTHING_WRITTEN, shell.open + shell.body, 0).depth ?? 0;
+    }
+  };
+  // The opening chunk is the only one the hook sees, and every path below
+  // reaches exactly one of them. Awaiting here rather than at each `yield`
+  // keeps them from drifting apart. The hook sees only the document opening:
+  // Vite's HTML parser is happy with an open body, but not with a React chunk
+  // that happens to end inside an attribute.
+  const opening = async (html: string, rest: string = ""): Promise<string> => {
+    const split = transformableOpening(html);
+    const transformed = transformHead == null ? split.opening : await transformHead(split.opening);
+    return transformed + split.rest + rest;
+  };
   for await (const chunk of chunks) {
-    if (shape === "document-open" || shape === "shell") {
+    if (shape === "document-open" || shape === "shell-open") {
       yield chunk;
       continue;
     }
@@ -312,40 +343,57 @@ async function* assembled(
       if (shape === "unknown") {
         continue;
       }
-      if (shape === "shell") {
-        yield shell.open + held;
-        held = "";
+    }
+    if (shape === "shell") {
+      const split = hoisted(held);
+      if (!split.complete) {
         continue;
       }
+      shape = "shell-open";
+      wrapped();
+      yield await opening(shell.open + split.head + shell.body, split.rest);
+      held = "";
+      continue;
     }
     // A document, and the tags go where its head closes.
     const close = held.indexOf("</head>");
     if (close !== -1) {
       shape = "document-open";
-      yield ufDoctype(held.slice(0, close) + shell.head + held.slice(close));
+      yield await opening(ufDoctype(held.slice(0, close) + shell.head + held.slice(close)));
       held = "";
       continue;
     }
     // `<body` before `</head>` means React wrote no head; give the tags one.
     const body = held.search(/<body[\s>]/i);
     if (body !== -1) {
+      const bodyEnd = held.indexOf(">", body);
+      if (bodyEnd === -1) {
+        continue;
+      }
       shape = "document-open";
-      yield ufDoctype(`${held.slice(0, body)}<head>${shell.head}</head>${held.slice(body)}`);
+      yield await opening(
+        ufDoctype(`${held.slice(0, body)}<head>${shell.head}</head>${held.slice(body)}`),
+      );
       held = "";
     }
   }
-  // The render ended before the decision could be made, or before the head it
-  // opened was closed: an empty document, or one with neither `</head>` nor
-  // `<body>` in it. There is nothing left to wait for either way.
+  // The render ended before the decision could be made, or before what was
+  // being waited for arrived: an empty document, one with neither `</head>` nor
+  // `<body>` in it, or a shell that is hoistable elements all the way down.
+  // There is nothing left to wait for in any of them.
   if (shape === "document") {
-    yield ufDoctype(held + shell.head);
+    yield await opening(ufDoctype(held + shell.head));
     shape = "document-open";
-  } else if (shape === "unknown") {
-    shape = "shell";
-    yield shell.open + held;
+  } else if (shape === "shell" || shape === "unknown") {
+    // `complete` is not consulted: nothing more is coming, so a run that was
+    // still open is over and whatever was left of it is markup like any other.
+    const split = hoisted(held);
+    shape = "shell-open";
+    wrapped();
+    yield await opening(shell.open + split.head + shell.body, split.rest);
   }
-  if (shape === "shell") {
+  if (shape === "shell-open") {
     yield shell.close;
   } else {
     // The newline `assemble` ended a document with, kept: `uf build` writes
@@ -355,6 +403,116 @@ async function* assembled(
   }
 }
+function transformableOpening(html: string): {| readonly opening: string, readonly rest: string |} {
+  const lower = html.toLowerCase();
+  const headEnd = lower.indexOf("</head>");
+  if (headEnd === -1) {
+    return { opening: html, rest: "" };
+  }
+  const afterHead = headEnd + "</head>".length;
+  const body = lower.indexOf("<body", afterHead);
+  if (body === -1) {
+    return { opening: html.slice(0, afterHead), rest: html.slice(afterHead) };
+  }
+  const bodyEnd = html.indexOf(">", body);
+  if (bodyEnd === -1) {
+    return { opening: html.slice(0, afterHead), rest: html.slice(afterHead) };
+  }
+  const afterBody = bodyEnd + 1;
+  return { opening: html.slice(0, afterBody), rest: html.slice(afterBody) };
+}
+/**
+ * The head elements React opened the app's markup with, split from the rest.
+ *
+ * `complete` is false while the buffer might still be in the middle of one — a
+ * chunk that ends inside `<meta cont`, or after a `<link>` and before whatever
+ * follows it. Deciding on an incomplete buffer would be a classification that
+ * depends on where React split its output, which is the bug `documentShape`
+ * above is written the way it is to avoid. The split is filled in either way,
+ * because the caller that has run out of chunks has nothing left to wait for
+ * and wants it.
+ *
+ * # Why a leading run rather than the whole document
+ *
+ * React hoists a `<title>`, a `<meta>` and a `<link>` into the `<head>` of a
+ * document *it* rendered. uf's shell is not one — React is handed the app, not
+ * the document — so with the shell every one of those landed in the body, and
+ * `<link rel="canonical">` in a body is a canonical link Google does not read.
+ * The fix is for uf to do the hoisting into the head it wrote itself.
+ *
+ * A leading run is what can be hoisted without holding the document. `RouteView`
+ * renders the route's metadata first, before the layouts and the page, so the
+ * run is exactly that metadata and the wait ends at the first byte of the
+ * application's own markup. Scanning further would mean buffering an arbitrary
+ * amount of a document to find a `<meta>` that might be at the end of it, which
+ * is streaming in shape and buffering in fact — the same trade this module
+ * refuses in `ChunkQueue`. So a tag a component renders further in stays where
+ * it is, and on a client React will hoist it into `document.head` itself.
+ *
+ * # Reading React's markup with a regular expression
+ *
+ * Which is only safe because it is React's. React escapes `>` in an attribute
+ * value and `<` in text, so the first `>` after an opening tag ends it and the
+ * first `</title>` ends a title — neither can appear inside one. This function
+ * is not an HTML parser and must never be handed markup from anywhere else.
+ */
+function hoisted(held: string): HoistedHead {
+  let index = 0;
+  while (index < held.length) {
+    const rest = held.slice(index);
+    const split = { head: held.slice(0, index), rest, complete: false };
+    const open = rest.match(/^<(title|meta|link)(?=[\s/>])/i);
+    if (open == null) {
+      // Not a hoistable element, or not yet enough bytes to say it is not one.
+      return { ...split, complete: !couldOpenHoistable(rest) };
+    }
+    const close = held.indexOf(">", index);
+    if (close === -1) {
+      return split;
+    }
+    if (open[1].toLowerCase() !== "title") {
+      index = close + 1;
+      continue;
+    }
+    const end = held.indexOf("</title>", close);
+    if (end === -1) {
+      return split;
+    }
+    index = end + "</title>".length;
+  }
+  // Every byte so far is a complete hoistable element, and the next one may
+  // still be on its way — the case a document that is metadata and nothing else
+  // ends in, and the reason the loop is bounded by the buffer rather than by
+  // `true`: a `while (true)` here is a function the checker reads as returning
+  // `void` on a path it cannot see is unreachable.
+  return { head: held, rest: "", complete: false };
+}
+/** What [`hoisted`] found, and whether more bytes could still change it. */
+type HoistedHead = {|
+  /** The hoistable elements the markup opened with. */
+  readonly head: string,
+  /** Everything after them. */
+  readonly rest: string,
+  /** Whether the run is known to have ended. */
+  readonly complete: boolean,
+|};
+/**
+ * Whether `rest` could still turn into a hoistable element once more bytes
+ * arrive.
+ *
+ * True for `"<"` and for every proper prefix of `<title`, `<meta` and `<link` —
+ * the states a chunk boundary can leave the buffer in. False for `<main`, and
+ * false for `<titlebar>`, which is somebody's component and not a title however
+ * much of it has arrived.
+ */
+function couldOpenHoistable(rest: string): boolean {
+  const text = rest.toLowerCase();
+  return ["<title", "<meta", "<link"].some((tag) => tag.startsWith(text));
+}
 /**
  * uf's spelling of the doctype, in place of whichever one React wrote.
  *
@@ -472,8 +630,85 @@ export type RenderOptions = {|
    * shell's own failure is not reported here — it rejects instead.
    */
   readonly onError: (error: mixed) => void,
+  /**
+   * Rewrite the document opening — the head and, when present, the body start
+   * tag — before it goes out.
+   *
+   * For `uf dev`, and only for it. Vite's `transformIndexHtml` rewrites asset
+   * URLs and injects `/@vite/client` and the refresh preamble, and it is a
+   * *whole document* hook, so the development server used to collect the page
+   * and transform it at the end. That made the one place a developer would
+   * notice streaming the one place it did not happen: a slow page showed
+   * nothing until it was finished, and `$loading.js` looked broken.
+   * See ubugeeei-prod/uf#374.
+   *
+   * The hook never sees application body markup, which is what makes this
+   * safe. Vite's injections are string-based against `<head>` and `<body>`,
+   * and its parser accepts a document that stops after the body start tag.
+   * It does not accept a React chunk that ends in the middle of an attribute.
+   *
+   * Absent everywhere else. `uf start`, `uf preview` and every deploy adapter
+   * have no such hook and stream already.
+   */
+  readonly transformHead?: (html: string) => Promise<string>,
+  /**
+   * Told what left, in what order, and what each chunk built.
+   *
+   * For `uf dev`, like `transformHead` above, and absent everywhere else —
+   * which is what makes it free rather than cheap: with nothing supplied no
+   * recorder is constructed, `./inspector.js` is never entered, and the
+   * generator a host consumes is the same object it was. See that module for
+   * what is done with the record and why it is a development affordance rather
+   * than a metric.
+   *
+   * Called once per document, after the last chunk and also after a render that
+   * was abandoned partway. `prerenderDocument` never calls it: a build resolves
+   * everything before it writes a byte, so there is no order to report.
+   */
+  readonly onStream?: (record: StreamRecord) => void,
+  /**
+   * The Flight payload this document's tree was read from, to write into the
+   * document for the browser to hydrate from.
+   *
+   * Absent for a document rendered from the route's modules, which is what
+   * every document was before ubugeeei-prod/uf#519 and what `app.rsc: false`
+   * still asks for. Present, it is copied into the document as it arrives, by
+   * [`interleaved`], which says where it may and may not go.
+   */
+  readonly payload?: ReadableStream<Uint8Array>,
+  /**
+   * This response's Content-Security-Policy nonce, or absent for none.
+   *
+   * Absent is what every render had before nonces existed and what every
+   * render still has in a project that has not asked for one, so a document
+   * written without it is byte-for-byte the document uf has always written.
+   *
+   * Present, it reaches three places, and it has to reach all three or the
+   * page is broken rather than merely unprotected: React's own option, which
+   * nonces every inline script React emits — the runtime that reveals a
+   * `<Suspense>` boundary, and the bootstrap; `shell.open`/`shell.body`, which
+   * carry the client entry; and the payload chunk elements, which
+   * [`interleaved`] writes as text.
+   *
+   * `prerenderDocument` is deliberately never given one. See its own paragraph.
+   */
+  readonly nonce?: string | null,
 |};
+/**
+ * `chunks`, recorded on the way out when `uf dev` asked for it.
+ *
+ * The wrapping goes here rather than around `assembled` in each of the callers
+ * so that what is recorded is unambiguous: these are the bytes the host is
+ * handed, head and all, and not React's own output on the way past.
+ */
+function outgoing(
+  chunks: AsyncGenerator<string, void, void>,
+  onStream?: (record: StreamRecord) => void,
+): AsyncGenerator<string, void, void> {
+  return onStream == null ? chunks : inspected(chunks, onStream, () => performance.now());
+}
 /**
  * Stream `node` as a document, resolving once the shell is ready.
  *
@@ -491,12 +726,31 @@ export function renderDocument(node: React.Node, options: RenderOptions): Promis
       const { pipe, abort } = ReactDOMServer.renderToPipeableStream(node, {
         onShellReady() {
           pipe(queueDestination(queue));
-          resolve(bodyOf(assembled(queue.chunks(), options.shell), () => abort()));
+          resolve(
+            bodyOf(
+              outgoing(
+                withPayload(
+                  queue.chunks(),
+                  options.shell,
+                  options.transformHead,
+                  options.payload,
+                  options.nonce,
+                ),
+                options.onStream,
+              ),
+              () => abort(),
+            ),
+          );
         },
         onShellError(error: mixed) {
           reject(error);
         },
         onError: options.onError,
+        // Every inline script React writes for this document, from one option:
+        // the streaming runtime that reveals a boundary and patches a segment,
+        // and the bootstrap. uf nonces the scripts it writes itself; these are
+        // React's, and there is no other way to reach them.
+        nonce: options.nonce ?? undefined,
       });
       return;
     }
@@ -524,6 +778,7 @@ type ReadableStreamRenderer = (
   settings: {|
     readonly onError: (error: mixed) => void,
     readonly signal: AbortSignal,
+    readonly nonce?: string,
   |},
 ) => Promise<ByteSource>;
@@ -549,11 +804,26 @@ export function renderWithReadableStream(
   options: RenderOptions,
 ): Promise<DocumentBody> {
   const controller = new AbortController();
-  return render(node, { onError: options.onError, signal: controller.signal }).then(
-    (stream: ByteSource) =>
-      bodyOf(assembled(decoded(stream), options.shell), () => {
+  return render(node, {
+    onError: options.onError,
+    signal: controller.signal,
+    nonce: options.nonce ?? undefined,
+  }).then((stream: ByteSource) =>
+    bodyOf(
+      outgoing(
+        withPayload(
+          decoded(stream),
+          options.shell,
+          options.transformHead,
+          options.payload,
+          options.nonce,
+        ),
+        options.onStream,
+      ),
+      () => {
         controller.abort();
-      }),
+      },
+    ),
   );
 }
@@ -602,7 +872,470 @@ export async function prerenderDocument(node: React.Node, options: RenderOptions
     typeof ReactDOMStatic.prerenderToNodeStream === "function"
       ? await ReactDOMStatic.prerenderToNodeStream(node, settings)
       : await ReactDOMStatic.prerender(node, settings);
-  return bodyOf(assembled(preludeChunks(result.prelude), options.shell)).text();
+  return bodyOf(
+    withPayload(
+      preludeChunks(result.prelude),
+      options.shell,
+      options.transformHead,
+      options.payload,
+    ),
+  ).text();
+}
+/**
+ * A page's static shell, and what React needs to finish it per request.
+ *
+ * What `uf build` writes for a page it prerenders partially (`ppr`): the whole
+ * document React could render without a request, with each `<Suspense>`
+ * boundary that waited on one written as its fallback, and React's record of
+ * where those holes are.
+ */
+export type PrerenderedShell = {|
+  /**
+   * The document as far as a server sends it before it renders anything: the
+   * head, uf's tags in it, and every byte React finished. It stops where the
+   * request's part begins, which is before the closing tags.
+   */
+  readonly html: string,
+  /**
+   * What follows the request's part: the closing tags of a document uf wraps
+   * around the application. Empty for a document the application renders
+   * itself, because React's `resume` writes `</body></html>` for that one.
+   */
+  readonly close: string,
+  /** See [`Layout`]'s field of the same name. */
+  readonly rootDepth: number,
+  /**
+   * React's postponed state: which boundaries are holes and how to find them
+   * again. Plain JSON, which is what lets a build write it to a file and a
+   * server read it back. `null` when the prerender left nothing for the
+   * request, and `html` is then a whole document.
+   */
+  readonly postponed: mixed,
+|};
+/**
+ * Prerender `node` to a static shell, leaving whatever is still waiting when
+ * `settle` resolves as a hole.
+ *
+ * React's `prerender` with an abort. A boundary whose content is waiting on
+ * something when the render is stopped is written as its fallback, and React
+ * returns its postponed state beside the markup; [`resumeDocument`] hands that
+ * state back to React per request and streams only what was left.
+ *
+ * `settle` decides what is waiting, and it can only ever make a hole larger:
+ * stopped early, a boundary that would have finished is a hole instead, which
+ * the request then renders — slower, never wrong. The router waits until the
+ * payload it feeds this render has been read and every module it names has
+ * loaded, so what is left waiting is what was left out on purpose.
+ *
+ * Like [`prerenderDocument`], it is never given a nonce: what it writes is a
+ * file every request is sent.
+ */
+export async function prerenderShell(
+  node: React.Node,
+  options: {|
+    readonly shell: DocumentShell,
+    readonly onError: (error: mixed) => void,
+    readonly settle: () => Promise<void>,
+  |},
+): Promise<PrerenderedShell> {
+  const controller = new AbortController();
+  // The reason every hole is reported with when the render stops. Stopping is
+  // the point rather than a failure, so it is not passed on.
+  const stopped = new Error("@uniflowed/router: the static shell is complete");
+  const settings = {
+    onError: (error: mixed) => {
+      if (error !== stopped) options.onError(error);
+    },
+    signal: controller.signal,
+  };
+  const pending =
+    typeof ReactDOMStatic.prerenderToNodeStream === "function"
+      ? ReactDOMStatic.prerenderToNodeStream(node, settings)
+      : ReactDOMStatic.prerender(node, settings);
+  await options.settle();
+  controller.abort(stopped);
+  const result = await pending;
+  const layout: Layout = { rootDepth: 0 };
+  const text = await bodyOf(
+    assembled(preludeChunks(result.prelude), options.shell, undefined, layout),
+  ).text();
+  const postponed = result.postponed ?? null;
+  if (postponed == null) {
+    return { html: text, close: "", rootDepth: layout.rootDepth, postponed: null };
+  }
+  // A shell uf wrapped ends in uf's closing tags, which `resume` does not write;
+  // a document React wrote ends in its own, which `resume` writes again.
+  if (text.endsWith(options.shell.close)) {
+    return {
+      html: text.slice(0, text.length - options.shell.close.length),
+      close: options.shell.close,
+      rootDepth: layout.rootDepth,
+      postponed,
+    };
+  }
+  return {
+    html: text.replace(/<\/body>\s*<\/html>\s*$/i, ""),
+    close: "",
+    rootDepth: layout.rootDepth,
+    postponed,
+  };
+}
+/**
+ * A page's static shell, then what the request fills its holes with.
+ *
+ * The shell goes out as the first chunk, before React has rendered anything for
+ * this request — that is the whole of what partial prerendering buys, and it is
+ * why the shell is text the build wrote rather than a render. React's `resume`
+ * then renders the holes, and its output follows the shell unchanged: each
+ * hole's content in a hidden element and the script that moves it into place,
+ * which is what a streamed `<Suspense>` boundary always was.
+ *
+ * `payload` is the request's Flight payload, the one the holes were rendered
+ * from, and it is written into the document by [`interleaved`] under the same
+ * rules as a streamed render's. The shell ends between elements at the root's
+ * own level, so the payload may follow it as soon as it exists.
+ */
+export function resumeDocument(
+  node: React.Node,
+  shell: PrerenderedShell,
+  options: {|
+    readonly onError: (error: mixed) => void,
+    readonly payload: ReadableStream<Uint8Array>,
+    readonly nonce?: string | null,
+    readonly onStream?: (record: StreamRecord) => void,
+  |},
+): DocumentBody {
+  const controller = new AbortController();
+  // Begun now and awaited only after the shell has gone: the shell must not
+  // wait for anything React does for this request, and React must not wait
+  // for the shell to be read before it starts on the holes.
+  const resuming: Promise<ByteSource> = ReactDOMServer.resume(node, shell.postponed, {
+    onError: options.onError,
+    signal: controller.signal,
+    nonce: options.nonce ?? undefined,
+  });
+  // A resume that fails before its first byte fails the stream below, once it
+  // is read; this keeps the rejection from being reported as unhandled while
+  // the shell is still being written.
+  resuming.catch(() => {});
+  async function* chunks(): AsyncGenerator<string, void, void> {
+    yield shell.html;
+    yield* decoded(await resuming);
+    if (shell.close !== "") {
+      yield shell.close;
+    }
+  }
+  const layout: Layout = { rootDepth: shell.rootDepth };
+  return bodyOf(
+    outgoing(interleaved(chunks(), options.payload, options.nonce, layout), options.onStream),
+    () => {
+      controller.abort();
+    },
+  );
+}
+/**
+ * What [`assembled`] learns about a document that [`interleaved`] needs.
+ *
+ * Which shape a document has is decided on its opening bytes, inside
+ * `assembled`, and `interleaved` reads that document's chunks — so by the time
+ * it has HTML to follow, the answer is here.
+ */
+type Layout = {|
+  /**
+   * How many elements are open inside `<body>` where React's root begins: none
+   * for a document React wrote, and uf's own container for one uf wraps.
+   */
+  rootDepth: number,
+|};
+/** [`assembled`] alone when there is no payload, and [`interleaved`] with one. */
+function withPayload(
+  chunks: AsyncGenerator<string, void, void>,
+  shell: DocumentShell,
+  transformHead: ?(html: string) => Promise<string>,
+  payload: ?ReadableStream<Uint8Array>,
+  nonce?: string | null,
+): AsyncGenerator<string, void, void> {
+  if (payload == null) {
+    return assembled(chunks, shell, transformHead ?? undefined);
+  }
+  const layout: Layout = { rootDepth: 0 };
+  return interleaved(
+    assembled(chunks, shell, transformHead ?? undefined, layout),
+    payload,
+    nonce,
+    layout,
+  );
+}
+/**
+ * A document's chunks, with the Flight payload it was rendered from written
+ * into it as it arrives.
+ *
+ * Six rules, and each is the answer to a way the obvious version is wrong.
+ *
+ * **Nothing before the head.** The first chunk this is handed is the whole
+ * opening of the document — `assembled` does not let one go until the head is
+ * complete — and a payload element written in front of it would sit before
+ * `<head>`, where the parser would open a body for it and every tag after it
+ * would land in the wrong element.
+ *
+ * **Written as soon as it exists.** A payload row usually exists before the
+ * HTML rendered from it — React's client reads the row, then the boundary
+ * renders — so waiting for the next HTML chunk would put the browser's copy
+ * behind the markup it hydrates. Each HTML chunk that ends between elements is
+ * followed by whatever payload is waiting, and a payload that arrives while the
+ * HTML is idle there is written then, without a chunk of HTML to follow.
+ *
+ * **Only between elements.** React hands its HTML on through a fixed-size
+ * buffer, so a chunk can end anywhere: inside a tag, an attribute's value, a
+ * comment, a character reference or an inline `<script>`. A payload element
+ * written after such a chunk is not an element. It is part of the attribute,
+ * the comment or the text it landed in, the browser never reads it, and React's
+ * client closes the payload with rows missing, which is the "Connection closed"
+ * a page reports instead of hydrating. So a waiting payload goes out only where
+ * the HTML written so far ends between elements, which [`advanced`] follows
+ * from chunk to chunk, and otherwise waits for the HTML that finishes what is
+ * open.
+ *
+ * **Only where React steps over it.** Between elements is where the *parser*
+ * keeps a payload element. React is stricter: hydrating, it steps over an
+ * element it did not render only among the children of its root and of
+ * `<html>`, `<head>` and `<body>`. Anywhere deeper the element is a child the
+ * tree has no fiber for, the hydration fails there, and React throws the
+ * server's markup away and renders the document again. A shell that is one
+ * large element — a frame around the page, all of it rendered on the server —
+ * is written in many pieces, several of which end between two of its children,
+ * and a payload that was already waiting used to go out at the first of them.
+ * So [`advanced`] also follows how many elements are open inside `<body>`, and
+ * a payload waits for the root's own level: between React's top-level
+ * elements, which is where every streamed segment is written anyway.
+ *
+ * **Outside replaceable boundaries.** Even between tags, a payload inside a
+ * Suspense fallback disappears when React reveals its content. A browser that
+ * loads the Flight reader afterwards then sees an incomplete stream. React's
+ * boundary comments keep those ranges closed to injection until their end.
+ *
+ * **`</body></html>` waits for the end of the payload.** The HTML can finish
+ * first — the last boundary's markup is rendered from rows that are already
+ * written — and a payload element after `</html>` is one the parser moves
+ * rather than one React expects. So the closing tags are held back, the rest of
+ * the payload and its end marker are written, and the tags go last. For a
+ * document uf wraps, the closing run is `</div></body></html>`, and only the
+ * part from `</body>` is held: the root element React hydrates must hold
+ * nothing React did not render.
+ *
+ * A consumer that stops early stops the payload too: the reader is cancelled
+ * in the `finally`, which is where `return()` on this generator lands.
+ */
+async function* interleaved(
+  chunks: AsyncGenerator<string, void, void>,
+  payload: ReadableStream<Uint8Array>,
+  nonce?: string | null,
+  layout?: Layout,
+): AsyncGenerator<string, void, void> {
+  const encoder = createChunkEncoder(nonce);
+  const reader = payload.getReader();
+  let written = "";
+  let ended = false;
+  let wake: ?() => void = null;
+  const ring = () => {
+    const resume = wake;
+    wake = null;
+    if (resume != null) {
+      resume();
+    }
+  };
+  const pumping = (async () => {
+    try {
+      while (true) {
+        const step = await reader.read();
+        if (step.done === true) {
+          break;
+        }
+        if (step.value != null) {
+          written += encoder.encode(step.value);
+          ring();
+        }
+      }
+    } catch {
+      // A payload that failed partway is still ended, with the end marker, so
+      // the browser's reader closes and React reports the rows it never got
+      // rather than waiting for them for as long as the page is open.
+    } finally {
+      written += encoder.end();
+      ended = true;
+      ring();
+    }
+  })();
+  // Nothing written yet, and nothing may go before the head.
+  let boundary: Boundary = NOTHING_WRITTEN;
+  let closing = "";
+  try {
+    let next = chunks.next();
+    while (true) {
+      if (boundary.safe && written !== "") {
+        const out = written;
+        written = "";
+        yield out;
+      }
+      const idle = new Promise<null>((resolve) => {
+        wake = () => resolve(null);
+      });
+      const outcome = await Promise.race([next, idle]);
+      if (outcome == null) {
+        continue;
+      }
+      if (outcome.done === true) {
+        break;
+      }
+      let text = outcome.value;
+      const close = text.search(/<\/body>\s*<\/html>\s*$/i);
+      if (close !== -1) {
+        closing = text.slice(close);
+        text = text.slice(0, close);
+      }
+      if (text !== "") {
+        yield text;
+        boundary = advanced(boundary, text, layout?.rootDepth ?? 0);
+      }
+      next = chunks.next();
+    }
+    while (!ended || written !== "") {
+      if (written !== "") {
+        const out = written;
+        written = "";
+        yield out;
+        continue;
+      }
+      await new Promise<void>((resolve) => {
+        wake = resolve;
+        if (ended || written !== "") {
+          ring();
+        }
+      });
+    }
+    await pumping;
+    yield closing;
+  } finally {
+    if (!ended) {
+      void reader.cancel();
+    }
+  }
+}
+/** Where the HTML written so far leaves the next payload element. */
+type Boundary = {|
+  /** Whether a payload element may be written now. */
+  readonly safe: boolean,
+  /** The `script` or `style` element the HTML is inside, if it is inside one. */
+  readonly rawText: string | null,
+  /** Suspense/Activity ranges React can replace before hydration starts. */
+  readonly replaceable: number,
+  /** A tag, or a comment, the HTML has started and not yet finished. */
+  readonly open: string,
+  /** How many elements are open inside `<body>`; `null` until it has opened. */
+  readonly depth: number | null,
+|};
+const NOTHING_WRITTEN: Boundary = {
+  safe: false,
+  rawText: null,
+  replaceable: 0,
+  open: "",
+  depth: null,
+};
+/** Elements with no closing tag, for markup whose `/>` React did not write. */
+const VOID_ELEMENTS: $ReadOnlySet<string> = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+/**
+ * `boundary`, once `html` has been written after it.
+ *
+ * A payload element may follow HTML that ends with a `>` outside a `<script>`
+ * and a `<style>`. The test can be that short because React wrote the HTML: it
+ * escapes `<` and `>` in text and in attribute values, so a `>` it wrote closes
+ * a tag or a comment, and HTML that ends any other way ends inside one, or
+ * inside a character reference or a run of text. What React does not escape is
+ * the content of an inline script or stylesheet, where a `>` is code, so an
+ * opening `<script>` or `<style>` is followed to its closing tag. A tag split
+ * across two chunks is carried in `open` and read whole with the next one.
+ *
+ * And it may follow only HTML that leaves `rootDepth` elements open inside
+ * `<body>`, or none: the children of React's root and of `<body>` are the ones
+ * hydration steps over. Every tag from `<body>` on is counted for that, React's
+ * void elements by the `/>` it writes them with. Markup React did not write —
+ * `dangerouslySetInnerHTML` — can leave a tag open that the parser would close,
+ * and the count then stays too deep for the rest of the document. That errs the
+ * safe way: the payload waits, and goes out before `</body>` as it always can.
+ */
+function advanced(boundary: Boundary, html: string, rootDepth: number): Boundary {
+  const text = boundary.open + html;
+  let rawText = boundary.rawText;
+  let replaceable = boundary.replaceable;
+  let depth = boundary.depth;
+  const tags = /<!--([\s\S]*?)-->|<(\/?)([a-z][^\s/>]*)[^>]*?(\/?)>/gi;
+  let tag = tags.exec(text);
+  while (tag != null) {
+    const comment = tag[1];
+    if (comment != null) {
+      if (rawText == null) {
+        if (/^[\$&][?!~]?$/.test(comment)) replaceable += 1;
+        else if (comment === "/$" || comment === "/&") replaceable = Math.max(0, replaceable - 1);
+      }
+    } else {
+      const name = tag[3].toLowerCase();
+      const closes = tag[2] === "/";
+      if (rawText != null) {
+        // Inside a script or a stylesheet a `<` is code, up to its own end tag.
+        if (closes && rawText === name) {
+          rawText = null;
+          if (depth != null) depth -= 1;
+        }
+      } else if (closes) {
+        if (depth != null) depth -= 1;
+      } else if (depth == null) {
+        if (name === "body") depth = 0;
+        else if (name === "script" || name === "style") rawText = name;
+      } else if (tag[4] !== "/" && !VOID_ELEMENTS.has(name)) {
+        depth += 1;
+        if (name === "script" || name === "style") rawText = name;
+      }
+    }
+    tag = tags.exec(text);
+  }
+  const start = text.lastIndexOf("<");
+  return {
+    safe:
+      rawText == null &&
+      replaceable === 0 &&
+      text.endsWith(">") &&
+      (depth === 0 || (depth != null && depth === rootDepth)),
+    rawText,
+    replaceable,
+    open: start > text.lastIndexOf(">") ? text.slice(start) : "",
+    depth,
+  };
 }
 /**