@uniflowed/router 0.0.0-alpha.14 → 0.0.0-alpha.16

package/action.js

@@ -32,6 +32,61 @@
 // above the page — and it is not a substitute for the action authorizing
 // itself; `internal/action-endpoint.js` says why in the paragraph that matters.
 //
+// # A form
+//
+// The same reference is what React 19's form APIs take, because a reference is
+// an ordinary async function and that is all they ask for:
+//
+//   // app/counter/_components/Note.js
+//   "use client";
+//   import { useActionState } from "@uniflowed/react";
+//   import { useFormStatus } from "react-dom";
+//   import { submitNote } from "../_actions/notes.js";
+//
+//   component Save() {
+//     const { pending } = useFormStatus();
+//     return <button disabled={pending}>Save</button>;
+//   }
+//
+//   component Note() {
+//     const [saved, save] = useActionState(submitNote, null);
+//     return (
+//       <form action={save}>
+//         <input name="note" />
+//         <Save />
+//         <output>{saved}</output>
+//       </form>
+//     );
+//   }
+//
+// `<form action={save}>` hands the reference a `FormData`, `useActionState`
+// hands it the previous state and then the `FormData`, and both cross under
+// the grammar in `internal/action-wire.js` — one form per call, beside the
+// values rather than inside one, entries of strings and nothing else. Flow
+// 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.
+//
 // # What Flow checks, and where
 //
 // Flow reads `app/_actions/clicks.js`, not the reference the bundler
@@ -51,12 +106,13 @@
 import {
   ACTION_CONTENT_TYPE,
   ACTION_HEADER,
+  type ActionArgument,
   type ActionValue,
   decodeActionResult,
   encodeActionArguments,
 } from "./internal/action-wire.js";
 
