@uniflowed/router 0.1.0 → 0.3.0

package/internal/payload.js

@@ -241,8 +241,8 @@ function asThenable(value: mixed): Promise<mixed> | null {
   if (value == null || (typeof value !== "object" && typeof value !== "function")) {
     return null;
   }
-  const then: mixed = (value: $FlowFixMe).then;
-  return typeof then === "function" ? (value: $FlowFixMe) : null;
+  const then: mixed = (value as $FlowFixMe).then;
+  return typeof then === "function" ? (value as $FlowFixMe) : null;
 }
 
 /** Whether a string would be read as a reference and so has to be escaped. */
@@ -315,7 +315,7 @@ function needsEncoding(root: mixed, label: string): boolean {
       continue;
     }
     if (isPlainObject(value)) {
-      const source: { +[string]: mixed } = (value: $FlowFixMe);
+      const source: { readonly [string]: mixed } = value as $FlowFixMe;
       for (const key of Object.keys(source)) {
         stack.push({ value: source[key], path: `${path}.${key}`, depth: depth + 1 });
       }
@@ -381,7 +381,7 @@ export function encodePayload(root: mixed, label: string): EncodedPayload {
       continue;
     }
     if (Array.isArray(value)) {
-      const encoded: Array<mixed> = new Array(value.length).fill(null);
+      const encoded: Array<mixed> = new Array<mixed>(value.length).fill(null);
       emit(encoded);
       // Pushed in reverse so that popping visits index 0 first: the id a
       // promise is given has to follow the order the payload reads in.
@@ -403,7 +403,7 @@ export function encodePayload(root: mixed, label: string): EncodedPayload {
       emit(value);
       continue;
     }
-    const source: { +[string]: mixed } = (value: $FlowFixMe);
+    const source: { readonly [string]: mixed } = value as $FlowFixMe;
     const encoded: { [string]: mixed } = {};
     emit(encoded);
     const keys = Object.keys(source);
@@ -491,7 +491,7 @@ export function decodePayload(root: mixed, resolve: RowResolver, label: string):
       continue;
     }
     if (Array.isArray(value)) {
-      const rebuilt: Array<mixed> = new Array(value.length).fill(null);
+      const rebuilt: Array<mixed> = new Array<mixed>(value.length).fill(null);
       emit(rebuilt);
       for (let index = value.length - 1; index >= 0; index -= 1) {
         stack.push({
@@ -509,7 +509,7 @@ export function decodePayload(root: mixed, resolve: RowResolver, label: string):
       emit(value);
       continue;
     }
-    const source: { +[string]: mixed } = (value: $FlowFixMe);
+    const source: { readonly [string]: mixed } = value as $FlowFixMe;
     const rebuilt: { [string]: mixed } = {};
     emit(rebuilt);
     const keys = Object.keys(source);
@@ -553,7 +553,7 @@ function hasReference(root: mixed, label: string): boolean {
       continue;
     }
     if (isPlainObject(value)) {
-      const source: { +[string]: mixed } = (value: $FlowFixMe);
+      const source: { readonly [string]: mixed } = value as $FlowFixMe;
       for (const key of Object.keys(source)) {
         stack.push({ value: source[key], path: `${path}.${key}`, depth: depth + 1 });
       }
@@ -632,7 +632,13 @@ function parsePayloadRowId(digits: string): number | null {
  * only one of them.
  */
 export function payloadJson(value: mixed): string {
-  return JSON.stringify(value)
+  const text = JSON.stringify(value);
+  if (text === undefined) {
+    // `undefined`, a function or a symbol: nothing JSON can say. This threw
+    // before too, as a `TypeError` about `replace`; now it says what it is.
+    throw new TypeError("@uniflowed/router: a payload value has no JSON form");
+  }
+  return text
     .replace(/</g, "\\u003c")
     .replace(/\u2028/g, "\\u2028")
     .replace(/\u2029/g, "\\u2029");
@@ -660,9 +666,9 @@ export function parseRowMessage(text: string, id: number): PayloadRowMessage {
   if (!isPlainObject(parsed)) {
     throw new PayloadValueError(label, "is not a row message");
   }
-  const message: { +[string]: mixed } = (parsed: $FlowFixMe);
-  const hasValue = Object.prototype.hasOwnProperty.call(message, "value");
-  const hasError = Object.prototype.hasOwnProperty.call(message, "error");
+  const message: { readonly [string]: mixed } = parsed as $FlowFixMe;
+  const hasValue = Object.hasOwn(message, "value");
+  const hasError = Object.hasOwn(message, "error");
   if (hasValue === hasError) {
     throw new PayloadValueError(label, "must carry exactly one of `value` and `error`");
   }

package/internal/prepare-document.js

@@ -19,6 +19,12 @@ export function prepareDocumentForHydration(document: Document): void {
   // document that arrived. See `./deployment.js`.
   rememberDeployment(document);
   const head = document.head;
+  if (head == null) {
+    // Nothing a server wrote into a head to put right; the forms still are.
+    document.getElementById("_R_")?.remove();
+    normalizeReactFormActions(document);
+    return;
+  }
   const envelope = head.querySelector('meta[name="uf:render"]');
   if (envelope != null && head.firstChild !== envelope) {
     head.insertBefore(envelope, head.firstChild);

package/internal/resolve.js

@@ -639,7 +639,7 @@ export function loadOnce<T>(load: () => Promise<T>): Promise<T> {
     pending = load();
     moduleCache.set(load, pending);
   }
-  // $FlowFixMe[incompatible-return] the cache is keyed by the loader, whose result type it stores.
+  // $FlowFixMe[incompatible-type] the cache is keyed by the loader, whose result type it stores.
   return pending;
 }
 
@@ -755,9 +755,12 @@ async function resolveRoute(
         "client JavaScript, so the browser navigates to it rather than rendering it",
     );
   }
-  const [page, ...layouts] = await Promise.all([
+  // A pair rather than one spread array, so that the page stays a
+  // `PageModule` and the layouts `LayoutModule`s: `Promise.all` of a mixed
+  // list answers with the union of the two.
+  const [page, layouts] = await Promise.all([
     loadOnce(load),
-    ...matched.route.layouts.map((layout) => loadOnce(layout)),
+    Promise.all(matched.route.layouts.map((layout) => loadOnce(layout))),
   ]);
   // Started here and awaited at the end: the boundary's module does not depend
   // on the loader, so importing it alongside costs a navigation nothing. It
@@ -1460,11 +1463,11 @@ async function resolveNotFound(
 ): Promise<ResolvedRoute> {
   const record = nearestBoundary(table.notFound, pathname);
   const load = record?.page;
-  const [page, ...layouts] = await Promise.all([
+  const [page, layouts] = await Promise.all([
     load == null
       ? Promise.resolve<PageModule>({ default: DefaultNotFound, metadata: { title: "Not found" } })
       : loadOnce(load),
-    ...(record?.layouts ?? []).map((layout) => loadOnce(layout)),
+    Promise.all((record?.layouts ?? []).map((layout) => loadOnce(layout))),
   ]);
   const metadata = await resolveMetadata(page, layouts, {
     params: {},
@@ -1527,11 +1530,14 @@ async function resolveMetadata(
   }
   if (page.frontmatter != null) {
     const { title, description } = page.frontmatter;
-    merged = {
-      ...merged,
-      ...(title != null ? { title } : {}),
-      ...(description != null ? { description } : {}),
-    };
+    // One field at a time: spreading two conditional objects is a union per
+    // spread, and Flow refuses to multiply them out.
+    if (title != null) {
+      merged = { ...merged, title };
+    }
+    if (description != null) {
+      merged = { ...merged, description };
+    }
   }
   if (page.metadata != null) {
     take(page.metadata);
@@ -1587,7 +1593,7 @@ export function errorTitle(error: RouteError): string {
   return match (error) {
     {kind: "unauthorized"} => "Sign in required",
     {kind: "forbidden"} => "Not allowed",
-    {kind: "thrown"} => "Something went wrong",
+    {kind: "thrown", ...} => "Something went wrong",
   };
 }
 

package/internal/routing.js

@@ -150,7 +150,7 @@ export type RouteTable<
 type UnknownRouteRecord = RouteRecord<mixed, mixed, mixed, mixed, mixed>;
 
 /** A URL matched against a table. */
-export type RouteMatch<TRoute: { +path: string, ... } = UnknownRouteRecord> = {|
+export type RouteMatch<TRoute extends { readonly path: string, ... } = UnknownRouteRecord> = {|
   readonly route: TRoute,
   readonly params: RouteParams,
 |};
@@ -172,7 +172,7 @@ export function routeErrorStatus(error: RouteError): 401 | 403 | 500 {
   return match (error) {
     {kind: "unauthorized"} => 401,
     {kind: "forbidden"} => 403,
-    {kind: "thrown"} => 500,
+    {kind: "thrown", ...} => 500,
   };
 }
 
@@ -200,12 +200,77 @@ export class ForbiddenError extends Error {
   }
 }
 
-/** Thrown by `redirect()`; the renderer answers with a redirect. */
+/**
+ * The URL schemes a navigation never follows, because following one runs
+ * script in the page rather than loading one.
+ *
+ * `javascript:` is the reason. `location.assign("javascript:…")` and
+ * `location.replace("javascript:…")` execute it in the current document, with
+ * the page's origin and its cookies, so a router that hands a caller's string
+ * to either is a DOM XSS sink the moment that string comes from a query
+ * parameter: `redirect(searchParams.get("next"))` is the sign-in flow in half
+ * the applications ever written. React 19 refuses the same scheme in `href`
+ * for the same reason, and `Link` renders through that; this is the half of
+ * the router React never sees. `vbscript:` is the same thing in an older
+ * browser, and `data:` a document of the sender's choosing that browsers now
+ * refuse to navigate to at the top level anyway — refused here too, so the
+ * answer does not depend on which browser was asked.
+ */
+const SCRIPT_SCHEMES: $ReadOnlyArray<string> = ["javascript:", "vbscript:", "data:"];
+
+/**
+ * The scheme `to` would run as script when navigated to, or `null` when it is
+ * a URL a navigation may follow.
+ *
+ * Parsed with the WHATWG URL parser rather than compared as text, because the
+ * browser is what decides and it forgives a great deal: leading spaces and
+ * control characters are stripped, tabs and newlines anywhere are dropped, and
+ * the scheme is case-insensitive — ` JaVa\tScRiPt:` is `javascript:`. The base
+ * only resolves a relative path, which is never one of these.
+ */
+export function scriptSchemeOf(to: string): string | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(to, "http://uf.invalid/");
+  } catch {
+    return null;
+  }
+  return SCRIPT_SCHEMES.includes(parsed.protocol) ? parsed.protocol : null;
+}
+
+/**
+ * Throw unless `to` is a URL a navigation may follow.
+ *
+ * Named after the call that asked (`redirect()`, `router.push()`), so the
+ * stack a developer reads points at the line that built the URL. The URL
+ * itself is not repeated: it is often a value a visitor chose, and an error
+ * message is something applications log.
+ */
+export function refuseScriptUrl(to: string, caller: string): void {
+  const scheme = scriptSchemeOf(to);
+  if (scheme != null) {
+    throw new Error(
+      `@uniflowed/router: ${caller} refused a ${scheme} URL, which a browser would run as ` +
+        "script in this page rather than load. If the URL came from a query parameter, allow " +
+        "only paths on this site before navigating to it.",
+    );
+  }
+}
+
+/**
+ * Thrown by `redirect()`; the renderer answers with a redirect.
+ *
+ * Refuses a script URL when it is built (see [`refuseScriptUrl`]), so every
+ * place that follows one — the server's `Location`, the browser's
+ * `location.replace` in a single-page application, a form's `303` — is
+ * covered by one check rather than by one each.
+ */
 export class RedirectError extends Error {
   to: string;
   permanent: boolean;
 
   constructor(to: string, permanent: boolean) {
+    refuseScriptUrl(to, permanent ? "permanentRedirect()" : "redirect()");
     super(`redirect to ${to}`);
     this.name = "RedirectError";
     this.to = to;
@@ -241,9 +306,9 @@ function specificity(segments: $ReadOnlyArray<Segment>): number {
   let score = 0;
   for (const segment of segments) {
     score += match (segment) {
-      {kind: "static"} => 3,
-      {kind: "param"} => 2,
-      {kind: "catchAll"} => 1,
+      {kind: "static", ...} => 3,
+      {kind: "param", ...} => 2,
+      {kind: "catchAll", ...} => 1,
     };
   }
   return score;
@@ -338,12 +403,12 @@ function decodeSegment(segment: string): string {
 }
 
 /** Whether this table can render the route in the browser. */
-export function hasClientPage(route: { +page?: mixed, ... }): boolean {
+export function hasClientPage(route: { readonly page?: mixed, ... }): boolean {
   return route.page != null;
 }
 
 /** Match a pathname against the table, preferring the most specific route. */
-export function matchRoute<TRoute: { +path: string, ... }>(
+export function matchRoute<TRoute extends { readonly path: string, ... }>(
   routes: $ReadOnlyArray<TRoute>,
   pathname: string,
 ): ?RouteMatch<TRoute> {
@@ -356,7 +421,7 @@ export function matchRoute<TRoute: { +path: string, ... }>(
  * A slot is a second table matched against the same URL, and it has to be
  * matched by this function rather than by one of its own.
  */
-export function matchIn<TRoute: { +path: string, ... }>(
+export function matchIn<TRoute extends { readonly path: string, ... }>(
   routes: $ReadOnlyArray<TRoute>,
   pathname: string,
 ): ?RouteMatch<TRoute> {
@@ -389,8 +454,8 @@ function covers(segments: $ReadOnlyArray<Segment>, parts: $ReadOnlyArray<string>
   for (const segment of segments) {
     const next = match (segment) {
       {kind: "static", value: const value} => parts[index] === value ? index + 1 : -1,
-      {kind: "param"} => index < parts.length ? index + 1 : -1,
-      {kind: "catchAll"} => parts.length,
+      {kind: "param", ...} => index < parts.length ? index + 1 : -1,
+      {kind: "catchAll", ...} => parts.length,
     };
     if (next === -1) {
       return false;
@@ -401,7 +466,7 @@ function covers(segments: $ReadOnlyArray<Segment>, parts: $ReadOnlyArray<string>
 }
 
 /** The nearest boundary above `pathname`, or `null` when none covers it. */
-export function nearestBoundary<TBoundary: { readonly path: string, ... }>(
+export function nearestBoundary<TBoundary extends { readonly path: string, ... }>(
   boundaries: $ReadOnlyArray<TBoundary>,
   pathname: string,
 ): ?TBoundary {

package/internal/runtime.js

@@ -100,7 +100,13 @@ import {
   navigationKey,
   routeNavigations,
 } from "./navigation-cache.js";
-import { hasClientPage, matchRoute, nearestBoundary } from "./routing.js";
+import {
+  hasClientPage,
+  matchRoute,
+  nearestBoundary,
+  refuseScriptUrl,
+  scriptSchemeOf,
+} from "./routing.js";
 import type { RouteParams, SearchParams } from "./routing.js";
 import {
   beneath,
@@ -352,6 +358,70 @@ export type Router = {|
   readonly forward: () => void,
 |};
 
+/**
+ * The router of the `RouterProvider` on screen, or `null` when none is mounted.
+ *
+ * Module state, for the one caller that is not a component and still has to
+ * navigate: a server action reference whose action called `redirect()`
+ * (`../action.js`). A reference is a plain function that React calls from a
+ * form or a transition, with no hook to read the context through, and the
+ * navigation it owes is the one `router.push` would make — a client render
+ * under client navigation, a document load under document navigation.
+ */
+let mountedRouter: Router | null = null;
+
+/** Publish `router` as [`mountedRouter`] while its provider is mounted. */
+hook useMountedRouter(router: Router): void {
+  useEffect(() => {
+    mountedRouter = router;
+    return () => {
+      if (mountedRouter === router) {
+        mountedRouter = null;
+      }
+    };
+  });
+}
+
+/**
+ * Go where a server action's `redirect()` pointed.
+ *
+ * `location` is the address the action endpoint answered with — already under
+ * `app.router.basePath` for a path on this application — and `from` is the page
+ * the call was made from, which a relative `location` is resolved against: the
+ * visitor may have navigated while the action ran, and `redirect("next")` means
+ * next to the page that called it. A path on this origin is the mounted
+ * router's `push`, so the page underneath stays hydrated and a layout keeps its
+ * state, exactly as a `Link` to it would; another origin, or no router on
+ * screen, is the browser's document load. The promise settles when the
+ * navigation has, so a `useActionState` that awaited the action is not left
+ * pending on a page that has moved on.
+ *
+ * Only `http:` and `https:` are followed. `redirect()` refuses a script URL
+ * where it is built, but `location` arrived over the network, and
+ * `location.assign("javascript:…")` runs it in this page; a scheme this
+ * function would not follow is thrown as an error instead.
+ */
+export async function followActionRedirect(location: string, from: string): Promise<void> {
+  const target = new URL(location, new URL(from, window.location.href));
+  if (target.protocol !== "http:" && target.protocol !== "https:") {
+    throw new Error(
+      `@uniflowed/router: a server action redirected to a ${target.protocol} URL, which is not ` +
+        "followed. A redirect goes to an http or https address.",
+    );
+  }
+  const router = mountedRouter;
+  if (router == null || target.origin !== window.location.origin) {
+    window.location.assign(target.href);
+    return;
+  }
+  const applicationPath = applicationPathOf(target.pathname);
+  if (applicationPath == null) {
+    window.location.assign(target.href);
+    return;
+  }
+  await router.push(applicationPath + target.search + target.hash);
+}
+
 /** What `useRoute()` returns. */
 export type RouteInfo = {|
   readonly path: string,
@@ -679,6 +749,9 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
     if (!isBrowser()) {
       return;
     }
+    // Before anything else: every path below may end in `location.assign`,
+    // which runs a `javascript:` URL in this page. See `refuseScriptUrl`.
+    refuseScriptUrl(to, "a router navigation");
     const target = new URL(addressOf(to), window.location.href);
     // The application path the route table is asked about, and the address the
     // history entry keeps: one URL, with and without `app.router.basePath`.
@@ -973,6 +1046,8 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
     },
   };
 
+  useMountedRouter(router);
+
   const value: RouterState = {
     route: routeState(resolved),
     view: { kind: "modules", resolved },
@@ -1019,6 +1094,8 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
     if (!isBrowser()) {
       return;
     }
+    // As in `ModuleRouter`: a `javascript:` URL never reaches `location`.
+    refuseScriptUrl(to, "a router navigation");
     // A payload URL is an address, so it keeps the base path; the server takes
     // it off.
     const target = new URL(addressOf(to), window.location.href);
@@ -1243,6 +1320,8 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
     },
   };
 
+  useMountedRouter(router);
+
   const value: RouterState = {
     route: root.route,
     view: { kind: "flight", tree: root.tree },
@@ -1781,6 +1860,28 @@ export hook useLinkStatus(): {| readonly pending: boolean |} {
   return { pending: useContext(LinkStatusContext) };
 }
 
+/**
+ * The click a `Link` hands its `onClick`: React's synthetic mouse event, as
+ * much of it as a link reads.
+ *
+ * Flow's React library no longer declares `SyntheticMouseEvent`, so the name
+ * this prop used did not resolve and every handler passed to it was unchecked.
+ * Stated structurally, as `@uniflowed/ui`'s `PartEvent` is; the event React
+ * passes has every member below.
+ */
+export type LinkClickEvent = {
+  readonly defaultPrevented: boolean,
+  readonly button: number,
+  readonly altKey: boolean,
+  readonly ctrlKey: boolean,
+  readonly metaKey: boolean,
+  readonly shiftKey: boolean,
+  readonly currentTarget: mixed,
+  readonly preventDefault: () => mixed,
+  readonly stopPropagation: () => mixed,
+  ...
+};
+
 /**
  * A client-side navigation.
  *
@@ -1813,8 +1914,10 @@ export component Link(
   transition?: boolean = true,
   children?: React.Node,
   className?: string,
-  onClick?: (event: SyntheticMouseEvent<HTMLAnchorElement>) => mixed,
-  ...rest: { readonly [string]: mixed }
+  onClick?: (event: LinkClickEvent) => mixed,
+  // `key` named out of the indexer: React never hands a component its key, and
+  // the rest is spread onto the anchor, where a `mixed` key would not do.
+  ...rest: { readonly key?: empty, readonly [string]: mixed }
 ) {
   const { router, navigation } = useRouterState();
   const [linkPending, startLinkTransition] = useTransition();
@@ -1835,7 +1938,7 @@ export component Link(
     }
   });
 
-  const handleClick = (event: SyntheticMouseEvent<HTMLAnchorElement>) => {
+  const handleClick = (event: LinkClickEvent) => {
     if (onClick != null) {
       onClick(event);
     }
@@ -1857,9 +1960,14 @@ export component Link(
       try {
         await router.push(to, { replace, transition });
       } catch (error) {
-        // A failed navigation falls back to the browser doing it.
+        // A failed navigation falls back to the browser doing it — unless what
+        // failed was the router refusing a script URL, which the browser would
+        // run rather than load. `isExternal` above does not catch every
+        // spelling of one: ` javascript:` with a leading space is a path to it.
         console.error(error);
-        window.location.assign(addressOf(to));
+        if (scriptSchemeOf(to) == null) {
+          window.location.assign(addressOf(to));
+        }
       }
     });
   };

package/internal/shell.js

@@ -15,6 +15,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 FormState, formStateScript } from "./form-action.js";
 import type { RedirectError } from "./routing.js";
 import { type DocumentShell, bodyOfText } from "./stream.js";
 
@@ -79,8 +80,14 @@ export function redirectDocument(error: RedirectError): RenderResult {
  * carried two of them, one in each place, and only one was where a browser
  * looks. Hoisting the rendered one leaves the metadata with a single source.
  */
-export function shellFor(assets: RenderAssets, nonce?: string | null): DocumentShell {
-  const head = headTags(assets, nonce);
+export function shellFor(
+  assets: RenderAssets,
+  nonce?: string | null,
+  formState?: FormState,
+): DocumentShell {
+  // A postback's form state goes first, before the client entry that reads it:
+  // data rather than a script, so it needs no nonce. See `./form-action.js`.
+  const head = (formState == null ? "" : formStateScript(formState)) + headTags(assets, nonce);
   return {
     head,
     open: `<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">`,

package/internal/stream.js

@@ -44,6 +44,7 @@ import * as ReactDOMServer from "react-dom/server";
 import * as ReactDOMStatic from "react-dom/static";
 
 import { createChunkEncoder } from "./flight-chunks.js";
+import type { FormState } from "./form-action.js";
 import { type StreamRecord, inspected } from "./inspector.js";
 
 /**
@@ -99,12 +100,25 @@ type NodeDestination = {
 };
 
 /** The controller a `ReadableStream` source is handed. */
-type StreamController = {
-  readonly enqueue: (chunk: Uint8Array) => mixed,
-  readonly close: () => mixed,
+/**
+ * What `renderToPipeableStream` hands back, as much of it as is used here.
+ *
+ * Stated because the callbacks passed to the call use its result, and Flow
+ * cannot type a value whose definition depends on itself without being told.
+ */
+type PipeableStream = {
+  readonly pipe: (destination: NodeDestination) => mixed,
+  readonly abort: (reason?: mixed) => void,
   ...
 };
 
+type StreamController = interface {
+  // Methods, as a `ReadableStreamDefaultController`'s are: a method cannot be
+  // read off its object as a function-valued property.
+  enqueue(chunk: Uint8Array): mixed,
+  close(): mixed,
+};
+
 /**
  * A stream of bytes, as much of one as this module reads.
  *
@@ -112,13 +126,13 @@ type StreamController = {
  * result and `react-dom/static`'s `prelude` — and neither is typed by anything
  * uf can import, so the shape it is used through is stated here.
  */
-type ByteSource = {
-  readonly getReader: () => {
-    readonly read: () => Promise<{ readonly done?: boolean, readonly value?: Uint8Array, ... }>,
-    readonly releaseLock: () => mixed,
-    ...
+type ByteSource = interface {
+  // Methods, as a `ReadableStream`'s are: a class instance is not a subtype of
+  // an object type with function-valued properties.
+  getReader(): interface {
+    read(): Promise<{ readonly done?: boolean, readonly value?: Uint8Array, ... }>,
+    releaseLock(): mixed,
   },
-  ...
 };
 
 /** How the document is assembled around the app's markup. */
@@ -693,6 +707,14 @@ export type RenderOptions = {|
    * `prerenderDocument` is deliberately never given one. See its own paragraph.
    */
   readonly nonce?: string | null,
+  /**
+   * React's `formState`, for a document that answers a form posted before
+   * hydration: the `useActionState` that submitted starts from the action's
+   * result, and React marks it so the browser's hydration picks the same one.
+   * The shell carries the same value for `hydrateRoot`; see
+   * `./form-action.js`. Absent for every other render.
+   */
+  readonly formState?: FormState,
 |};
 
 /**
@@ -723,7 +745,7 @@ export function renderDocument(node: React.Node, options: RenderOptions): Promis
   const queue = new ChunkQueue();
   return new Promise((resolve, reject) => {
     if (typeof ReactDOMServer.renderToPipeableStream === "function") {
-      const { pipe, abort } = ReactDOMServer.renderToPipeableStream(node, {
+      const { pipe, abort }: PipeableStream = ReactDOMServer.renderToPipeableStream(node, {
         onShellReady() {
           pipe(queueDestination(queue));
           resolve(
@@ -751,6 +773,7 @@ export function renderDocument(node: React.Node, options: RenderOptions): Promis
         // 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,
+        formState: options.formState ?? null,
       });
       return;
     }
@@ -779,6 +802,7 @@ type ReadableStreamRenderer = (
     readonly onError: (error: mixed) => void,
     readonly signal: AbortSignal,
     readonly nonce?: string,
+    readonly formState?: FormState | null,
   |},
 ) => Promise<ByteSource>;
 
@@ -808,6 +832,7 @@ export function renderWithReadableStream(
     onError: options.onError,
     signal: controller.signal,
     nonce: options.nonce ?? undefined,
+    formState: options.formState ?? null,
   }).then((stream: ByteSource) =>
     bodyOf(
       outgoing(
@@ -1343,13 +1368,15 @@ function advanced(boundary: Boundary, html: string, rootDepth: number): Boundary
  *
  * `prerenderToNodeStream` hands back a Node `Readable` and `prerender` a web
  * `ReadableStream`, and which one a build has depends on which React entry
- * point exists — so the union is real rather than defensive, and `getReader`
- * is what tells them apart.
+ * point exists — so the union is real rather than defensive. Which one it is
+ * is asked of the class: a web stream is a `ReadableStream`, and a Node
+ * `Readable` is not. A test of a `getReader` property answered the same at run
+ * time, but a union of two structural types cannot be narrowed by one.
  */
 async function* preludeChunks(
-  prelude: ByteSource | AsyncIterable<string | Uint8Array>,
+  prelude: ReadableStream | AsyncIterable<string | Uint8Array>,
 ): AsyncGenerator<string, void, void> {
-  if (typeof prelude.getReader === "function") {
+  if (prelude instanceof ReadableStream) {
     yield* decoded(prelude);
     return;
   }