@uniflowed/router 0.0.0-alpha.45 → 0.0.0-alpha.47

package/action.js

@@ -87,6 +87,16 @@
 // all and falls through to the route handlers. The `415` answers a request
 // that claims to be an action, which is the only kind that reaches it.
 //
+// # After a deploy
+//
+// A reference carries its build's id, and a new build mints new ids, so a tab
+// left open across a deploy holds ids the live server has never heard of. The
+// call names the page's build in `uf-deployment`; a server on another build
+// answers `409` without running anything; and the reference then loads the
+// page's document again — a hard navigation onto the live build — instead of
+// throwing. The promise it returned never settles, because the page it was
+// returned to is being replaced. See `./internal/deployment.js`.
+//
 // # What Flow checks, and where
 //
 // Flow reads `app/_actions/clicks.js`, not the reference the bundler
@@ -111,6 +121,7 @@ import {
   decodeActionResult,
   encodeActionArguments,
 } from "./internal/action-wire.js";
+import { loadDocument, refusedAsAnotherDeployment, withDeployment } from "./internal/deployment.js";
 import { clearNavigationCache } from "./internal/navigation-cache.js";
 
 export type { ActionArgument, ActionValue } from "./internal/action-wire.js";
@@ -251,6 +262,9 @@ export function createServerReference(id: string, name: string): ServerActionFun
     // declines to track.
     const headers: { [string]: string } = { "content-type": ACTION_CONTENT_TYPE };
     headers[ACTION_HEADER] = id;
