@uniflowed/router 0.1.0 → 0.2.0

package/action.js

@@ -66,26 +66,19 @@
 // still reads `submitNote`'s own declaration, so a form action whose first
 // parameter is not the state it was given `null` for is a `uf check` error.
 //
-// **This needs the page to be hydrated.** React's progressive enhancement —
-// the form that submits before its JavaScript has arrived — works through a
-// `$$FORM_ACTION` property that turns the submit into a *native* form post,
-// and a native form post is `multipart/form-data`: the content type this
-// endpoint refuses, deliberately, as one of the three things standing between
-// it and a cross-site call. Supporting the pre-hydration submit would mean
-// accepting that content type, so a reference carries no `$$FORM_ACTION`, and
-// React writes the form it writes for any client action —
-// `action="javascript:throw new Error('React form unexpectedly submitted.')"`
-// — so a submit before hydration throws in the page rather than posting
-// anywhere. Nothing reaches a server that was not meant to; what is missing is
-// the submit working at all. See ubugeeei-prod/uf#252.
-//
-// The refusal is why the property is withheld, not what would stop it: no
-// request is made, so nothing is refused. Nor would a native form post aimed
-// at a page by hand be refused as multipart — `createActionDispatcher` reads
-// the `uf-action` header before it looks at the method or the content type and
-// returns `null` when it is absent, so the request is not an action call at
-// 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.
+// **It works before the page has hydrated, too.** React's progressive
+// enhancement — the form that submits before its JavaScript has arrived — asks
+// the function for `$$FORM_ACTION` while rendering to HTML, and a reference
+// has one: `method="POST"`, `application/x-www-form-urlencoded`, and hidden
+// fields naming the action and carrying its bound arguments. The server
+// renders with the real function, which `@uniflowed/vite` gives the same
+// property through `registerServerAction` below, so the markup is the same
+// whichever side wrote it. A native post is not the JSON call: it is a
+// separate door in `./internal/action-endpoint.js`, which accepts only that
+// content type, only from the page's own origin, and only with the fields
+// `./internal/form-action.js` writes. `useActionState` works there as well
+// — the answer is the page rendered with the action's result as the hook's
+// state. See ubugeeei-prod/uf#1358.
 //
 // # After a deploy
 //
@@ -122,6 +115,7 @@ import {
   encodeActionArguments,
 } from "./internal/action-wire.js";
 import { loadDocument, refusedAsAnotherDeployment, withDeployment } from "./internal/deployment.js";
+import { withFormAction } from "./internal/form-action.js";
 import { clearNavigationCache } from "./internal/navigation-cache.js";
 
 export type { ActionArgument, ActionValue } from "./internal/action-wire.js";
