@uniflowed/router 0.0.0-alpha.9 → 0.2.0

package/action.js

@@ -0,0 +1,344 @@
+// @flow
+//
+// `@uniflowed/router/action`: a server action, as the browser holds it.
+//
+// A `"use client"` module writes an ordinary import and an ordinary call:
+//
+//   // app/counter/_components/Counter.js
+//   "use client";
+//   import { recordClick } from "../_actions/clicks.js";
+//   …
+//   <button onClick={() => { void recordClick(count); }}>
+//
+// On the server that import is the function. In the browser it is a reference
+// built here: `@uniflowed/vite` replaces the `"use server"` module, in the
+// client graph only, with one `createServerReference` per callable export, so
+// what crosses the import is an id and a `fetch` — and the module's body, its
+// imports and every secret they reached stay where they were written.
+//
+// # Why this module is where it is
+//
+// It is the browser's half, so it may not live in `@uniflowed/server`: that
+// package is in `SERVER_ONLY_PACKAGES` and importing it from a client
+// component is the error the RSC graph exists to produce. It holds no
+// platform API beyond `fetch` and `location`, and it imports one internal
+// module, which is the grammar the server applies to the same bytes.
+//
+// # The call
+//
+// `POST` to the page's own URL, `uf-action: <id>`, `application/json`, and
+// `{"args":[…]}`. The URL is the page rather than a path uf reserves so that
+// the middleware guarding that path runs above the call exactly as it does
+// 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.
+//
+// **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
+//
+// A reference carries its build's id, and a new build mints new ids, so a tab
+// left open across a deploy holds ids the live server has never heard of. The
+// call names the page's build in `uf-deployment`; a server on another build
+// answers `409` without running anything; and the reference then loads the
+// page's document again — a hard navigation onto the live build — instead of
+// throwing. The promise it returned never settles, because the page it was
+// returned to is being replaced. See `./internal/deployment.js`.
+//
+// # What Flow checks, and where
+//
+// Flow reads `app/_actions/clicks.js`, not the reference the bundler
+// substitutes for it, so `recordClick("nine")` against
+// `recordClick(count: number)` is a `uf check` error rather than a `400`. That
+// is the half that needs nothing from this module.
+//
+// What a declaration alone does not say is whether those arguments and that
+// result can cross a wire at all, and `ActionArguments` and `ActionResult` are
+// that half: `uf prepare` writes one instantiation of each into
+// `server-actions.js`, over every action in the project at once, so an action
+// taking a callback or returning a `Map` is a `uf check` error naming the
+// offending type. Without them the same mistake is a request that arrives with
+// `{}` where an object was passed — the kind of bug found in production by a
+// column that stopped being written.
+
+import {
+  ACTION_CONTENT_TYPE,
+  ACTION_HEADER,
+  type ActionArgument,
+  type ActionValue,
+  decodeActionResult,
+  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";
+export {
+  ACTION_CONTENT_TYPE,
+  ACTION_HEADER,
+  ActionValueError,
+  MAX_ACTION_ARGUMENTS,
+  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, 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<ActionArgument>) => Promise<ActionValue | void>;
+
+/**
+ * An action's arguments, held against what a wire can carry.
+ *
+ * A bound on a tuple rather than a bound on the function, and the difference
+ * is the whole reason this is two types instead of one. A function type puts
+ * its parameters in a contravariant position: `F extends (…args:
+ * Array<ActionValue>) => …` asks whether `F` accepts *every* `ActionValue`,
+ * which `createUser(name: string)` does not and should not. `Parameters<F>` is
+ * the same list read covariantly, where the question is the one worth asking —
+ * is each argument something that can cross?
+ *
+ * `uf prepare` writes one instantiation over the whole project:
+ *
+ *   export type ServerActionArgsFitTheWire =
+ *     ActionArguments<ServerActionArgs<ServerActionName>>;
+ *
+ * `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<ActionArgument>> = TArgs;
+
+/**
+ * An action's result, held against the same grammar.
+ *
+ * A promise, because a server action is always async — the RSC graph rejects
+ * one that is not — and `void` is allowed because an action that returns
+ * nothing is ordinary. `Promise` is covariant in Flow, so the bound reaches
+ * the resolved type without any of the contortion the arguments needed.
+ */
+export type ActionResult<TResult extends Promise<ActionValue | void>> = TResult;
+
+/**
+ * A server action that did not answer.
+ *
+ * Carries the status and the action's build-time name and nothing else,
+ * because nothing else came back: the endpoint answers every refusal with a
+ * fixed body, so there is no message from the server to relay. What went wrong
+ * is in the server's log, which is where an application's internals belong.
+ */
+export class ServerActionError extends Error {
+  /** The HTTP status the endpoint answered with. */
+  status: number;
+  /** `module#export` of the action that was called. */
+  action: string;
+
+  constructor(action: string, status: number) {
+    super(
+      `@uniflowed/router: the server action \`${action}\` answered ${String(status)}. ` +
+        "The endpoint reports every failure the same way; the reason is in the server's log.",
+    );
+    this.name = "ServerActionError";
+    this.status = status;
+    this.action = action;
+  }
+}
+
+/**
+ * The reference the client bundle holds in place of one server action.
+ *
+ * Generated, never written by hand: `@uniflowed/vite` emits one call per
+ * callable export of a `"use server"` module, with the id
+ * `crates/uf_rsc/src/action.rs` derived for it and the `module#export` name
+ * that only ever appears in an 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 `$$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> {
+    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
+    // declines to track.
+    const headers: { [string]: string } = { "content-type": ACTION_CONTENT_TYPE };
+    headers[ACTION_HEADER] = id;
+    // Which build this page is, so a server on another build refuses the call
+    // rather than looking this id up in a table it was never in.
+    withDeployment(headers);
+    const response = await fetch(currentUrl(), {
+      method: "POST",
+      // Stated rather than left to the default, because the default is what a
+      // reader has to look up and because this one is load-bearing: the
+      // endpoint's `Origin` check is only meaningful for a request that
+      // carries the visitor's cookies in the first place.
+      credentials: "same-origin",
+      // Never a cached answer, and never one written to a cache: an action is
+      // a side effect, and `POST` responses are outside HTTP caching by
+      // default only until something decides otherwise.
+      cache: "no-store",
+      headers,
+      body,
+    });
+    // A route a navigation kept may no longer show what this action wrote, and
+    // which routes is the server's to know, so every kept route is asked for
+    // again. Whatever the status: an action that failed part-way may have
+    // written before it failed. See `./internal/navigation-cache.js`.
+    clearNavigationCache();
+    // The server is on another build: nothing ran, and nothing on this page
+    // can be called correctly any more. Load the page again, from the build
+    // that is live, and never settle — a rejection here would reach an error
+    // boundary for the moment before the document is replaced, and a result
+    // would be a lie. See `./internal/deployment.js`.
+    if (refusedAsAnotherDeployment(response)) {
+      loadDocument(currentUrl());
+      return new Promise<ActionValue | void>(() => {});
+    }
+    if (!response.ok) {
+      throw new ServerActionError(name, response.status);
+    }
+    return decodeActionResult(await response.text());
+  };
+}
+
+/**
+ * The URL an action call is sent to: the page the browser is on.
+ *
+ * Path and query, not the whole URL, so the request is same-origin by
+ * construction rather than by a comparison somebody could get wrong. The hash
+ * is left off because it never reaches a server.
+ *
+ * A reference only exists in the client bundle — the server imports the real
+ * module — so there is no `location` here only if something has imported the
+ * browser's half into a server, and saying so is better than posting to a
+ * relative path that means nothing there.
+ */
+function currentUrl(): string {
+  const location = globalThis.location;
+  if (location == null) {
+    throw new Error(
+      "@uniflowed/router: a server action reference was called where there is no `location`. " +
+        "A reference is the browser's half of an action; the server imports the module itself.",
+    );
+  }
+  return `${location.pathname}${location.search}`;
+}

package/client.js

@@ -1,12 +1,91 @@
 // @flow
 //
-// Hydrating the document in the browser.
+// Starting the application in the browser.
+//
+// Two entry points, and which one `virtual:uf/client` calls is decided by
+// `app.rendering.modes`. `hydrate` is the one every uf build has used: a server
+// or a prerender wrote the markup, and React attaches to it. `render` is for
+// `["csr"]`, where the build wrote one shell with an empty root and nothing has
+// been rendered anywhere yet; see its own comment for why that is not `hydrate`
+// with a flag.
 //
 // `virtual:uf/client` calls `hydrate` with the app root and the route table.
 // The current route's chunks are loaded and its embedded loader data read
 // *before* `hydrateRoot`, so the first client render is synchronous and
 // matches the server's markup exactly.
 //
+// An application whose routes render as React Server Components, the default,
+// starts from neither: `hydrateFlight` in `./rsc-client.js` hydrates the Flight
+// payload its document carries. That is a separate entry so that this one,
+// which every other web application imports, never names React's Flight
+// client. The client is an optional peer that needs React 19.3, and a project
+// on React 19.2 does not install it (ubugeeei-prod/uf#992).
+//
+// # What "its loader data" means once the loader can defer
+//
+// It is a payload rather than a value: `internal/payload.js` writes the model
+// into `<script id="__uf_data">` with a `"$P<n>"` reference wherever the loader
+// left a promise, and each of those arrives later in a `<script data-uf-row>`
+// of its own. So two things happen before `hydrateRoot` rather than one — the
+// model is decoded, and `internal/payload-rows.js` starts watching for the
+// rows it referred to. Both have to be first: the decoded model is what the
+// first render is handed, and a row that landed while nothing was watching
+// would be a boundary that never resolves. A document with nothing deferred
+// has no references, so the reader is handed no ids and installs nothing.
+//
+// # A hydration that fails says what differed
+//
+// React reports a mismatch with one sentence and a list of the six things that
+// usually cause it, and leaves the reader to find which node of the two
+// thousand on the page was the one. This module is the only place that can do
+// better, because it is the only place that runs between the parser finishing
+// and React starting: `internal/hydration.js` takes a copy of the server's
+// markup here, and compares it against the repaired tree when React reports.
+// 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.
+//
+// # And an application can decline to be navigated
+//
+// `app.rendering.navigation: "document"` is the whole application saying what
+// the paragraph below says about one route: the document the server wrote is
+// what a link produces, and the browser fetches the next one. It is *not* the
+// same as declining to hydrate — the page still hydrates, so a `"use client"`
+// component is still interactive — and what it removes is the takeover. The
+// flag reaches the runtime through `installNavigation` before the first render;
+// see `internal/runtime.js` for what `RouterProvider` and `Link` then do, and
+// `docs/app/guide/rendering` for when a project wants it.
+//
 // # A route can decline to be hydrated
 //
 // uf's server-component analysis decides which routes have a `"use client"`
@@ -18,18 +97,30 @@
 // See ubugeeei-prod/uf#350.
 
 import * as React from "react";
-import { startTransition } from "react";
-import { hydrateRoot } from "react-dom/client";
+import { StrictMode, startTransition } from "react";
+import { createRoot, hydrateRoot } from "react-dom/client";
 
 import {
   type AppProps,
+  type Navigation,
   type RouteTable,
+  RedirectError,
   hasClientPage,
+  installNavigation,
   installRoutes,
+  installRouting,
+  installStaleTime,
   matchRoute,
+  resolveFailure,
   resolveMatch,
 } from "./internal/runtime.js";
 import { DATA_ID, ROOT_ID } from "./internal/document.js";
+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.
@@ -43,6 +134,11 @@ export async function hydrate(options: {|
   readonly routes: RouteTable["routes"],
   readonly notFound: RouteTable["notFound"],
   readonly errors: RouteTable["errors"],
+  readonly strictMode?: boolean,
+  readonly navigation?: Navigation,
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
+  readonly staleTime?: number,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -50,22 +146,182 @@ export async function hydrate(options: {|
     errors: options.errors,
   };
   installRoutes(table);
+  // Beside the table, and before anything renders. `"client"` when the entry
+  // says nothing, which is what `virtual:uf/client` generated before
+  // `app.rendering.navigation` existed and what a hand-written entry still
+  // means: the default is the behaviour, not the absence of one.
+  installNavigation(options.navigation ?? "client");
+  installRouting({ basePath: options.basePath, trailingSlash: options.trailingSlash });
+  installStaleTime(options.staleTime ?? 0);
+  // The route table has no base path in it, and the address bar does.
+  const applicationPath = applicationPathOf(window.location.pathname) ?? window.location.pathname;
 
   // Before the loader data is read and before `resolveMatch` is called: both
   // would go looking for a page module that is not in this bundle.
-  const matched = matchRoute(table.routes, window.location.pathname);
+  const matched = matchRoute(table.routes, applicationPath);
   if (matched != null && !hasClientPage(matched.route)) {
     return;
   }
 
-  const url = window.location.pathname + window.location.search;
+  const url = applicationPath + window.location.search;
+  // Row 0 of the payload, and the reader that will fill in the rows it refers
+  // to. Both before `hydrateRoot`, and in this order: `decodePayload` is what
+  // tells the reader which rows the page is waiting for, and `watch` is what
+  // makes it notice the ones the server has not written yet. A document with
+  // nothing deferred has no references, so the reader is handed no ids, and
+  // `watch` returns without installing anything — see `internal/payload.js`.
   const embedded = document.getElementById(DATA_ID);
-  const data = embedded != null ? JSON.parse(embedded.textContent ?? "null") : undefined;
+  const reader = createPayloadReader(document, domObserver(document));
+  const data =
+    embedded != null
+      ? decodePayload(
+          JSON.parse(embedded.textContent ?? "null"),
+          reader.resolve,
+          "the route's loader data",
+        )
+      : undefined;
+  reader.watch();
   const resolved = await resolveMatch(table, url, { data, skipLoader: embedded != null });
 
   const { App } = options;
   const container = document.getElementById(ROOT_ID) ?? document;
+  prepareDocumentForHydration(document);
+
+  // The server's markup, and the reporter that will read it, in development
+  // only. Both have to be in place *before* `hydrateRoot`: React repairs a
+  // mismatched subtree by rendering over it, so the bytes the server sent exist
+  // for exactly the moment between the parser finishing and this line.
+  //
+  // `import.meta.hot` is the gate because it is the one signal that is right in
+  // all three places this module is evaluated. Vite defines it while serving
+  // and replaces it with `undefined` in a build, so the branch is statically
+  // dead there; Node leaves it undefined, so `packages/vite/rsc-split.test.js`
+  // imports this file without a bundler and gets the production path. The
+  // import is dynamic so that the overlay is not merely shaken out of a
+  // production bundle but never reachable from one.
+  let recovery = null;
+  let restoreDevHead = null;
+  if (import.meta.hot != null) {
+    const { captureServerMarkup, hydrationErrorHandler, prepareDevHeadForHydration } =
+      await import("./internal/hydration.js");
+    restoreDevHead = prepareDevHeadForHydration(document);
+    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} />);
+    hydrateRoot(
+      container,
+      options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
+      hydrationOptions(recovery, readFormState(document)),
+    );
+    if (restoreDevHead != null) {
+      setTimeout(restoreDevHead, 250);
+    }
   });
+
+  // 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);
+  }
+}
+
+/**
+ * Render the current route into an empty shell.
+ *
+ * The single-page entry point: `app.rendering.modes: ["csr"]` writes one
+ * document with an empty root and no markup in it, and this is what fills it.
+ *
+ * # Why it is not `hydrate` with a flag
+ *
+ * Because hydration is React comparing what it renders against what a server
+ * sent, and here no server sent anything. `hydrateRoot` against an empty
+ * container is a mismatch on the first node of every page — React would report
+ * it, throw the shell away and render from scratch, which is this function
+ * with a warning in front of it. `createRoot` says what is actually happening:
+ * the browser is the only renderer this application has.
+ *
+ * Three more things follow from there, and each of them is a line below rather
+ * than an omission:
+ *
+ *   * **The loader runs here.** `resolveMatch` fetches the route's modules and
+ *     runs its loader in the browser, because there was no server render to run
+ *     it in and no `<script id="__uf_data">` for it to have left an answer in.
+ *   * **A URL that matches nothing is the not-found boundary**, resolved the
+ *     way a server resolves it. The host served this shell for a URL it had no
+ *     file for, so "nothing matched" is a perfectly ordinary arrival here
+ *     rather than the exception it is during hydration.
+ *   * **A redirect is the browser's.** `redirect()` from a loader throws before
+ *     anything is rendered; on a server that becomes a 307 and here it becomes
+ *     `location.replace`, which is the same instruction to the same browser.
+ */
+export async function render(options: {|
+  readonly App: React.ComponentType<AppProps>,
+  readonly routes: RouteTable["routes"],
+  readonly notFound: RouteTable["notFound"],
+  readonly errors: RouteTable["errors"],
+  readonly strictMode?: boolean,
+  readonly navigation?: Navigation,
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
+  readonly staleTime?: number,
+|}): Promise<void> {
+  const table: RouteTable = {
+    routes: options.routes,
+    notFound: options.notFound,
+    errors: options.errors,
+  };
+  installRoutes(table);
+  installNavigation(options.navigation ?? "client");
+  installRouting({ basePath: options.basePath, trailingSlash: options.trailingSlash });
+  installStaleTime(options.staleTime ?? 0);
+
+  const url =
+    (applicationPathOf(window.location.pathname) ?? window.location.pathname) +
+    window.location.search;
+  let resolved;
+  try {
+    resolved = await resolveMatch(table, url);
+  } catch (error) {
+    if (error instanceof RedirectError) {
+      window.location.replace(addressOf(error.to));
+      return;
+    }
+    // The error boundary, chosen the same way the server chooses it. A throw
+    // from a loader is a page that cannot render, and rendering the boundary is
+    // what this application has instead of a 500.
+    resolved = await resolveFailure(table, url, error);
+  }
+
+  const { App } = options;
+  // An element, and never `document` — which is the other difference from
+  // `hydrate` above. `hydrateRoot` takes a document, because an app whose root
+  // layout renders `<html>` owns the whole of one and the server wrote it;
+  // `createRoot` does not, because creating a root *is* replacing the
+  // container's children and the container here would be the document. The
+  // shell always writes this element, so its absence means the document being
+  // rendered into is not one this build produced.
+  const container = document.getElementById(ROOT_ID);
+  if (container == null) {
+    throw new Error(
+      `@uniflowed/router: no #${ROOT_ID} in this document, so there is nothing to render into. ` +
+        "A single-page build writes the shell that carries it; this document came from " +
+        "somewhere else.",
+    );
+  }
+  const tree = <App url={url} initial={resolved} />;
+  createRoot(container).render(
+    options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
+  );
 }