+    // Which build this page is, so a server on another build refuses the call
+    // rather than looking this id up in a table it was never in.
+    withDeployment(headers);
     const response = await fetch(currentUrl(), {
       method: "POST",
       // Stated rather than left to the default, because the default is what a
@@ -270,6 +284,15 @@ export function createServerReference(id: string, name: string): ServerActionFun
     // again. Whatever the status: an action that failed part-way may have
     // written before it failed. See `./internal/navigation-cache.js`.
     clearNavigationCache();
+    // The server is on another build: nothing ran, and nothing on this page
+    // can be called correctly any more. Load the page again, from the build
+    // that is live, and never settle — a rejection here would reach an error
+    // boundary for the moment before the document is replaced, and a result
+    // would be a lie. See `./internal/deployment.js`.
+    if (refusedAsAnotherDeployment(response)) {
+      loadDocument(currentUrl());
+      return new Promise<ActionValue | void>(() => {});
+    }
     if (!response.ok) {
       throw new ServerActionError(name, response.status);
     }

package/internal/deployment.js

@@ -0,0 +1,160 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: which build this page is, and what it does
+// when the server is on another one.
+//
+// A tab stays open across a deploy. The page in it was built by build N — its
+// action ids, its chunk names, its copy of React — and after build N+1 goes
+// live the server it talks to is N+1's. Three things can then go wrong, and
+// this module is the browser's half of the answer to each:
+//
+// 1. **An action call.** N's action ids name nothing in N+1 (an id is an HMAC
+//    over a per-build secret), so the call cannot be answered — and must not
+//    be answered by guessing. The call names its build in the
+//    [`DEPLOYMENT_HEADER`]; a server on another build answers `409` without
+//    running anything; and the reference makes a hard navigation instead of
+//    throwing, so the reader lands on N+1's page and presses the button again
+//    on a page whose ids are right.
+// 2. **A navigation.** N+1's payload names N+1's client chunks, and loading
+//    them into N's page would put a second React beside the first. A payload
+//    request names its build the same way and is refused the same way, and
+//    `./flight-browser.js` already turns any answer that is not a payload into
+//    a document load. A payload the build *prerendered* is a file, answered by
+//    a host that runs nothing, so the payload also says which build rendered
+//    it (`FlightRoot.deployment`), and the router loads the document instead
+//    of rendering one from another build ([`fromAnotherDeployment`]).
+// 3. **A chunk.** `uf build` keeps the previous build's hashed files in the
+//    output directory for one more build, so a lazy chunk of N's is still
+//    there while N+1 is live and the page keeps working. Past that window — or
+//    on a host that did not keep them — the `import()` fails, and a
+//    navigation whose module will not load becomes a document load of the
+//    same URL rather than an error page ([`isChunkLoadFailure`]).
+//
+// The id is `<meta name="uf:deployment">` in the document's head, which
+// `./shell.js` writes. `uf dev` writes none, and a page without one sends no
+// header and compares nothing: there is no other build to be skewed against.
+
+/** The request header a page names its build in, and a refusal names the server's in. */
+export const DEPLOYMENT_HEADER: string = "uf-deployment";
+
+/** The `<meta name>` the document carries the id under. */
+export const DEPLOYMENT_META: string = "uf:deployment";
+
+/**
+ * What this page has read, once.
+ *
+ * `undefined` is "not read yet"; `null` is "read, and there is none". Read
+ * before hydration by [`rememberDeployment`], because an application that owns
+ * `<html>` hands its head to React, and the id is a fact about the document
+ * that arrived rather than about whatever the head holds later.
+ */
+let remembered: string | null | void;
+
+/** The parts of a `Document` read here. */
+type HeadLike = interface {
+  readonly querySelector: (selector: string) => ?interface {
+    readonly getAttribute: (name: string) => ?string,
+  },
+};
+
+/**
+ * Read the page's build from its document and keep it.
+ *
+ * Called by both client entries before `hydrateRoot`, through
+ * `./prepare-document.js`.
+ */
+export function rememberDeployment(document: ?HeadLike): void {
+  const meta = document?.querySelector(`meta[name="${DEPLOYMENT_META}"]`);
+  const content = meta?.getAttribute("content");
+  remembered = content == null || content === "" ? null : content;
+}
+
+/** The build this page is, or `null` for a page that does not say. */
+export function currentDeployment(): string | null {
+  if (remembered === undefined) {
+    rememberDeployment(typeof window === "undefined" ? null : window.document);
+  }
+  return remembered ?? null;
+}
+
+/** Forget what was read; for a test that builds a second page in one process. */
+export function forgetDeployment(): void {
+  remembered = undefined;
+}
+
+/** Name this page's build on an outgoing request's headers, when it has one. */
+export function withDeployment(headers: { [string]: string }): { [string]: string } {
+  const deployment = currentDeployment();
+  if (deployment != null) {
+    headers[DEPLOYMENT_HEADER] = deployment;
+  }
+  return headers;
+}
+
+/**
+ * Whether `response` is a server on another build refusing this page.
+ *
+ * The status and the header together: a `409` alone is an application's own
+ * answer to something, and only a front door refusing a build names the build
+ * it *is* on.
+ */
+export function refusedAsAnotherDeployment(response: Response): boolean {
+  if (response.status !== 409) return false;
+  const serving = response.headers.get(DEPLOYMENT_HEADER);
+  return serving != null && serving !== currentDeployment();
+}
+
+/**
+ * Whether a payload was rendered by another build than this page's.
+ *
+ * Only when both say: a payload from a server with no id (`uf dev`) and a page
+ * with none are the same build as far as anyone can tell.
+ */
+export function fromAnotherDeployment(rendered: ?string): boolean {
+  const current = currentDeployment();
+  return current != null && rendered != null && rendered !== "" && rendered !== current;
+}
+
+/**
+ * Whether `error` is a module that could not be fetched, rather than one that
+ * threw while it ran.
+ *
+ * An `import()` of a file the server no longer has rejects with a `TypeError`
+ * whose message is the browser's own and differs per engine; these are the
+ * three that ship, plus Vite's own message for a stylesheet its preload could
+ * not load. A module that threw while evaluating rejects with whatever it
+ * threw, and is an error for the route's boundary to show — reloading the page
+ * would only throw it again.
+ */
+export function isChunkLoadFailure(error: mixed): boolean {
+  if (!(error instanceof Error)) return false;
+  const message = error.message;
+  return (
+    message.includes("Failed to fetch dynamically imported module") ||
+    message.includes("error loading dynamically imported module") ||
+    message.includes("Importing a module script failed") ||
+    message.includes("Unable to preload CSS")
+  );
+}
+
+/**
+ * Whether a route resolved to an error because one of its modules could not be
+ * fetched — `isChunkLoadFailure` applied to a resolution's error, which is where
+ * a navigation meets it. A route whose module threw is not one of these.
+ */
+export function failedOnAMissingChunk(
+  failed: ?{ readonly kind: string, readonly error?: mixed, ... },
+): boolean {
+  return failed?.kind === "thrown" && isChunkLoadFailure(failed.error);
+}
+
+/**
+ * Leave this page for `href` by loading its document.
+ *
+ * `assign` rather than the history API, because the point is to stop running
+ * this build's code: the document that arrives is the current build's, with
+ * the current build's scripts.
+ */
+export function loadDocument(href: string): void {
+  window.location.assign(href);
+}

package/internal/flight-browser.js

@@ -25,6 +25,7 @@
 
 import { createFromFetch, createFromReadableStream } from "react-server-dom-parcel/client.browser";
 
+import { withDeployment } from "./deployment.js";
 import { FLIGHT_CHUNK_ATTRIBUTE, flightChunkBytes } from "./flight-chunks.js";
 import {
   FLIGHT_CONTENT_TYPE,
@@ -196,7 +197,10 @@ export async function fetchFlight(
   // document load: too old a React is not a network failure, and a navigation
   // that quietly reloaded the page would hide it.
   requireServerComponentsReact(ENTRY);
-  const headers = new Headers({ accept: FLIGHT_CONTENT_TYPE });
+  // With the page's build, so a server on another one refuses the request
+  // rather than answering with a payload that names chunks this page does not
+  // have. The refusal is not a payload, so it becomes a document load below.
+  const headers = new Headers(withDeployment({ accept: FLIGHT_CONTENT_TYPE }));
   const interceptedFrom = options?.interceptedFrom;
   if (interceptedFrom != null) {
     headers.set(INTERCEPTED_FROM_HEADER, interceptedFrom);

package/internal/flight-rows.js

@@ -0,0 +1,135 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: a finished Flight payload, with the rows a
+// partial prerender left for the request taken out.
+//
+// While `uf build` prerenders a page's static shell, a read of the request
+// throws (`@uniflowed/server`'s `internal/partial.js` says why a throw), and
+// React's Flight renderer writes an error row where that part of the tree would
+// have been, carrying the digest the renderer's `onError` returned for it. Fed
+// to the HTML renderer as it is, each of those rows is an error, and a
+// `<Suspense>` boundary that meets an error in a prerender is written as one the
+// browser has to render — not as a hole a server can finish.
+//
+// So the rows go. A row that never arrives is a part of the tree React's Flight
+// client is still waiting for, and a boundary waiting on it when the prerender
+// is stopped is exactly what React leaves as a hole in the shell. Everything
+// else in the payload arrived, so everything else is rendered.
+//
+// # Reading the rows
+//
+// The wire format is React's, and this reads the framing of it and nothing
+// more, following the state machine in React's own client
+// (`react-server-dom-*/client`, `processBinaryChunk`): a row is a hexadecimal
+// id, a colon, and then either a tag with a hexadecimal length, a comma and
+// that many raw bytes — text and typed arrays, which may hold a newline — or
+// everything up to the next newline. Only error rows are ever parsed further,
+// and only as the JSON React wrote them.
+
+/** The tags whose row is a length and raw bytes rather than a line. */
+const SIZED: $ReadOnlySet<number> = new Set(
+  ["T", "A", "O", "o", "b", "U", "S", "s", "L", "l", "G", "g", "M", "m", "V"].map((tag) =>
+    tag.charCodeAt(0),
+  ),
+);
+
+const COLON = 0x3a;
+const COMMA = 0x2c;
+const NEWLINE = 0x0a;
+const ERROR_TAG = "E".charCodeAt(0);
+
+/** One row's place in the payload. */
+type Row = {| +start: number, +end: number, +tag: number, +body: number |};
+
+/**
+ * Every row of a finished payload, in order.
+ *
+ * A payload that ends partway through a row is not one React finished writing,
+ * and is returned whole as its last row rather than guessed at.
+ */
+function rowsOf(bytes: Uint8Array): Array<Row> {
+  const rows: Array<Row> = [];
+  let at = 0;
+  while (at < bytes.length) {
+    const start = at;
+    const colon = bytes.indexOf(COLON, at);
+    if (colon === -1) {
+      rows.push({ start, end: bytes.length, tag: 0, body: bytes.length });
+      break;
+    }
+    const tag = bytes[colon + 1];
+    if (SIZED.has(tag)) {
+      const comma = bytes.indexOf(COMMA, colon + 2);
+      if (comma === -1) {
+        rows.push({ start, end: bytes.length, tag: 0, body: bytes.length });
+        break;
+      }
+      const length = Number.parseInt(
+        new TextDecoder().decode(bytes.subarray(colon + 2, comma)),
+        16,
+      );
+      const end = Math.min(comma + 1 + length, bytes.length);
+      rows.push({ start, end, tag, body: comma + 1 });
+      at = end;
+      continue;
+    }
+    const newline = bytes.indexOf(NEWLINE, colon + 1);
+    const end = newline === -1 ? bytes.length : newline + 1;
+    // A tag is one upper-case letter, `#`, `r` or `x`; anything else is the
+    // first byte of a model row, which has no tag.
+    const tagged = (tag > 64 && tag < 91) || tag === 0x23 || tag === 0x72 || tag === 0x78;
+    rows.push({ start, end, tag: tagged ? tag : 0, body: tagged ? colon + 2 : colon + 1 });
+    at = end;
+  }
+  return rows;
+}
+
+/**
+ * `payload` without the error rows whose digest `left` recognises.
+ *
+ * Returns the payload itself, unchanged, when there is no such row.
+ */
+export function withoutErrorRows(
+  payload: Uint8Array,
+  left: (digest: string) => boolean,
+): {| +payload: Uint8Array, +removed: number |} {
+  const decoder = new TextDecoder();
+  const kept: Array<Uint8Array> = [];
+  let removed = 0;
+  let length = 0;
+  for (const row of rowsOf(payload)) {
+    if (
+      row.tag === ERROR_TAG &&
+      left(digestOf(decoder.decode(payload.subarray(row.body, row.end))))
+    ) {
+      removed += 1;
+      continue;
+    }
+    const bytes = payload.subarray(row.start, row.end);
+    kept.push(bytes);
+    length += bytes.byteLength;
+  }
+  if (removed === 0) {
+    return { payload, removed };
+  }
+  const joined = new Uint8Array(length);
+  let at = 0;
+  for (const bytes of kept) {
+    joined.set(bytes, at);
+    at += bytes.byteLength;
+  }
+  return { payload: joined, removed };
+}
+
+/** The digest an error row carries, or `""`. */
+function digestOf(json: string): string {
+  try {
+    const parsed: mixed = JSON.parse(json);
+    if (parsed != null && typeof parsed === "object" && typeof parsed.digest === "string") {
+      return parsed.digest;
+    }
+  } catch {
+    // Not React's JSON, so not a row this module took out.
+  }
+  return "";
+}

package/internal/flight-ssr.js

@@ -71,8 +71,21 @@ export function installServerModules(load: ClientModuleLoader): void {
   });
 }
 
-/** Read a payload into its root value, as React's client does in the browser. */
-export function readPayload(stream: ReadableStream<Uint8Array>): Promise<FlightRoot> {
+/**
+ * Read a payload into its root value, as React's client does in the browser.
+ *
+ * `partial` is for a payload that is missing rows on purpose: a static shell's,
+ * with the parts a partial prerender left for the request taken out
+ * (`./flight-rows.js`). React's client then keeps waiting on those parts once
+ * the stream has ended, rather than failing every one of them with
+ * "Connection closed", so the HTML renderer leaves each as a hole.
+ */
+export function readPayload(
+  stream: ReadableStream<Uint8Array>,
+  options?: {| +partial?: boolean |},
+): Promise<FlightRoot> {
   requireServerComponentsReact(ENTRY);
-  return createFromReadableStream(stream);
+  return options?.partial === true
+    ? createFromReadableStream(stream, { unstable_allowPartialStream: true })
+    : createFromReadableStream(stream);
 }

package/internal/flight.js

@@ -59,6 +59,15 @@ export type RouteState = {|
 export type FlightRoot = {|
   readonly route: RouteState,
   readonly tree: Node,
+  /**
+   * The build that rendered it, when the build has an id.
+   *
+   * In the payload rather than only in a response header, because the payload
+   * of a prerendered route is a file and a host that serves files runs nothing
+   * that could set one. A page on another build loads the document instead of
+   * rendering this; see `./deployment.js`.
+   */
+  readonly deployment?: string | null,
 |};
 
 /** The intercepted URL a Flight payload rendered, and the page it rendered over. */

package/internal/prepare-document.js

@@ -12,7 +12,12 @@
 // modules, and `hydrateFlight` in `../rsc-client.js`, for one React Server
 // Components rendered — so the code lives here rather than in either entry.
 
+import { rememberDeployment } from "./deployment.js";
+
 export function prepareDocumentForHydration(document: Document): void {
+  // Before React touches the head: which build this document is, read off the
+  // document that arrived. See `./deployment.js`.
+  rememberDeployment(document);
   const head = document.head;
   const envelope = head.querySelector('meta[name="uf:render"]');
   if (envelope != null && head.firstChild !== envelope) {

package/internal/runtime.js

@@ -86,6 +86,12 @@ import {
   routeState,
 } from "./flight.js";
 import { Head } from "./head.js";
+import {
+  failedOnAMissingChunk,
+  fromAnotherDeployment,
+  isChunkLoadFailure,
+  loadDocument,
+} from "./deployment.js";
 import { addressOf, applicationPathOf, canonicalAddress } from "./base-path.js";
 import {
   clearNavigationCache,
@@ -727,6 +733,17 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
       const nextResolved =
         (intercepting ? await resolveInterception(routeTable(), origin, next) : null) ??
         (await (routeNavigations.read(key) ?? keepRoute(key, resolveMatch(routeTable(), next))));
+      // A module that could not be fetched, rather than one that threw: the
+      // chunk is gone, which after a deploy means this page is a build the
+      // server no longer carries. The document is the live build's page for
+      // this URL, so that is what is loaded — an error boundary would be a page
+      // that works after a reload, reported as though it were broken. See
+      // `./deployment.js`.
+      if (failedOnAMissingChunk(nextResolved.error)) {
+        setPending(false);
+        loadDocument(target.href);
+        return;
+      }
       // An intercepted entry remembers where it was intercepted from, so back
       // and forward can put the page underneath under it again. Every other
       // entry is written the way it always was.
@@ -791,6 +808,13 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
       return undefined;
     }
     const arrive = (nextResolved: ResolvedRoute) => {
+      // A chunk this page's build had and the server no longer does; the
+      // history entry has already moved, so reloading loads its document. See
+      // `navigateTo` above.
+      if (failedOnAMissingChunk(nextResolved.error)) {
+        window.location.reload();
+        return;
+      }
       // The back button is a navigation, and a navigation that animates in
       // one direction and cuts in the other would read as a bug in the
       // animation rather than as a decision.
@@ -1029,6 +1053,15 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
       }
       const payload = fetched.root;
       const nextRoot = await payload;
+      // A payload another build rendered: a prerendered one, answered as a
+      // file by a host that runs nothing and so refused nothing. Its tree names
+      // that build's chunks, so it is not rendered here; the document is. See
+      // `./deployment.js`.
+      if (fromAnotherDeployment(nextRoot.deployment)) {
+        setPending(false);
+        loadDocument(target.href);
+        return;
+      }
       // The URL the payload came from, which is a redirect's target when the
       // route redirected: the history entry is where the visitor ended up.
       // In the trailing-slash policy's spelling: a payload URL names its
@@ -1065,6 +1098,13 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
       }
     } catch (error) {
       setPending(false);
+      // A client module the payload named could not be fetched: after a
+      // deploy, a chunk the server no longer has. The document for the URL is
+      // the live build's, so it is what the reader gets.
+      if (isChunkLoadFailure(error)) {
+        loadDocument(target.href);
+        return;
+      }
       throw error;
     }
   };
@@ -1105,6 +1145,10 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
           const payload = fetched.root;
           payload.then(
             (nextRoot) => {
+              if (fromAnotherDeployment(nextRoot.deployment)) {
+                window.location.reload();
+                return;
+              }
               withViewTransition(nextRoot.route.viewTransition, () => {
                 show(payload, nextRoot);
               });
@@ -1177,6 +1221,10 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
       }
       const payload = fetched.root;
       const nextRoot = await payload;
+      if (fromAnotherDeployment(nextRoot.deployment)) {
+        window.location.reload();
+        return;
+      }
       // No view transition: a refresh is the same URL rendered again. See
       // `ModuleRouter`'s refresh.
       startTransition(() => {

package/internal/shell.js

@@ -13,6 +13,7 @@
 
 import type { PrerenderResult, RenderAssets, RenderResult } from "../server.js";
 import { addressOf } from "./base-path.js";
+import { DEPLOYMENT_META } from "./deployment.js";
 import { ROOT_ID } from "./document.js";
 import type { RedirectError } from "./routing.js";
 import { type DocumentShell, bodyOfText } from "./stream.js";
@@ -90,6 +91,15 @@ export function shellFor(assets: RenderAssets, nonce?: string | null): DocumentS
 
 function headTags(assets: RenderAssets, nonce?: string | null): string {
   let tags = "";
+  // Which build this document is, first, because everything after it is a URL
+  // that build wrote. The browser reads it once and names it on every action
+  // call and payload request, so a server on another build can refuse rather
+  // than answer with ids and chunks this page does not have. See
+  // `./deployment.js`.
+  const deployment = assets.deployment;
+  if (deployment != null && deployment !== "") {
+    tags += `<meta name="${DEPLOYMENT_META}" content="${escapeAttribute(deployment)}">`;
+  }
   for (const href of assets.styles) {
     tags += `<link rel="stylesheet" href="${escapeAttribute(href)}">`;
   }

package/internal/stream.js

@@ -882,6 +882,161 @@ export async function prerenderDocument(node: React.Node, options: RenderOptions
   ).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.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.45",
+  "version": "0.0.0-alpha.47",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -71,7 +71,7 @@
     }
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.45",
-    "@uniflowed/server": "0.0.0-alpha.45"
+    "@uniflowed/hooks": "0.0.0-alpha.47",
+    "@uniflowed/server": "0.0.0-alpha.47"
   }
 }

package/rsc-ssr.js

@@ -22,6 +22,7 @@
 import * as React from "react";
 
 import { addressOf } from "./internal/base-path.js";
+import { withoutErrorRows } from "./internal/flight-rows.js";
 import {
   type ClientModuleLoader,
   installServerModules,
@@ -32,10 +33,22 @@ import { type StreamRecord, streamReporter } from "./internal/inspector.js";
 import { requireServerComponentsReact } from "./internal/react-version.js";
 import { RedirectError } from "./internal/routing.js";
 import type { AppProps } from "./internal/runtime.js";
-import { currentNonce } from "@uniflowed/server/host";
+import {
+  currentNonce,
+  isPostponedRead,
+  newPartialPrerender,
+  runPartialPrerender,
+} from "@uniflowed/server/host";
 
 import { redirectDocument, redirectResult, shellFor } from "./internal/shell.js";
-import { type DocumentBody, prerenderDocument, renderDocument } from "./internal/stream.js";
+import {
+  type DocumentBody,
+  type PrerenderedShell,
+  prerenderDocument,
+  prerenderShell,
+  renderDocument,
+  resumeDocument,
+} from "./internal/stream.js";
 import type { FlightRenderer } from "./rsc.js";
 import type {
   FlightResponse,
@@ -233,22 +246,34 @@ export function createDocumentRenderer(options: DocumentRendererOptions): Render
   ): Promise<PrerenderResult> {
     const report = settings?.onError ?? (() => {});
     const ledger = createErrorLedger();
+    // A read of the request, while the build may leave it for the request, is
+    // not an exception to report: it is how the build finds the holes. Its row
+    // carries a digest of its own, so the HTML renderer's copy of it is known
+    // too, and `./internal/flight-rows.js` can take the row out.
+    const partial = settings?.partial === true ? newPartialPrerender() : null;
+    let postponedRows = 0;
     // The Flight renderer's copy of an exception is the one reported, because it
     // is the exception as thrown; the HTML renderer's copy of the same one is
     // recognised by its digest and dropped. See [`createErrorLedger`].
     const onServerError = (error: mixed): string => {
+      if (partial != null && isPostponedRead(error)) {
+        postponedRows += 1;
+        return `${POSTPONED_DIGEST}${postponedRows}`;
+      }
       report(error);
       return ledger.record(error);
     };
     const onHtmlError = (error: mixed) => {
-      if (!ledger.isCopy(error)) {
+      if (!ledger.isCopy(error) && !isPostponedCopy(error)) {
         report(error);
       }
     };
 
     // `defer: false`, for the reason [`createRenderer`]'s prerender passes it:
     // a file has no fallback to show first.
-    const rendered = await renderFlight(url, { defer: false, onError: onServerError });
+    const flightOf = () => renderFlight(url, { defer: false, onError: onServerError });
+    const rendered =
+      partial == null ? await flightOf() : await runPartialPrerender(partial, flightOf);
     if (rendered.kind === "redirect") {
       return redirectResult(
         redirectDocument(new RedirectError(rendered.location, rendered.status === 308)),
@@ -264,8 +289,22 @@ export function createDocumentRenderer(options: DocumentRendererOptions): Render
       // fails the stream itself, and that is this route's failure like any
       // other.
       payload = await bytesOf(rendered.stream);
+      // A read made before anything rendered — in a loader — has no boundary
+      // around it at all.
+      if (partial != null && isPostponedRead(failure)) {
+        throw readOutsideSuspense(url, partial.reads);
+      }
+      if (partial != null && partial.reads.length > 0 && failure == null) {
+        const shell = await partialDocumentOf(payload, url, assets, onHtmlError, partial.reads);
+        if (shell != null) {
+          return { status, html: shell.html, error: undefined, shell };
+        }
+      }
       html = await staticDocumentOf(payload, url, assets, onHtmlError);
     } catch (error) {
+      if (error instanceof ReadOutsideSuspenseError) {
+        throw error;
+      }
       const cause = ledger.originalOf(error);
       if (cause instanceof RedirectError) {
         return redirectResult(redirectDocument(cause));
@@ -296,6 +335,104 @@ export function createDocumentRenderer(options: DocumentRendererOptions): Render
     return { status, html, error: failure, payload };
   }
 
+  /**
+   * A page's static shell, for a payload whose render read the request.
+   *
+   * Two renders of the same payload. The first is the whole document, with an
+   * error where each read was, and it is there to prove one thing: that every
+   * read sits inside a `<Suspense>` boundary. A read outside one fails the
+   * shell itself, and the page is refused naming what it read, because a shell
+   * that has to wait for the request is not a shell. It also loads every client
+   * module the payload names, so the second render waits on nothing but the
+   * request.
+   *
+   * The second is the shell: the same payload with the rows the reads produced
+   * taken out, rendered until it has done everything it can and then stopped,
+   * so each boundary that is still waiting on one of those rows is a hole. It is
+   * `null` when that left no hole — a read whose result the page never rendered
+   * — and the page is then the plain document the first render already was.
+   */
+  async function partialDocumentOf(
+    payload: Uint8Array,
+    url: string,
+    assets: RenderAssets,
+    onError: (error: mixed) => void,
+    reads: $ReadOnlyArray<string>,
+  ): Promise<PrerenderedShell | null> {
+    try {
+      await staticDocumentOf(payload, url, assets, onError);
+    } catch (error) {
+      if (isPostponedCopy(error)) {
+        throw readOutsideSuspense(url, reads);
+      }
+      throw error;
+    }
+    const shellPayload = withoutErrorRows(payload, (digest) =>
+      digest.startsWith(POSTPONED_DIGEST),
+    ).payload;
+    const shell = await prerenderShell(
+      <App url={url} flight={readPayload(streamOf(shellPayload), { partial: true })} />,
+      { shell: shellFor(assets), onError, settle: settled },
+    );
+    return shell.postponed == null ? null : shell;
+  }
+
+  /**
+   * Answer `url` from its static shell: the shell now, and its holes as this
+   * request renders them.
+   *
+   * The route is resolved first, and that is the only thing the shell waits
+   * for: a redirect has to be the whole response, and a request that resolves
+   * to something other than the page the build prerendered — a `404`, an error
+   * boundary — is not answered with that page's shell. Either way it is
+   * rendered the way any other request is. Otherwise the whole route is
+   * rendered as Server Components for this request, the shell goes out, and
+   * React's `resume` renders the holes from the payload while the payload
+   * itself is written into the document for the browser to hydrate from.
+   *
+   * The payload is the request's whole one, not the shell's with the holes
+   * added: the browser hydrates the document from it, and the shell was
+   * rendered from the same modules without a request, so what it has in common
+   * with the shell is the same markup.
+   */
+  async function resume(
+    url: string,
+    assets: RenderAssets,
+    shell: PrerenderedShell,
+    settings?: RenderOptions,
+  ): Promise<RenderResult> {
+    const report = settings?.onError ?? (() => {});
+    const ledger = createErrorLedger();
+    const stop = new AbortController();
+    const rendered = await renderFlight(url, {
+      onError: (error: mixed) => {
+        report(error);
+        return ledger.record(error);
+      },
+      signal: stop.signal,
+    });
+    if (rendered.kind === "redirect") {
+      return redirectDocument(new RedirectError(rendered.location, rendered.status === 308));
+    }
+    if (rendered.status !== 200 || rendered.failure != null) {
+      stop.abort();
+      return render(url, assets, settings);
+    }
+    const send = settings?.onStream;
+    const [forHtml, forBrowser] = rendered.stream.tee();
+    const body = resumeDocument(<App url={url} flight={readPayload(forHtml)} />, shell, {
+      onError: (error: mixed) => {
+        if (!ledger.isCopy(error)) {
+          report(error);
+        }
+      },
+      payload: forBrowser,
+      nonce: currentNonce(),
+      onStream: send == null ? undefined : streamReporter(url, send),
+    });
+    return { status: 200, pipe: body.pipe, stream: body.stream, text: body.text };
+  }
+
   /** A finished document for a finished payload, with the payload written into it. */
   function staticDocumentOf(
     payload: Uint8Array,
@@ -342,7 +479,61 @@ export function createDocumentRenderer(options: DocumentRendererOptions): Render
     };
   }
 
-  return { render, prerender, flight };
+  return { render, prerender, flight, resume };
+}
+
+/**
+ * The digests a partial prerender gives the rows its reads of the request
+ * produced. React writes the digest into the row and onto the error its client
+ * rebuilds from it, which is how both copies are recognised.
+ */
+const POSTPONED_DIGEST = "uf:postponed:";
+
+/** Whether `error` is the HTML renderer's copy of a read left for the request. */
+function isPostponedCopy(error: mixed): boolean {
+  return digestOf(error)?.startsWith(POSTPONED_DIGEST) === true;
+}
+
+/**
+ * A page whose render read the request where no `<Suspense>` boundary could
+ * leave the read for later.
+ *
+ * Thrown rather than resolved to the error boundary, because it is not the
+ * page's failure to render — the page would render fine with a request — but
+ * the build's refusal to write it, and `uf build` names the route with it.
+ */
+class ReadOutsideSuspenseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReadOutsideSuspenseError";
+  }
+}
+
+function readOutsideSuspense(url: string, reads: $ReadOnlyArray<string>): ReadOutsideSuspenseError {
+  const named = [...new Set(reads)].map((read) => `${read}()`).join(", ");
+  return new ReadOutsideSuspenseError(
+    `${url} reads ${named} outside any <Suspense> boundary, so it has no static shell to ` +
+      "prerender. Move the part of the page that reads it inside a <Suspense> boundary, which " +
+      'leaves that part for the request, or export `dynamic = "force-dynamic"` from the page to ' +
+      "render all of it per request.",
+  );
+}
+
+/**
+ * Until the render reading a finished payload has done everything it can.
+ *
+ * Every row it will ever get is in memory and every module the payload names
+ * was loaded by the render before it, so what is left is React's own work,
+ * which it schedules as microtasks and a task to start. A few turns of the
+ * event loop is more than that takes; stopping early would only make a hole
+ * larger, never the document wrong. See `prerenderShell`.
+ */
+async function settled(): Promise<void> {
+  for (let turn = 0; turn < 4; turn += 1) {
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0);
+    });
+  }
 }
 
 /**

package/rsc.js

@@ -152,6 +152,13 @@ export function createFlightRenderer(options: {|
   readonly routes: RouteTable["routes"],
   readonly notFound: RouteTable["notFound"],
   readonly errors: RouteTable["errors"],
+  /**
+   * The build's deployment id, written into every payload's root so that a
+   * page on another build can tell — including from a payload that was
+   * prerendered into a file. `null` under `uf dev`. See
+   * `./internal/deployment.js`.
+   */
+  readonly deployment?: string | null,
 |}): FlightRenderer {
   // Before anything else: on a React older than 19.3 nothing below can render,
   // and React's Flight renderer would only say so from inside a render.
@@ -201,7 +208,7 @@ export function createFlightRenderer(options: {|
         ) : null}
       </>
     );
-    const root: FlightRoot = { route: state, tree };
+    const root: FlightRoot = { route: state, tree, deployment: options.deployment ?? null };
     const failure = renderFailure(route);
     if (failure != null) reportRequestError(failure, "render");
     const report = (error) => {

package/server.js

@@ -30,11 +30,14 @@ import * as React from "react";
 
 import {
   type DocumentBody,
+  type PrerenderedShell,
   type WritableLike,
   prerenderDocument,
   renderDocument,
 } from "./internal/stream.js";
 
+export type { PrerenderedShell } from "./internal/stream.js";
+
 import {
   type AppProps,
   type ResolvedRoute,
@@ -54,6 +57,12 @@ export type RenderAssets = {|
   readonly scripts: $ReadOnlyArray<string>,
   readonly styles: $ReadOnlyArray<string>,
   readonly preloads: $ReadOnlyArray<string>,
+  /**
+   * The build the document belongs to, written into its head as
+   * `<meta name="uf:deployment">`. Absent under `uf dev`, where there is no
+   * other build to be skewed against. See `./internal/deployment.js`.
+   */
+  readonly deployment?: string,
 |};
 
 /**
@@ -112,6 +121,17 @@ export type PrerenderResult = {|
    * navigation at all. Absent for a document rendered from its modules.
    */
   readonly payload?: Uint8Array,
+  /**
+   * The page's static shell, when the prerender was partial and the page read
+   * the request inside a `<Suspense>` boundary.
+   *
+   * `html` is then the shell's markup and not a document to write at the
+   * page's URL: a server answers the page by sending the shell and rendering
+   * the holes per request, through [`Renderer`]'s `resume`. No payload comes
+   * with it, because the browser hydrates from the request's. Only a renderer
+   * for React Server Components writes one.
+   */
+  readonly shell?: PrerenderedShell,
 |};
 
 /**
@@ -197,6 +217,19 @@ export type RenderOptions = {|
    * vocabulary of the report belongs on this side of that line.
    */
   readonly onStream?: (diagnostic: StreamDiagnostic) => void,
+  /**
+   * For `prerender` only: whether a read of the request may be left for the
+   * request rather than fail the page.
+   *
+   * `uf build` passes it when `app.rendering.modes` allows `ppr` and the build
+   * leaves a server behind. A page that reads `cookies()`, `headers()` or
+   * `draftMode()` inside a `<Suspense>` boundary is then written as a static
+   * shell with that boundary as a hole — [`PrerenderResult`]'s `shell` — and a
+   * read outside every boundary still fails the page, naming what it read.
+   * The renderer for React Server Components honours it; a route rendered from
+   * its modules (`app.rsc: false`) is prerendered whole or not at all.
+   */
+  readonly partial?: boolean,
 |};
 
 /** The two ids the server writes and the client reads. */
@@ -294,6 +327,17 @@ export type Renderer = {|
       readonly interceptedFrom?: string,
     |},
   ) => Promise<FlightResponse>,
+  /**
+   * A page `prerender` wrote as a static shell: the shell first, then its holes
+   * as this request renders them. Only a renderer for React Server Components
+   * has one, because only it writes a shell.
+   */
+  readonly resume?: (
+    url: string,
+    assets: RenderAssets,
+    shell: PrerenderedShell,
+    options?: RenderOptions,
+  ) => Promise<RenderResult>,
 |};
 
 export function createRenderer(options: {|