@@ -248,11 +242,37 @@ export class ServerActionError extends Error {
  * outside the wire grammar throws an `ActionValueError` naming the argument's
  * position, at the call site, rather than becoming a `400` with nothing in it.
  *
- * It carries no `$$FORM_ACTION`, which is deliberate and is the header's last
- * section: React uses that property to make a form submit *natively* before
- * hydration, and a native submit is a content type this endpoint refuses.
+ * It carries `$$FORM_ACTION`, so a form bound to it is a real form before the
+ * page hydrates; see the header and `./internal/form-action.js`.
  */
 export function createServerReference(id: string, name: string): ServerActionFunction {
+  return withFormAction(callServerActionFor(id, name), id, []);
+}
+
+/**
+ * Give a server action, on the server, what its reference has in the browser.
+ *
+ * `@uniflowed/vite` calls this on every callable export of a `"use server"`
+ * module in the server graphs, with the id the build derived for it, so that a
+ * client component rendered to HTML writes a form that posts without
+ * JavaScript. It changes nothing about calling the function: the properties it
+ * defines are ones only React reads, and `bind` still binds. Anything that is
+ * not a function is returned untouched, because the RSC graph has already
+ * refused a `"use server"` export that is not one and this is not the place to
+ * say it twice.
+ */
+export function registerServerAction<T>(fn: T, id: string): T {
+  if (typeof fn !== "function") {
+    return fn;
+  }
+  // `typeof` refines `T` to a function whose parameters Flow cannot name, and
+  // `withFormAction` changes nothing about calling it; the cast says that.
+  withFormAction(fn as $FlowFixMe, id, []);
+  return fn;
+}
+
+/** The network call one reference makes. */
+function callServerActionFor(id: string, name: string): ServerActionFunction {
   return async function callServerAction(
     ...args: Array<ActionArgument>
   ): Promise<ActionValue | void> {

package/client.js

@@ -119,6 +119,8 @@ import { decodePayload } from "./internal/payload.js";
 import { createPayloadReader, domObserver } from "./internal/payload-rows.js";
 import { prepareDocumentForHydration } from "./internal/prepare-document.js";
 import { type TrailingSlash, addressOf, applicationPathOf } from "./internal/base-path.js";
+import { hydrationOptions } from "./internal/hydrate-options.js";
+import { readFormState } from "./internal/form-action.js";
 
 /**
  * Hydrate the current document.
@@ -215,7 +217,7 @@ export async function hydrate(options: {|
     hydrateRoot(
       container,
       options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
-      recovery == null ? undefined : { onRecoverableError: recovery },
+      hydrationOptions(recovery, readFormState(document)),
     );
     if (restoreDevHead != null) {
       setTimeout(restoreDevHead, 250);

package/internal/action-endpoint.js

@@ -55,16 +55,46 @@
 // header for what is excluded and why.
 //
 // A submitted form is inside that boundary and does not widen it: `<form
-// action={fn}>` reaches here as the same `application/json` body, with the
-// form's entries beside the values under a `form` key, bounded in count and in
-// field-name length and holding strings only. Nothing about it is multipart
-// and nothing about it is a content type a cross-origin `<form>` could
-// produce, so rule 4 is exactly as true of a form call as of any other. The
-// cost of keeping it that way is written down where it is paid — a form that
-// submits before its page has hydrated throws in the page rather than posting
-// anywhere, because React writes `action="javascript:throw …"` for a form
-// whose action carries no `$$FORM_ACTION`, and giving it one would mean
-// accepting a native form post here.
+// action={fn}>` on a hydrated page reaches here as the same `application/json`
+// body, with the form's entries beside the values under a `form` key, bounded
+// in count and in field-name length and holding strings only. Nothing about it
+// is multipart and nothing about it is a content type a cross-origin `<form>`
+// could produce, so rule 4 is exactly as true of a form call as of any other.
+//
+// # The second door: a form posted before the page hydrated
+//
+// React's progressive enhancement is a *native* form post, and a native post is
+// the one request rule 4 was written to keep out. So it is not let in through
+// that door. It has its own, narrower than the first, and it is worth being
+// exact about what it keeps of the six rules above:
+//
+// - **Rules 1, 2, 3, 5 and 6 hold unchanged.** The id selects a row and is
+//   compared the same way; a failed lookup is the same `404`; the bound
+//   arguments and the form cross through `decodeActionArguments`, so the
+//   grammar, the counts, the depth and the field limits are the JSON call's
+//   own; a throw is the same fixed `500`.
+// - **Rule 4 keeps one of its three guards.** A native post is a simple
+//   request, so there is no custom header and no JSON content type to lean on.
+//   What is left is `Origin`, which every browser sends on a `POST` and which
+//   must equal `Host` exactly as before — and `Sec-Fetch-Site`, which must say
+//   `same-origin` when the browser sends it. A cross-site form, a sandboxed
+//   frame (`Origin: null`) and a request with no `Origin` are `403`s.
+// - **It accepts one content type**, `application/x-www-form-urlencoded`, which
+//   is what `$$FORM_ACTION` asks React to write. Not multipart: a file cannot
+//   cross to an action, and a multipart parser is surface uf does not open.
+// - **It is recognised by its fields, read from a copy of the body.** A post
+//   that carries no `$uf_ref_` field is somebody else's — an ordinary form to a
+//   route handler — and is declined with `null` and its body untouched. So is
+//   one larger than an action accepts or not UTF-8, because it cannot be known
+//   to be an action post without reading it; it goes on to the route handlers,
+//   and a page answers a `POST` with a `404`.
+//
+// The answer is a document rather than JSON, because a person is looking at it:
+// a `303` back to the page for a plain form action, the page rendered again
+// with the action's result as the submitting `useActionState`'s state (the
+// host supplies that render as `postback`), or a `303` to wherever
+// `redirect()` pointed. See `./form-action.js` for the fields and
+// ubugeeei-prod/uf#1358.
 //
 // **6. Nothing about a failure goes back.** An action that throws is a `500`
 // with a fixed body; the exception goes to the host's error reporting. A
@@ -102,7 +132,30 @@ import {
   encodeActionResult,
   isActionId,
 } from "./action-wire.js";
+import { addressOf } from "./base-path.js";
+import {
+  FORM_ACTION_CONTENT_TYPE,
+  type FormPost,
+  type FormState,
+  readFormPost,
+} from "./form-action.js";
 import { requireRequest } from "./request.js";
+import { RedirectError } from "./routing.js";
+
+export type { FormState } from "./form-action.js";
+
+/**
+ * What a host gives the dispatcher beyond the request.
+ *
+ * `postback` renders the page the request is for, with a `useActionState`'s
+ * result as React's `formState`, and is how a form posted before hydration
+ * gets the page back with its answer in it. A host that supplies none still
+ * serves native posts: the answer is a `303` back to the page, which runs the
+ * action and loses only the state.
+ */
+export type ActionDispatchOptions = {|
+  readonly postback?: (formState: FormState) => Promise<Response>,
+|};
 
 /** A module holding server actions, as the generated table loads it. */
 export type ActionModule = { readonly [name: string]: mixed };
@@ -146,10 +199,13 @@ const ANSWER_HEADERS: { readonly [string]: string } = {
  */
 export function createActionDispatcher(options: {|
   readonly actions: $ReadOnlyArray<ActionRecord>,
-|}): (request: Request) => Promise<Response | null> {
+|}): (request: Request, settings?: ActionDispatchOptions) => Promise<Response | null> {
   const table = options.actions;
 
-  return async function callAction(request: Request): Promise<Response | null> {
+  return async function callAction(
+    request: Request,
+    settings?: ActionDispatchOptions,
+  ): Promise<Response | null> {
     // The host's half of the contract, checked rather than assumed, exactly as
     // `dispatch` and `runMiddleware` check it: an action that calls `cookies()`
     // has to answer about the request it is inside.
@@ -157,7 +213,9 @@ export function createActionDispatcher(options: {|
 
     const id = request.headers.get(ACTION_HEADER);
     if (id == null) {
-      return null;
+      // Not a JSON call. It may still be a form posted before its page
+      // hydrated, which is the second door in the header.
+      return nativeFormPost(table, request, settings?.postback);
     }
 
     // Cheapest and most protective first, and all of it before a byte of the
@@ -256,6 +314,151 @@ export function createActionDispatcher(options: {|
   };
 }
 
+/**
+ * Answer a form the browser posted natively, or decline with `null`.
+ *
+ * The header's second door. Declines everything that is not a urlencoded
+ * `POST` carrying a `$uf_ref_` field, and answers everything that is,
+ * refusals included — the same promise the JSON door makes, for the same
+ * reason.
+ */
+async function nativeFormPost(
+  table: $ReadOnlyArray<ActionRecord>,
+  request: Request,
+  postback: ?(formState: FormState) => Promise<Response>,
+): Promise<Response | null> {
+  if (request.method.toUpperCase() !== "POST") {
+    return null;
+  }
+  if (!isMedia(request.headers.get("content-type"), FORM_ACTION_CONTENT_TYPE)) {
+    return null;
+  }
+  // A copy, so that a form which turns out not to be an action post reaches the
+  // route handler with its body unread.
+  const text = await readBoundedText(request.clone(), MAX_ACTION_BODY_BYTES);
+  if (text == null) {
+    return null;
+  }
+  const post = readFormPost(new URLSearchParams(text));
+  if (post == null) {
+    return null;
+  }
+
+  // An action post from here on, and every outcome is an answer.
+  if (!sameOrigin(request) || !sameSiteFetch(request)) {
+    return refusal(403);
+  }
+
+  let args: Array<ActionArgument>;
+  let bound: number;
+  try {
+    ({ args, bound } = formArguments(post));
+  } catch (error) {
+    if (!(error instanceof ActionValueError)) {
+      throw error;
+    }
+    return refusal(400);
+  }
+
+  const id = post.id;
+  const record = id != null && isActionId(id) ? select(table, id) : null;
+  if (record == null) {
+    return refusal(404);
+  }
+
+  let action: mixed;
+  try {
+    const module = await record.load();
+    action = module[record.export];
+  } catch (error) {
+    report(record, error);
+    return refusal(500);
+  }
+  if (typeof action !== "function") {
+    report(record, new Error(`export \`${record.export}\` is not a function`));
+    return refusal(500);
+  }
+
+  const url = new URL(request.url);
+  const stateKey = post.stateKey;
+  return asResponder("a server action", async () => {
+    let result: mixed;
+    try {
+      const call = action as $FlowFixMe;
+      result = await traceRequestPhase("action", () => call(...args));
+    } catch (error) {
+      if (error instanceof RedirectError) {
+        return seeOther(addressOf(error.to));
+      }
+      report(record, error);
+      return refusal(500);
+    }
+    if (stateKey == null || postback == null) {
+      // Post/redirect/get: the page again, by a `GET`, so a reload does not
+      // submit the form a second time.
+      return seeOther(addressOf(url.pathname + url.search));
+    }
+    try {
+      // Held to the grammar for the reason the JSON door holds a result to it:
+      // this value is written into a document a browser parses.
+      encodeActionResult(result);
+    } catch (error) {
+      report(record, error);
+      return refusal(500);
+    }
+    // `bound - 1`: `useActionState` bound the previous state itself, and
+    // React compares the count of the bindings the *action* had.
+    return postback([result, stateKey, record.id, bound - 1]);
+  });
+}
+
+/**
+ * The arguments a native post calls its action with: the bound ones, then
+ * the form.
+ *
+ * Built into the JSON call's own envelope and decoded by the JSON call's own
+ * decoder, so there is one grammar and one set of limits, not a second one for
+ * forms that could drift from the first.
+ */
+function formArguments(post: FormPost): {|
+  readonly args: Array<ActionArgument>,
+  readonly bound: number,
+|} {
+  let bound: Array<ActionArgument> = [];
+  if (post.bound != null) {
+    bound = decodeActionArguments(post.bound);
+    if (bound.some((value) => value instanceof FormData)) {
+      throw new ActionValueError("the bound arguments", "carry a form");
+    }
+  }
+  const envelope = JSON.stringify({
+    args: [...bound, null],
+    form: { at: bound.length, entries: post.entries },
+  });
+  return { args: decodeActionArguments(envelope), bound: bound.length };
+}
+
+/**
+ * Whether the browser says the request came from this origin, when it says.
+ *
+ * `Sec-Fetch-Site` is a forbidden header name, so a page cannot set it; a
+ * browser that sends it and says anything but `same-origin` is describing a
+ * cross-site form. Absent is not a refusal on its own — older browsers do not
+ * send it, and `Origin` has already been required.
+ */
+function sameSiteFetch(request: Request): boolean {
+  const site = request.headers.get("sec-fetch-site");
+  return site == null || site === "same-origin";
+}
+
+/** A `303 See Other`, which a browser follows with a `GET`. */
+function seeOther(location: string): Response {
+  return new Response(null, {
+    status: 303,
+    headers: { location, "cache-control": "no-store" },
+  });
+}
+
 /**
  * The row with this id, or `null`, without saying which by taking longer.
  *
@@ -331,12 +534,17 @@ function sameOrigin(request: Request): boolean {
  * can.
  */
 function isJson(declared: string | null): boolean {
+  return isMedia(declared, ACTION_CONTENT_TYPE);
+}
+
+/** Whether `declared` is exactly the media type `expected`, parameters aside. */
+function isMedia(declared: string | null, expected: string): boolean {
   if (declared == null) {
     return false;
   }
   const semicolon = declared.indexOf(";");
   const media = (semicolon === -1 ? declared : declared.slice(0, semicolon)).trim().toLowerCase();
-  return media === ACTION_CONTENT_TYPE;
+  return media === expected;
 }
 
 /**

package/internal/form-action.js

@@ -0,0 +1,243 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: a server action as a form the browser can
+// submit before any JavaScript has run.
+//
+// React 19's contract for `<form action={serverFunction}>` is progressive
+// enhancement. While rendering to HTML, React asks the function for
+// `$$FORM_ACTION(prefix)` and writes what it answers into the markup — a
+// `method`, an `encType`, a hidden field named `name`, and one hidden field per
+// entry of `data` — so the form is a real form that posts to the page it is on.
+// A function without the property gets `action="javascript:throw …"` instead,
+// which is what every uf form got before ubugeeei-prod/uf#1358.
+//
+// Two functions carry the property: the reference the browser holds
+// (`createServerReference` in `../action.js`) and the real function the server
+// renders with (`registerServerAction`, which `@uniflowed/vite` calls on every
+// callable export of a `"use server"` module in the server graph). Both answer
+// with the same fields, from the code below, so the markup the server writes and
+// what a hydrated page would have written agree.
+//
+// # The fields
+//
+// React hands `$$FORM_ACTION` a prefix unique to the form in its render, and
+// the prefix is in every field name so that two forms — or a `<form>` and a
+// `<button formAction>` inside it — never read each other's fields:
+//
+// | Field | Value |
+// | --- | --- |
+// | `$uf_ref_<prefix>` | empty. The field that says *which* action this submit is for; on a `<button formAction>` it is the button's own name, so only the button that was pressed sends it |
+// | `$uf_id_<prefix>` | the action's id, the same 64 hexadecimal characters the JSON call carries in `uf-action` |
+// | `$uf_bound_<prefix>` | the bound arguments, as the JSON envelope `encodeActionArguments` writes, when there are any |
+//
+// `useActionState` adds React's own `$ACTION_KEY`, which names the hook that
+// submitted, so the answer can put the action's result back into the same hook.
+//
+// Every field is a string and every bound argument goes through the same
+// grammar as a JSON call: nothing new is allowed to cross by arriving as a form.
+// `./action-endpoint.js` is the other half, and its header says what a native
+// post is refused for.
+
+import { encodeActionArguments } from "./action-wire.js";
+
+/** The name of the field that says which action a submit is for. */
+export const FORM_REF_FIELD = "$uf_ref_";
+/** The action id, beside it. */
+export const FORM_ID_FIELD = "$uf_id_";
+/** The bound arguments, beside it. */
+export const FORM_BOUND_FIELD = "$uf_bound_";
+/** React's own: which `useActionState` submitted. */
+export const FORM_STATE_KEY_FIELD = "$ACTION_KEY";
+
+/**
+ * The only content type a native action post may have.
+ *
+ * `application/x-www-form-urlencoded` rather than `multipart/form-data`,
+ * because a server action refuses a file anyway and multipart parsing is a
+ * surface uf does not open for one (`docs/security.md`). `$$FORM_ACTION` says
+ * it explicitly, so React writes it on the form and on a submit button.
+ */
+export const FORM_ACTION_CONTENT_TYPE = "application/x-www-form-urlencoded";
+
+/** What `$$FORM_ACTION` answers, in the shape React reads. */
+export type FormActionFields = {|
+  readonly name: string,
+  readonly method: "POST",
+  readonly encType: string,
+  readonly data: FormData,
+|};
+
+/**
+ * What a `useActionState` postback leaves for the page it renders.
+ *
+ * React's `ReactFormState`: the action's result, the hook's key, the action's
+ * id, and how many bound arguments it had *besides* the state
+ * `useActionState` bound itself.
+ */
+export type FormState = [mixed, string, string, number];
+
+/**
+ * Make `fn` a server action a form can post to without JavaScript.
+ *
+ * Defines three non-enumerable properties on `fn` and returns it:
+ *
+ * - `$$FORM_ACTION(prefix)`, the fields above;
+ * - `$$IS_SIGNATURE_EQUAL(id, bound)`, which React asks while rendering a
+ *   postback's answer to decide whether a `useActionState` is the one that
+ *   submitted — the same action, bound the same number of times;
+ * - `bind`, which keeps both of those on the function it returns, with the
+ *   bound arguments recorded so they travel in the form.
+ *
+ * `call` is what the bound function runs: `fn` itself on the server, the
+ * network call in the browser.
+ */
+export function withFormAction<T extends (...args: $ReadOnlyArray<empty>) => mixed>(
+  fn: T,
+  id: string,
+  bound: $ReadOnlyArray<mixed>,
+): T {
+  const define = (name: string, value: mixed) => {
+    Object.defineProperty(fn, name, { value, configurable: true, writable: true });
+  };
+  define("$$FORM_ACTION", (prefix: string): FormActionFields => formFields(id, bound, prefix));
+  define(
+    "$$IS_SIGNATURE_EQUAL",
+    (referenceId: string, boundCount: number): boolean =>
+      referenceId === id && boundCount === bound.length,
+  );
+  // `Function.prototype.bind` itself, reached through a cast: Flow types
+  // `bind` per call site and has no type for the method taken off the
+  // prototype and applied to an arbitrary function.
+  const nativeBind: $FlowFixMe = Function.prototype.bind;
+  define("bind", function bindAction(thisArg: mixed, ...more: Array<mixed>) {
+    const next: T = nativeBind.call(fn, thisArg, ...more);
+    return withFormAction(next, id, [...bound, ...more]);
+  });
+  return fn;
+}
+
+/**
+ * The fields a form bound to this action is written with.
+ *
+ * Throws `ActionValueError` when a bound argument cannot cross, which React
+ * catches and reports as "Failed to serialize an action for progressive
+ * enhancement" before writing the form it would have written without this —
+ * so an unencodable state costs the pre-hydration submit and nothing else.
+ */
+export function formFields(
+  id: string,
+  bound: $ReadOnlyArray<mixed>,
+  prefix: string,
+): FormActionFields {
+  const data = new FormData();
+  data.append(`${FORM_ID_FIELD}${prefix}`, id);
+  if (bound.length > 0) {
+    data.append(`${FORM_BOUND_FIELD}${prefix}`, encodeActionArguments(bound));
+  }
+  return {
+    name: `${FORM_REF_FIELD}${prefix}`,
+    method: "POST",
+    encType: FORM_ACTION_CONTENT_TYPE,
+    data,
+  };
+}
+
+/** What a native post names, read off its fields. */
+export type FormPost = {|
+  /** The action id, as sent; checked by the caller. */
+  readonly id: string | null,
+  /** The bound-argument envelope, as sent, or `null` when there is none. */
+  readonly bound: string | null,
+  /** `$ACTION_KEY`, or `null` when no `useActionState` submitted. */
+  readonly stateKey: string | null,
+  /** Every other field, in order: what the action is handed as its form. */
+  readonly entries: Array<[string, string]>,
+|};
+
+/**
+ * Read a native post's fields, or `null` when it names no action at all.
+ *
+ * `null` is the caller's signal to decline, exactly as a JSON request with no
+ * `uf-action` header is: an ordinary form posted to a route handler must reach
+ * that handler. The last `$uf_ref_` field wins, because the browser writes a
+ * pressed button's name after the fields of the form around it, and a button's
+ * `formAction` is meant to override the form's `action`.
+ *
+ * Every field whose name uf or React owns is kept out of `entries`, including
+ * another prefix's, so the action receives the form the person filled in and
+ * nothing that says how it was wired.
+ */
+export function readFormPost(fields: URLSearchParams): FormPost | null {
+  let prefix: string | null = null;
+  for (const [name] of fields) {
+    if (name.startsWith(FORM_REF_FIELD)) {
+      prefix = name.slice(FORM_REF_FIELD.length);
+    }
+  }
+  if (prefix == null) {
+    return null;
+  }
+  const entries: Array<[string, string]> = [];
+  for (const [name, value] of fields) {
+    if (!isWiring(name)) {
+      entries.push([name, value]);
+    }
+  }
+  return {
+    id: fields.get(`${FORM_ID_FIELD}${prefix}`),
+    bound: fields.get(`${FORM_BOUND_FIELD}${prefix}`),
+    stateKey: fields.get(FORM_STATE_KEY_FIELD),
+    entries,
+  };
+}
+
+/** Whether a field is uf's or React's rather than the form's own. */
+function isWiring(name: string): boolean {
+  return name.startsWith("$uf_") || name.startsWith("$ACTION_");
+}
+
+/** The element a postback's form state is written into the document as. */
+export const FORM_STATE_ELEMENT_ID = "uf:form-state";
+
+/**
+ * The `<script>` that carries a postback's form state to `hydrateRoot`.
+ *
+ * `application/json`, so it is data and never executed — no nonce, and nothing
+ * a Content Security Policy has to admit. The result was already held to the
+ * wire grammar before it got here, so it is plain JSON; `<` is escaped so
+ * that no string in it can close the element.
+ */
+export function formStateScript(state: FormState): string {
+  const json = JSON.stringify(state).replace(/</g, "\\u003c");
+  return `<script type="application/json" id="${FORM_STATE_ELEMENT_ID}">${json}</script>`;
+}
+
+/**
+ * The form state a document carries, or `undefined`.
+ *
+ * Read by both hydrating entries before `hydrateRoot`. Anything malformed is
+ * `undefined` rather than an exception: the page still hydrates, and the
+ * `useActionState` that submitted starts from its initial state, which is what
+ * it would have done with JavaScript from the start.
+ */
+export function readFormState(document: Document): FormState | void {
+  const element = document.getElementById(FORM_STATE_ELEMENT_ID);
+  if (element == null) {
+    return undefined;
+  }
+  try {
+    const parsed: mixed = JSON.parse(element.textContent);
+    if (
+      Array.isArray(parsed) &&
+      parsed.length === 4 &&
+      typeof parsed[1] === "string" &&
+      typeof parsed[2] === "string" &&
+      typeof parsed[3] === "number"
+    ) {
+      return [parsed[0], parsed[1], parsed[2], parsed[3]];
+    }
+  } catch {
+    // Fall through: see above.
+  }
+  return undefined;
+}

package/internal/hydrate-options.js

@@ -0,0 +1,38 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: what both hydrating entries hand
+// `hydrateRoot` besides the tree.
+
+import type { FormState } from "./form-action.js";
+
+/** React's `onRecoverableError`, as the development report builds one. */
+type Recovery = (error: mixed, info: { componentStack?: ?string, ... }) => void;
+
+/** What this hands `hydrateRoot`. */
+type HydrationOptions = {| onRecoverableError?: Recovery, formState?: FormState |};
+
+/**
+ * `hydrateRoot`'s options: the development recovery handler, and a postback's
+ * form state.
+ *
+ * `formState` is React's own option. A page rendered in answer to a form posted
+ * before hydration was rendered with it, React marked the `useActionState` that
+ * submitted, and passing the same value here is how the browser's copy of that
+ * hook starts from the action's result instead of its initial state.
+ */
+export function hydrationOptions(
+  recovery: ?Recovery,
+  formState: FormState | void,
+): HydrationOptions | void {
+  if (recovery == null && formState == null) {
+    return undefined;
+  }
+  const options: HydrationOptions = {};
+  if (recovery != null) {
+    options.onRecoverableError = recovery;
+  }
+  if (formState != null) {
+    options.formState = formState;
+  }
+  return options;
+}

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";
 
 /**
@@ -693,6 +694,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,
 |};
 
 /**
@@ -751,6 +760,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 +789,7 @@ type ReadableStreamRenderer = (
     readonly onError: (error: mixed) => void,
     readonly signal: AbortSignal,
     readonly nonce?: string,
+    readonly formState?: FormState | null,
   |},
 ) => Promise<ByteSource>;
 
@@ -808,6 +819,7 @@ export function renderWithReadableStream(
     onError: options.onError,
     signal: controller.signal,
     nonce: options.nonce ?? undefined,
+    formState: options.formState ?? null,
   }).then((stream: ByteSource) =>
     bodyOf(
       outgoing(

package/middleware.js

@@ -60,6 +60,32 @@
 // middleware writes against `/pricing` holds for a client navigation too, and
 // a rewrite of the document becomes a rewrite of its payload.
 //
+// # A payload that renders over another page runs that page's guards too
+//
+// An intercepted navigation — a modal slot opening over the page it was clicked
+// from — asks for the payload of the URL it opens, and names the page it
+// renders over in `uf-intercepted-from`. The answer is *both* pages: the one
+// the URL names, in the slot, and the one the header names, underneath it,
+// with that page's loader run and its data in the payload.
+//
+// So the chain matched against the URL alone would be the wrong chain. A guard
+// on `/feed` holds for a request *for* `/feed`, and a payload for `/photo/1`
+// rendered over `/feed` is `/feed` as much as it is `/photo/1`. After the
+// ordinary chain has admitted the request, every middleware guarding the page
+// underneath runs as well — against a `GET` for that page, with its params and
+// query — including one that already ran for the URL, because a middleware
+// that decides by reading the pathname (one root `$middleware.js` guarding
+// several sections is a common shape) has only been asked about the other
+// path. If every one of them declines, the interception stands. If any
+// answers or rewrites, the page underneath is not this request's to render:
+// the header is taken off, and what renders is the page the URL names on its
+// own — exactly what a reader who could not open the page underneath would
+// see after a reload. The guard's own answer is not sent: the request was for
+// `/photo/1`, which that guard does not cover.
+//
+// The header is taken off whenever it is not a path on this origin, too, so
+// the renderer is never handed a value this module has not judged.
+//
 // # The request it runs inside
 //
 // The runner does not establish one. The host does — `beginRequest` in
@@ -96,7 +122,7 @@
 // `routesModuleSource` keeps the middleware table in an export the client
 // never imports, for the same reason it does that with route handlers.
 
-import { documentPathOf, flightUrl } from "./internal/flight.js";
+import { INTERCEPTED_FROM_HEADER, documentPathOf, flightUrl } from "./internal/flight.js";
 import { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
 
@@ -160,7 +186,10 @@ export type MiddlewareRecord = {|
  * caller's signal to carry on to the handler or the page. Returns a `Request`
  * when one of them rewrote: the same request at the destination, which the
  * caller carries on with instead — and which has already been past the
- * destination's middleware.
+ * destination's middleware. It also returns a `Request` when a payload request
+ * names a page to render over and that page's guards did not all admit it: the
+ * same request without `uf-intercepted-from`. The host must carry on with that
+ * request and read the header off nothing else, or the decision is undone.
  *
  * The runner is called once per request, above both the dispatcher and the
  * renderer, rather than from inside each of them. Putting the call inside
@@ -242,15 +271,99 @@ export function createMiddlewareRunner(options: {|
       return result;
     }
 
-    if (!rewritten) {
-      return null;
+    const admitted: Request | null = !rewritten
+      ? null
+      : document == null
+        ? seen
+        : requestAt(seen, new URL(flightUrl(url.pathname + url.search), url));
+
+    // A payload rendered over another page: that page's guards have their say
+    // too. See "A payload that renders over another page" above.
+    if (document != null && request.headers.has(INTERCEPTED_FROM_HEADER)) {
+      const carried = admitted ?? request;
+      const underneath = interceptionBase(request.headers.get(INTERCEPTED_FROM_HEADER), url);
+      if (underneath == null || !(await guardsAdmit(table, carried, underneath))) {
+        return withoutInterception(carried);
+      }
     }
-    return document == null
-      ? seen
-      : requestAt(seen, new URL(flightUrl(url.pathname + url.search), url));
+    return admitted;
   };
 }
 
+/**
+ * The page an intercepted payload names in its header, as a URL on `base`'s
+ * origin, or `null` when the value is not a path on this origin.
+ *
+ * The same shape the renderer accepts (`usableInterceptionBase` in `./rsc.js`,
+ * `interceptedFrom` in `@uniflowed/server`): a path, not a network-path
+ * reference, with any fragment dropped. Parsed rather than compared as text,
+ * so the pathname the guards are matched against is the one the renderer's
+ * route matching will read.
+ */
+function interceptionBase(header: string | null, base: URL): URL | null {
+  if (header == null || !header.startsWith("/") || header.startsWith("//")) {
+    return null;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(header, base);
+  } catch {
+    return null;
+  }
+  if (parsed.origin !== base.origin) {
+    return null;
+  }
+  parsed.hash = "";
+  return parsed;
+}
+
+/**
+ * Whether every middleware guarding `underneath` lets this request see it.
+ *
+ * Each one is asked exactly as it would be asked by a request for that page: a
+ * `GET` at its URL carrying this request's headers, with the params of the
+ * directory it guards and the page's query. All of them, root first, whether
+ * or not they already ran for the URL the request names — a guard that reads
+ * the pathname has so far only been asked about the other one.
+ *
+ * A `Response` is a refusal and so is a `rewrite()`: the page a guard would
+ * serve instead is not the page the header names, and the renderer has no way
+ * to render one under the other. Nothing either returns is sent; the caller
+ * only learns that the page underneath is not this request's to render.
+ */
+async function guardsAdmit(
+  table: $ReadOnlyArray<MiddlewareRecord>,
+  request: Request,
+  underneath: URL,
+): Promise<boolean> {
+  const asked = new Request(underneath.href, { method: "GET", headers: request.headers });
+  for (const record of table) {
+    const params = matchPrefix(record.path, underneath.pathname);
+    if (params == null) {
+      continue;
+    }
+    const middleware = pick(await record.load(), record.file);
+    const result = await middleware(asked, { params, searchParams: underneath.searchParams });
+    if (result != null) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * `request` with its `uf-intercepted-from` header taken off, so the renderer
+ * answers with the page its URL names and nothing underneath it.
+ *
+ * Only a payload request reaches here, and a payload is a `GET` or a `HEAD`,
+ * so there is no body to hand on.
+ */
+function withoutInterception(request: Request): Request {
+  const headers = new Headers(request.headers);
+  headers.delete(INTERCEPTED_FROM_HEADER);
+  return new Request(request.url, { method: request.method, headers, signal: request.signal });
+}
+
 /**
  * Where a rewrite goes, resolved against the URL the middleware was handed.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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.1.0",
-    "@uniflowed/server": "0.1.0"
+    "@uniflowed/hooks": "0.2.0",
+    "@uniflowed/server": "0.2.0"
   }
 }

package/rsc-client.js

@@ -41,6 +41,8 @@ import {
   installRouting,
   installStaleTime,
 } from "./internal/runtime.js";
+import { hydrationOptions } from "./internal/hydrate-options.js";
+import { readFormState } from "./internal/form-action.js";
 
 /**
  * Hydrate a document React Server Components rendered.
@@ -106,7 +108,7 @@ export async function hydrateFlight(options: {|
     hydrateRoot(
       container,
       options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
-      recovery == null ? undefined : { onRecoverableError: recovery },
+      hydrationOptions(recovery, readFormState(document)),
     );
     if (restoreDevHead != null) {
       setTimeout(restoreDevHead, 250);

package/rsc-ssr.js

@@ -40,6 +40,7 @@ import {
   runPartialPrerender,
 } from "@uniflowed/server/host";
 
+import type { FormState } from "./internal/form-action.js";
 import { redirectDocument, redirectResult, shellFor } from "./internal/shell.js";
 import {
   type DocumentBody,
@@ -113,6 +114,7 @@ export function createDocumentRenderer(options: DocumentRendererOptions): Render
       readonly onError: (error: mixed) => void,
       readonly transformHead?: (html: string) => Promise<string>,
       readonly onStream?: (record: StreamRecord) => void,
+      readonly formState?: FormState,
     |},
   ): Promise<DocumentBody> {
     const [forHtml, forBrowser] = stream.tee();
@@ -123,12 +125,13 @@ export function createDocumentRenderer(options: DocumentRendererOptions): Render
     const nonce = currentNonce();
     try {
       return await renderDocument(<App url={url} flight={readPayload(forHtml)} />, {
-        shell: shellFor(assets, nonce),
+        shell: shellFor(assets, nonce, settings.formState),
         onError: settings.onError,
         transformHead: settings.transformHead,
         onStream: settings.onStream,
         payload: forBrowser,
         nonce,
+        formState: settings.formState,
       });
     } catch (error) {
       void forBrowser.cancel();
@@ -189,6 +192,7 @@ export function createDocumentRenderer(options: DocumentRendererOptions): Render
         },
         transformHead,
         onStream,
+        formState: settings?.formState,
       });
       streaming = true;
       for (const error of held) {

package/server.js

@@ -48,6 +48,7 @@ import {
   resolveMatch,
 } from "./internal/runtime.js";
 
+import type { FormState } from "./internal/form-action.js";
 import { type StreamDiagnostic, streamReporter } from "./internal/inspector.js";
 
 import { redirectDocument, redirectResult, shellFor } from "./internal/shell.js";
@@ -198,6 +199,12 @@ export type RenderOptions = {|
    * it changes is a failing test rather than a surprise.
    */
   readonly transformHead?: (html: string) => Promise<string>,
+  /**
+   * React's `formState` for a page rendered in answer to a form posted before
+   * hydration; see `internal/form-action.js`. Only a host's `postback` passes
+   * one.
+   */
+  readonly formState?: FormState,
   /**
    * Told, in words, when a document streamed differently than it did last time.
    *
@@ -436,11 +443,12 @@ export function createRenderer(options: {|
     let body: DocumentBody;
     try {
       body = await renderDocument(<App url={url} initial={resolved} />, {
-        shell: shellFor(assets, nonce),
+        shell: shellFor(assets, nonce, settings?.formState),
         onError,
         transformHead: settings?.transformHead,
         onStream,
         nonce,
+        formState: settings?.formState,
       });
       streaming = true;
       // Recovered before the shell was ready: a `<Suspense>` boundary whose
@@ -469,11 +477,12 @@ export function createRenderer(options: {|
       // where somebody can fix it.
       streaming = true;
       body = await renderDocument(<App url={url} initial={resolved} />, {
-        shell: shellFor(assets, nonce),
+        shell: shellFor(assets, nonce, settings?.formState),
         onError,
         transformHead: settings?.transformHead,
         onStream,
         nonce,
+        formState: settings?.formState,
       });
     }