-export type { ActionValue } from "./internal/action-wire.js";
+export type { ActionArgument, ActionValue } from "./internal/action-wire.js";
 export {
   ACTION_CONTENT_TYPE,
   ACTION_HEADER,
@@ -65,17 +121,22 @@ export {
   MAX_ACTION_BODY_BYTES,
   MAX_ACTION_DEPTH,
   MAX_ACTION_VALUES,
+  MAX_FORM_ENTRIES,
+  MAX_FORM_NAME_LENGTH,
 } from "./internal/action-wire.js";
 
 /**
  * A function that can be a server action.
  *
- * Both halves of the signature are the wire grammar: an action is called with
- * values that can cross and answers with one that can. `void` is a result and
- * not an argument, because JSON has no `undefined` and an action declared to
- * take one would be taking something the caller cannot send.
+ * Both halves of the signature are the wire grammar, and they are not the same
+ * half: an action is called with values that can cross *or* the one form a
+ * submit produces, and answers with a value that can cross. `void` is a result
+ * and not an argument, because JSON has no `undefined` and an action declared
+ * to take one would be taking something the caller cannot send; a `FormData`
+ * is an argument and not a result, because a form is something a browser
+ * submits and not something a server answers with.
  */
-export type ServerActionFunction = (...args: Array<ActionValue>) => Promise<ActionValue | void>;
+export type ServerActionFunction = (...args: Array<ActionArgument>) => Promise<ActionValue | void>;
 
 /**
  * An action's arguments, held against what a wire can carry.
@@ -95,8 +156,38 @@ export type ServerActionFunction = (...args: Array<ActionValue>) => Promise<Acti
  *
  * `ServerActionName` is every action's name, so `ServerActionArgs` of it is
  * every action's argument list, and one line checks all of them.
+ *
+ * The bound is [`ActionArgument`] and not [`ActionValue`], which is the whole
+ * of what makes `<form action={fn}>` type-check: a form action's parameter is
+ * a `FormData`, and a `FormData` crosses as an argument and only as one.
+ *
+ * # What this does not catch, and why
+ *
+ * The bound is element-wise, so it holds each argument against the grammar and
+ * says nothing about the list as a whole. The wire has one rule that is about
+ * the list: a call carries at most one form, because the envelope names the
+ * form's position once. So `(a: FormData, b: FormData)` type-checks here and
+ * throws `ActionValueError` at `encodeActionArguments` — a rule enforced at
+ * run time that the types ought to have caught.
+ *
+ * Saying it in the type needs a walk over the tuple, and the walk is blocked by
+ * ubugeeei-prod/uf#300: a spread in a conditional type's tuple pattern binds
+ * `infer` as `unknown` and the rest as the whole array widened. The obvious
+ * recursion is not merely rejected, it quietly answers wrongly —
+ *
+ *   type NoForm<T> = T extends [] ? true
+ *     : T extends [infer H, ...infer R]
+ *       ? (H extends FormData ? false : NoForm<R>) : true;
+ *
+ * — gives `true` for `[string, FormData]`, because the spread pattern never
+ * matches and every tuple falls through to the last branch. A constraint built
+ * on that would be worse than none: it would report every signature as fine.
+ *
+ * `tests/type-tests/server-actions.js` pins the gap, so that whoever fixes
+ * #300 is told this is waiting on it. The run-time guard and its test are in
+ * `internal/action-wire.js` and `tests/library/server-actions.test.js`.
  */
-export type ActionArguments<TArgs extends $ReadOnlyArray<ActionValue>> = TArgs;
+export type ActionArguments<TArgs extends $ReadOnlyArray<ActionArgument>> = TArgs;
 
 /**
  * An action's result, held against the same grammar.
@@ -144,9 +235,15 @@ export class ServerActionError extends Error {
  * The returned function is `async` and refuses before it sends: an argument
  * 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.
  */
 export function createServerReference(id: string, name: string): ServerActionFunction {
-  return async function callServerAction(...args: Array<ActionValue>): Promise<ActionValue | void> {
+  return async function callServerAction(
+    ...args: Array<ActionArgument>
+  ): Promise<ActionValue | void> {
     const body = encodeActionArguments(args);
     // Built rather than written as a literal, because the header's name is a
     // constant and a computed key in an object literal is a shape Flow

package/client.js

@@ -18,6 +18,37 @@
 // Development only, and dynamically imported so a production bundle has no path
 // to it. See ubugeeei-prod/uf#508.
 //
+// # And whether React DevTools can see the page at all
+//
+// The other question only this module is in a position to ask.
+// `@uniflowed/vite` installs the hook DevTools attaches through, above every
+// module in the document; whether that worked *on this page* is a fact about a
+// running browser, and the line after hydration is where it can be read.
+// `internal/devtools.js` has the two findings and sends them to the same
+// terminal the hydration report goes to. See ubugeeei-prod/uf#503.
+//
+// # Strict Mode, in development, by default
+//
+// `uf dev` generates `strictMode: true` into `virtual:uf/client` and `uf build`
+// does not, so a development render is doubled and a visitor's is not. That is
+// React's own check for the thing it cannot check any other way: a component
+// whose render is not pure, and an effect whose cleanup does not undo its
+// setup, both behave correctly until the one production render that interleaves
+// with something — and Strict Mode makes them behave incorrectly at once, on
+// the machine of the person writing them.
+//
+// The wrapper is the argument to `hydrateRoot` rather than something inside
+// `<App>`, and that is load-bearing rather than tidy. React decides whether to
+// double-invoke a mount's effects at the *topmost fiber it is placing*: if that
+// fiber is not itself in Strict Mode, React stops there and never looks inside
+// it. A `<StrictMode>` further down still doubles the renders under it — that
+// comes from the fiber's own mode — and doubles no effect at all, so it would
+// have bought the half of the check that is easy to notice and silently lost
+// the half that finds the bug. It renders no element, so the hydrated tree is
+// unchanged and the markup comparison above is unaffected.
+// `app.react.strictMode: false` in `uf.config.js` turns it off. See
+// ubugeeei-prod/uf#516.
+//
 // # A route can decline to be hydrated
 //
 // uf's server-component analysis decides which routes have a `"use client"`
@@ -29,7 +60,7 @@
 // See ubugeeei-prod/uf#350.
 
 import * as React from "react";
-import { startTransition } from "react";
+import { StrictMode, startTransition } from "react";
 import { hydrateRoot } from "react-dom/client";
 
 import {
@@ -54,6 +85,7 @@ export async function hydrate(options: {|
   readonly routes: RouteTable["routes"],
   readonly notFound: RouteTable["notFound"],
   readonly errors: RouteTable["errors"],
+  readonly strictMode?: boolean,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -95,11 +127,28 @@ export async function hydrate(options: {|
     recovery = hydrationErrorHandler(container, captureServerMarkup(container), document);
   }
 
+  // `<StrictMode>` renders no element of its own, so the tree React hydrates
+  // against the server's markup is the same tree either way and the flag can
+  // be a development-only difference without being a hydration difference.
+  const tree = <App url={url} initial={resolved} />;
+
   startTransition(() => {
     hydrateRoot(
       container,
-      <App url={url} initial={resolved} />,
+      options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
       recovery == null ? undefined : { onRecoverableError: recovery },
     );
   });
+
+  // And, in development only, whether the panel a developer is about to open
+  // can see any of that. `react-dom` announced itself while it was being
+  // imported — long before this line — so the answer is already settled and
+  // this only reads it. Behind the same `import.meta.hot` gate as the
+  // hydration reporter, dynamically imported for the same reason: a production
+  // bundle has no path to the module rather than merely no reason to run it.
+  // See `./internal/devtools.js` and ubugeeei-prod/uf#503.
+  if (import.meta.hot != null) {
+    const { reportDevtools } = await import("./internal/devtools.js");
+    reportDevtools(window);
+  }
 }

package/index.js

@@ -56,6 +56,7 @@ export {
   RouteView,
   RouterProvider,
   UnauthorizedError,
+  buildRoute,
   forbidden,
   hasClientPage,
   matchRoute,

package/internal/action-endpoint.js

@@ -54,6 +54,18 @@
 // prototype keys, no constructor named by the payload. See that module's
 // 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.
+//
 // **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
 // message, a name or a stack in that response is an application's internals
@@ -81,7 +93,7 @@ import { asResponder } from "@uniflowed/server/host";
 import {
   ACTION_CONTENT_TYPE,
   ACTION_HEADER,
-  type ActionValue,
+  type ActionArgument,
   ActionValueError,
   MAX_ACTION_BODY_BYTES,
   decodeActionArguments,
@@ -163,7 +175,7 @@ export function createActionDispatcher(options: {|
       return refusal(413);
     }
 
-    let args: Array<ActionValue>;
+    let args: Array<ActionArgument>;
     try {
       args = decodeActionArguments(body);
     } catch (error) {
@@ -213,7 +225,7 @@ export function createActionDispatcher(options: {|
     return asResponder("a server action", async () => {
       let result: mixed;
       try {
-        // The build-time contract says this is `async (...ActionValue) => …`
+        // The build-time contract says this is `async (...ActionArgument) => …`
         // (`ServerActionBoundary` in `../action.js`), and Flow cannot read that
         // through a module loaded by a thunk. The arguments are the ones
         // `decodeActionArguments` produced, so what is unchecked here is the

package/internal/action-wire.js

@@ -10,7 +10,7 @@
 //
 // # The boundary
 //
-// **A server action's arguments are plain JSON data and nothing else.**
+// **A server action's arguments are plain JSON data, plus at most one form.**
 //
 // One JSON object, `{"args": [...]}`, at most `MAX_ACTION_BODY_BYTES` of valid
 // UTF-8, holding at most `MAX_ACTION_ARGUMENTS` values, nested at most
@@ -18,7 +18,8 @@
 // Each of those values is `null`, a boolean, a finite number, a string, an
 // array of them, or a plain object whose keys are ordinary strings. The result
 // travels back under exactly the same grammar, plus `undefined` for an action
-// that returns nothing.
+// that returns nothing — and with no form, because a form is something a
+// browser submits and not something a server answers with.
 //
 // Nothing in a payload can name a function, a module, a class, a prototype, a
 // React element, an id or a reference, and nothing in it is revived into an
@@ -27,6 +28,35 @@
 // `JSON.parse` would have let through — which is the whole of what a decoder
 // has to get right.
 //
+// # The one thing that is not a value: `<form action={fn}>`
+//
+// React 19 hands a form action a `FormData`, and `useActionState` hands it the
+// previous state and then a `FormData`. So one argument of a call may be a
+// form, and the envelope grows a second key to say which:
+//
+//   {"args": [null, null], "form": {"at": 1, "entries": [["note", "hi"]]}}
+//
+// It is written *beside* the values rather than inside one, and that placement
+// is the whole design. A tag in the value tree — `{"$formData": …}` — would be
+// a payload saying which constructor to call, which is the shape of every
+// deserialisation CVE and the thing the list below refuses on principle.
+// Outside the tree there is no tag: `checkActionValue` is unchanged and still
+// knows nothing but JSON data, `at` names a position and not a type, and the
+// slot it names must hold `null` so a sender cannot say two things about one
+// argument. At most one form crosses per call, it is never nested inside a
+// value, its entries are `[name, value]` pairs of strings, and the decoder's
+// only constructor is `FormData` — fixed here, never named by the payload.
+//
+// What that buys is `<form action={fn}>`, `useActionState` and `useFormStatus`
+// against a real endpoint. What it does not buy is a form that works before
+// hydration: React's progressive enhancement needs `$$FORM_ACTION` on the
+// reference, which makes the submit a *native* form post, and a native form
+// post is `multipart/form-data` — a content type this endpoint refuses on
+// purpose (see `./action-endpoint.js`, rule 4). Without it React writes the
+// form it writes for any client action, whose `action` is a `javascript:` URL
+// that throws, so such a submit does nothing rather than posting somewhere it
+// should not. That is still open; see ubugeeei-prod/uf#252.
+//
 // # What is deliberately absent, and why
 //
 // * **A reference format.** React's Flight payload can carry a reference to a
@@ -39,11 +69,11 @@
 //   tag naming a constructor is the oracle every deserialisation CVE is made
 //   of. An action that wants a date takes an ISO string and parses it, where
 //   the parse is the application's and is checked.
-// * **`FormData` and `<form action={fn}>`.** Multipart parsing is its own
-//   attack surface with its own bounds, and a form post is a *simple* CORS
-//   request — it reaches a server with the visitor's cookies and no preflight.
-//   Both are worth having and neither is worth having by accident; see the
-//   security note in `./action-endpoint.js`.
+// * **A file in a form.** A `File` entry is refused at the call site rather
+//   than encoded: bytes in this envelope would be base64 in a JSON string with
+//   no ceiling of their own, and an upload wants a content type, a streaming
+//   read and a size limit that are not this module's. Multipart parsing is its
+//   own attack surface and is still deliberately absent.
 // * **Cycles and shared references.** A value that refers to itself is
 //   rejected rather than encoded, because the alternative is a marker in the
 //   payload that says "this is the object you saw earlier", which is a
@@ -87,6 +117,26 @@ export const MAX_ACTION_DEPTH: number = 24;
 /** Most values, of any kind, one payload may hold. */
 export const MAX_ACTION_VALUES: number = 10000;
 
+/**
+ * Most fields one submitted form may carry.
+ *
+ * A ceiling on the *count* rather than on the bytes, because the bytes already
+ * have one: the whole body is bounded by `MAX_ACTION_BODY_BYTES` before a
+ * character of it is parsed. What this bounds is the number of `append` calls
+ * a sender can make the decoder do, and the size of the multimap they build.
+ * A form with more than 256 controls is a form that wants a different shape.
+ */
+export const MAX_FORM_ENTRIES: number = 256;
+
+/**
+ * Longest field name one form entry may have.
+ *
+ * A name is an HTML `name` attribute — `email`, `items[3][quantity]` — so this
+ * is generous by two orders of magnitude for anything a document declares, and
+ * it stops a body's whole byte budget being spent on one key.
+ */
+export const MAX_FORM_NAME_LENGTH: number = 128;
+
 /**
  * Everything that may cross the wire.
  *
@@ -103,6 +153,18 @@ export type ActionValue =
   | $ReadOnlyArray<ActionValue>
   | { readonly [string]: ActionValue };
 
+/**
+ * Everything an *argument* may be: a value, or the one form.
+ *
+ * Wider than [`ActionValue`] in exactly one place and deliberately not
+ * recursive: a `FormData` is something a call passes, never something inside
+ * something a call passes. `ActionArguments` in `../action.js` holds every
+ * action's parameter list against this, and `ActionResult` still holds every
+ * return type against `ActionValue` — an action receives a form and does not
+ * answer with one.
+ */
+export type ActionArgument = ActionValue | FormData;
+
 /**
  * A value that is outside the grammar, and where in the payload it was.
  *
@@ -158,6 +220,28 @@ function isPlainObject(value: interface {}): boolean {
  */
 const PLAIN_PROTOTYPE: mixed = Object.getPrototypeOf({});
 
+/**
+ * The value as a submitted form, or `null`.
+ *
+ * `typeof` first, because this module is imported by the browser's half and by
+ * the server's, and `FormData` is a global that a runtime is allowed not to
+ * have. `instanceof` and not a duck-type, for the reason `isPlainObject` gives
+ * about prototypes: an object with `entries` and `get` is not a form.
+ *
+ * It answers with the form rather than with a `boolean` so that the caller
+ * that goes on to read the entries has the type from the check rather than
+ * from a cast. A Flow type guard would be the direct spelling and is not
+ * available here: a guard has to refine the type away on the false branch too,
+ * and "this runtime has no `FormData` at all" is a false branch that says
+ * nothing about the value.
+ */
+function asFormData(value: mixed): FormData | null {
+  if (typeof FormData === "undefined" || !(value instanceof FormData)) {
+    return null;
+  }
+  return value;
+}
+
 /** One entry of the explicit walk stack. */
 type Pending = {| readonly value: mixed, readonly path: string, readonly depth: number |};
 
@@ -229,6 +313,18 @@ export function checkActionValue(root: mixed, label: string): void {
     }
 
     if (!isPlainObject(object)) {
+      // A form gets its own sentence. It is the one prototype this grammar
+      // does carry, just not here — a `FormData` is an argument of a call, and
+      // this walk only ever sees the inside of one, or a result — and "is a
+      // class instance" would send the reader looking for a class they did not
+      // write.
+      if (asFormData(object) != null) {
+        throw new ActionValueError(
+          path,
+          "is a FormData, and a form may only be an argument of a call: never part of a value, " +
+            "and never a result",
+        );
+      }
       throw new ActionValueError(
         path,
         "is a class instance, a Map, a Set, a Date, a React element or another object with a " +
@@ -252,12 +348,52 @@ export function checkActionValue(root: mixed, label: string): void {
   }
 }
 
+/**
+ * One form's entries, as pairs of strings, or a named failure.
+ *
+ * The count is checked as the entries are read rather than afterwards, so an
+ * enormous form is refused before the whole of it has been copied. A `File`
+ * entry is refused by name: an upload is not in this grammar and the field
+ * that carried it is the useful half of saying so.
+ */
+function formEntries(form: FormData, label: string): Array<Array<string>> {
+  const entries: Array<Array<string>> = [];
+  for (const [name, value] of form.entries()) {
+    if (entries.length >= MAX_FORM_ENTRIES) {
+      throw new ActionValueError(
+        label,
+        `carries more than ${String(MAX_FORM_ENTRIES)} form fields`,
+      );
+    }
+    if (name.length > MAX_FORM_NAME_LENGTH) {
+      throw new ActionValueError(
+        label,
+        `has a form field name longer than ${String(MAX_FORM_NAME_LENGTH)} characters`,
+      );
+    }
+    if (typeof value !== "string") {
+      throw new ActionValueError(
+        `${label} field \`${name}\``,
+        "is a file, and a file cannot cross to a server action",
+      );
+    }
+    entries.push([name, value]);
+  }
+  return entries;
+}
+
 /**
  * The request body for a call, or a named failure.
  *
  * The browser's half. Refusing here is what turns "the server answered 400"
  * into "argument 2.createdAt is a class instance", at the call site, with a
  * stack that reaches the component.
+ *
+ * A `FormData` argument becomes the envelope's `form` key and leaves `null` in
+ * its own slot, so `args` stays a list of values of exactly the length the
+ * call had. Two forms is a refusal rather than a choice: React passes one, and
+ * an envelope that could carry several would need to say which is which in a
+ * place that is not `at`.
  */
 export function encodeActionArguments(args: $ReadOnlyArray<mixed>): string {
   if (args.length > MAX_ACTION_ARGUMENTS) {
@@ -267,10 +403,24 @@ export function encodeActionArguments(args: $ReadOnlyArray<mixed>): string {
         String(MAX_ACTION_ARGUMENTS),
     );
   }
+  const values: Array<mixed> = [];
+  let form: {| readonly at: number, readonly entries: Array<Array<string>> |} | null = null;
   for (let index = 0; index < args.length; index += 1) {
-    checkActionValue(args[index], `argument ${String(index + 1)}`);
+    const argument = args[index];
+    const label = `argument ${String(index + 1)}`;
+    const submitted = asFormData(argument);
+    if (submitted != null) {
+      if (form != null) {
+        throw new ActionValueError(label, "is a second form, and a call carries at most one");
+      }
+      form = { at: index, entries: formEntries(submitted, label) };
+      values.push(null);
+      continue;
+    }
+    checkActionValue(argument, label);
+    values.push(argument);
   }
-  return JSON.stringify({ args });
+  return form == null ? JSON.stringify({ args: values }) : JSON.stringify({ args: values, form });
 }
 
 /**
@@ -282,7 +432,7 @@ export function encodeActionArguments(args: $ReadOnlyArray<mixed>): string {
  * only way to keep this closed as it grows is to refuse anything that is not
  * this today.
  */
-export function decodeActionArguments(text: string): Array<ActionValue> {
+export function decodeActionArguments(text: string): Array<ActionArgument> {
   let parsed: mixed;
   try {
     parsed = JSON.parse(text);
@@ -293,8 +443,9 @@ export function decodeActionArguments(text: string): Array<ActionValue> {
     throw new ActionValueError("the body", "is not a JSON object");
   }
   const keys: $ReadOnlyArray<string> = Object.getOwnPropertyNames(parsed);
-  if (keys.length !== 1 || keys[0] !== "args") {
-    throw new ActionValueError("the body", 'has keys other than "args"');
+  const named = keys.length === 1 ? keys[0] === "args" : keys.length === 2 && keys.includes("form");
+  if (!named || !keys.includes("args")) {
+    throw new ActionValueError("the body", 'has keys other than "args" and "form"');
   }
   const args: mixed = parsed.args;
   if (!Array.isArray(args)) {
@@ -309,7 +460,79 @@ export function decodeActionArguments(text: string): Array<ActionValue> {
   for (let index = 0; index < args.length; index += 1) {
     checkActionValue(args[index], `argument ${String(index + 1)}`);
   }
-  return args as $FlowFixMe;
+  const decoded: Array<ActionArgument> = args as $FlowFixMe;
+  if (keys.length === 2) {
+    const at = decodeForm(parsed.form, decoded);
+    decoded[at.index] = at.form;
+  }
+  return decoded;
+}
+
+/**
+ * The envelope's `form`, as a `FormData` and the position it belongs at.
+ *
+ * Every field of the envelope is checked before anything is built, and the
+ * slot it names must already hold `null`: `args` and `form` are two statements
+ * about one call, and a payload that makes both about the same argument is a
+ * payload whose sender believed something that is not true. The only thing
+ * constructed is a `FormData`, from strings, and which constructor that is was
+ * decided here rather than by the bytes.
+ */
+function decodeForm(
+  candidate: mixed,
+  args: $ReadOnlyArray<ActionArgument>,
+): {| readonly index: number, readonly form: FormData |} {
+  if (typeof FormData === "undefined") {
+    throw new ActionValueError("the body", "carries a form, and this runtime has no FormData");
+  }
+  if (candidate == null || typeof candidate !== "object" || Array.isArray(candidate)) {
+    throw new ActionValueError("the form", "is not a JSON object");
+  }
+  const keys: $ReadOnlyArray<string> = Object.getOwnPropertyNames(candidate);
+  if (keys.length !== 2 || !keys.includes("at") || !keys.includes("entries")) {
+    throw new ActionValueError("the form", 'has keys other than "at" and "entries"');
+  }
+
+  const at: mixed = candidate.at;
+  if (typeof at !== "number" || !Number.isInteger(at) || at < 0 || at >= args.length) {
+    throw new ActionValueError("the form", "names no argument of this call");
+  }
+  if (args[at] !== null) {
+    throw new ActionValueError(
+      "the form",
+      `names argument ${String(at + 1)}, which the payload also gives a value`,
+    );
+  }
+
+  const entries: mixed = candidate.entries;
+  if (!Array.isArray(entries)) {
+    throw new ActionValueError("the form", 'has an "entries" that is not an array');
+  }
+  if (entries.length > MAX_FORM_ENTRIES) {
+    throw new ActionValueError(
+      "the form",
+      `carries more than ${String(MAX_FORM_ENTRIES)} form fields`,
+    );
+  }
+
+  const form: FormData = new FormData();
+  for (const entry of entries) {
+    if (!Array.isArray(entry) || entry.length !== 2) {
+      throw new ActionValueError("the form", "has an entry that is not a name and a value");
+    }
+    const [name, value] = entry;
+    if (typeof name !== "string" || typeof value !== "string") {
+      throw new ActionValueError("the form", "has an entry whose name or value is not a string");
+    }
+    if (name.length > MAX_FORM_NAME_LENGTH) {
+      throw new ActionValueError(
+        "the form",
+        `has a form field name longer than ${String(MAX_FORM_NAME_LENGTH)} characters`,
+      );
+    }
+    form.append(name, value);
+  }
+  return { index: at, form };
 }
 
 /**

package/internal/devtools.js

@@ -0,0 +1,131 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: whether React DevTools can actually attach
+// to the page this browser just hydrated.
+//
+// `@uniflowed/vite` installs the hook DevTools attaches through, as a classic
+// script above every module — see `packages/vite/internal/devtools.js`, which
+// has the argument. That is uf saying what it intends. This is the half that
+// checks it happened, and the two are not the same claim: the preamble is
+// injected by a `transformIndexHtml` hook, into a document a project's own Vite
+// plugins also write to, and the thing that has to be true is an *ordering* —
+// the hook exists before `react-dom` is evaluated — which no amount of reading
+// the injector can establish about a particular page.
+//
+// It runs once, after hydration, in development only, and says nothing at all
+// when there is nothing wrong. See ubugeeei-prod/uf#503.
+//
+// # Why it reports rather than throws
+//
+// Nothing here is a reason to stop a page. DevTools not attaching costs a
+// developer a panel, and a framework that refused to render over it would have
+// turned a missing convenience into an outage. So the two findings go to the
+// terminal on the same channel as every other browser-side diagnostic — see
+// `./diagnostics.js` — and the page carries on.
+//
+// # The two findings, and why they are the two
+//
+// A third condition — React's *development* build, which is what gives the
+// panel props, hooks and source positions — is not checked here because a
+// browser cannot tell the difference from the outside, and because uf owns it
+// end to end: `mode` is `development` and `uf transform` is called with
+// `development: true`, both asserted in `tests/library/devtools.test.js`
+// against the plugin rather than against a page. What is left is what only a
+// running page knows.
+//
+//   1. **There is no hook.** Something ran before `react-dom` and there was
+//      nothing for it to register with, or the preamble did not reach this
+//      document. Either way no renderer was announced and the panel will say
+//      the page is not using React.
+//   2. **There is more than one renderer.** Two copies of `react-dom` each
+//      injected, and DevTools shows the tree of whichever it heard from — which
+//      is the shape of the "multiple renderers concurrently rendering the same
+//      context provider" report, and a component tree that is missing half the
+//      page for a reason nothing on screen explains.
+
+import { reportDiagnostic } from "./diagnostics.js";
+
+/**
+ * The global React registers itself with.
+ *
+ * The same string as `DEVTOOLS_HOOK` in `@uniflowed/vite`'s
+ * `internal/devtools.js`, written out again rather than imported for the reason
+ * that file's neighbour `internal/diagnostics.js` gives about the endpoint
+ * paths: `@uniflowed/vite` is loaded by Vite before any Flow transform exists
+ * and this module is Flow, so the import cannot go either way.
+ * `tests/library/devtools.test.js` asserts the two spellings agree, which is
+ * what makes a duplicated constant honest.
+ */
+export const DEVTOOLS_HOOK: string = "__REACT_DEVTOOLS_GLOBAL_HOOK__";
+
+/** The part of a page this module reads. */
+type HookWindow = {
+  [key: string]: mixed,
+  ...
+};
+
+/**
+ * What is wrong with this page's DevTools hook, as a diagnostic, or `null`.
+ *
+ * Separated from the reporting so that a test can ask the question without a
+ * channel to answer on, and because the wording is the part worth pinning: a
+ * reader who sees this in a terminal has to be able to act on it without
+ * reading this file.
+ */
+export function devtoolsProblem(win: HookWindow): {|
+  readonly message: string,
+  readonly detail: $ReadOnlyArray<string>,
+|} | null {
+  const hook = win[DEVTOOLS_HOOK];
+  if (hook == null || typeof hook !== "object") {
+    return {
+      message: `React DevTools cannot attach: nothing installed \`${DEVTOOLS_HOOK}\` before react-dom ran`,
+      detail: [
+        "React registers itself with that global while `react-dom` is evaluated, once and never again.",
+        "`uf dev` injects the hook as a classic script at the top of the head; a plugin that replaces",
+        "`transformIndexHtml`'s output, or a document that does not go through it, takes it away.",
+      ],
+    };
+  }
+
+  // `renderers` is a Map React puts its renderer in, keyed by the id `inject`
+  // handed back. Anything else there is a hook uf did not install and DevTools
+  // did not either, and guessing at its shape would report a problem that is
+  // really this module not recognising one.
+  const renderers = (hook: $FlowFixMe).renderers;
+  const count = renderers instanceof Map ? renderers.size : null;
+  if (count != null && count > 1) {
+    return {
+      message: `React DevTools has ${count} renderers on this page and will show one of them`,
+      detail: [
+        "Two copies of `react-dom` are loaded, so half the component tree is in a tree the panel cannot see.",
+        '`resolve.dedupe: ["react", "react-dom"]` is what usually prevents it; a linked package with its',
+        "own `react-dom` in `node_modules` is what usually causes it.",
+      ],
+    };
+  }
+  return null;
+}
+
+/**
+ * Report the problem, if there is one, to the terminal running `uf dev`.
+ *
+ * Throws nothing and returns nothing, and the guard is around the whole body
+ * rather than around the reading: this is called from the line after a
+ * successful hydration, so every failure available to it — a hook object whose
+ * property getter throws, a host with no `fetch` to report through — is a
+ * development convenience failing, and a development convenience that can take
+ * a working page down is worse than no convenience at all.
+ */
+export function reportDevtools(win: HookWindow): void {
+  try {
+    const problem = devtoolsProblem(win);
+    if (problem == null) {
+      return;
+    }
+    reportDiagnostic({ severity: "warn", message: problem.message, detail: problem.detail });
+  } catch {
+    // Deliberately silent. There is no second channel to complain on, and the
+    // thing being reported was never worth interrupting anybody for.
+  }
+}

package/internal/diagnostics.js

@@ -39,9 +39,9 @@
 // `uf dev` serves this path and nothing else does: a built application has no
 // `/__uf/` anything, so a call in production posts to a path that answers 404
 // and the rejected promise is swallowed here. That is a fallback rather than a
-// design — the only caller is behind `import.meta.hot` in `../client.js`, so a
-// production bundle has no path to this module rather than merely no answer
-// from it.
+// design — both callers are behind `import.meta.hot` in `../client.js`, the
+// hydration report and the DevTools check, so a production bundle has no path
+// to this module rather than merely no answer from it.
 //
 // Nothing here opens a connection until it is called, importing it does nothing
 // at all, and what it sends goes to the page's own origin as a path rather than

package/internal/runtime.js

@@ -732,6 +732,68 @@ function matchSegments(
   return index === parts.length ? params : null;
 }
 
+/**
+ * The URL for a route pattern and the parameters it takes.
+ *
+ * The inverse of [`matchSegments`], and deliberately built out of the same
+ * [`compile`]: a builder that parsed patterns its own way would drift from the
+ * matcher, and the drift would show up as a link that 404s rather than as a
+ * failure anybody could see.
+ *
+ * The generated `router.js` is what a project calls — `route("/posts/:slug",
+ * { slug })` — and it is typed there, so the parameters are checked before this
+ * runs. This still refuses a bad call rather than building a wrong URL,
+ * because the types are only in front of the callers that have them: a value
+ * that arrived from JSON, or from a module that opted out of Flow, reaches
+ * here unchecked. A link to `/posts/undefined` is the failure this exists to
+ * turn into an error with a name on it.
+ *
+ * Each segment is `encodeURIComponent`d, which is what [`decodeSegment`]
+ * undoes on the way back — so a slug with a slash in it round-trips as one
+ * segment rather than becoming two.
+ */
+export function buildRoute(routePath: string, params?: RouteParams): string {
+  const values: RouteParams = params ?? {};
+  const parts: Array<string> = [];
+  for (const segment of compile(routePath)) {
+    match (segment) {
+      {kind: "static", value: const value} => {
+        parts.push(value);
+      }
+      {kind: "param", name: const name} => {
+        const value = values[name];
+        if (typeof value !== "string") {
+          throw new Error(
+            `route ${routePath} takes a string for :${name}, and got ${describeParam(value)}`,
+          );
+        }
+        parts.push(encodeURIComponent(value));
+      }
+      {kind: "catchAll", name: const name} => {
+        const value = values[name];
+        if (value == null || typeof value === "string") {
+          throw new Error(
+            `route ${routePath} takes an array of segments for :${name}*, and got ` +
+              describeParam(value),
+          );
+        }
+        for (const part of value) {
+          parts.push(encodeURIComponent(part));
+        }
+      }
+    }
+  }
+  return parts.length === 0 ? "/" : `/${parts.join("/")}`;
+}
+
+/** What a parameter was, for the message that says it was the wrong thing. */
+function describeParam(value: string | $ReadOnlyArray<string> | void): string {
+  if (value === undefined) {
+    return "nothing";
+  }
+  return typeof value === "string" ? `the string ${JSON.stringify(value)}` : "an array";
+}
+
 function decodeSegment(segment: string): string {
   try {
     return decodeURIComponent(segment);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.14",
+  "version": "0.0.0-alpha.16",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "react-dom": ">=19"
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.14",
-    "@uniflowed/server": "0.0.0-alpha.14"
+    "@uniflowed/hooks": "0.0.0-alpha.16",
+    "@uniflowed/server": "0.0.0-alpha.16"
   }
 }