@uniflowed/router 0.0.0-alpha.13 → 0.0.0-alpha.15

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/handler.js

@@ -69,7 +69,7 @@
 // `after()` promises. A handler that streams its body has not sent a byte at
 // that point. See ubugeeei-prod/uf#389.
 
-import { noteRoute } from "@uniflowed/server/host";
+import { asResponder, noteRoute } from "@uniflowed/server/host";
 
 import { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
@@ -157,10 +157,15 @@ export function createDispatcher(options: {|
       // In the host's request, so a handler that calls `headers()`,
       // `cookies()` or `after()` answers about the same one its guard did, and
       // what it defers is drained once, by the host, after the bytes are out.
-      const response = await handler(request, {
-        params,
-        searchParams: url.searchParams,
-      });
+      //
+      // And inside `asResponder`, which is the other half: a route handler is
+      // one of the two things that owns a response, so it is one of the two
+      // places `draftMode().enable()` is allowed — and the `Set-Cookie` it
+      // decided on is written onto the response below rather than left on an
+      // object the host is about to discard. See ubugeeei-prod/uf#282.
+      const response = await asResponder("a route handler", async () =>
+        handler(request, { params, searchParams: url.searchParams }),
+      );
 
       // A `HEAD` answered by `GET` must not carry the body. The test is
       // against the module's own `HEAD`, not `pick`'s — `pick` falls back to

package/internal/action-endpoint.js

@@ -76,6 +76,8 @@
 // it. Written here because this is the file somebody reads before deciding
 // otherwise.
 
+import { asResponder } from "@uniflowed/server/host";
+
 import {
   ACTION_CONTENT_TYPE,
   ACTION_HEADER,
@@ -198,32 +200,44 @@ export function createActionDispatcher(options: {|
       return refusal(500);
     }
 
-    let result: mixed;
-    try {
-      // The build-time contract says this is `async (...ActionValue) => …`
-      // (`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
-      // shape of the function and not the shape of the payload.
-      const call = action as $FlowFixMe;
-      result = await call(...args);
-    } catch (error) {
-      report(record, error);
-      return refusal(500);
-    }
+    // Everything from here to the answer runs as the thing that owns this
+    // response, which is what makes `draftMode().enable()` legal in an action:
+    // a `"use server"` function is one of the two places uf lets draft mode be
+    // changed, and the `Set-Cookie` it decides on is written onto the response
+    // this returns rather than onto an object the host discards. See
+    // ubugeeei-prod/uf#282 and `asResponder`.
+    //
+    // The refusals stay outside it. A `403` for a cross-origin call must not
+    // carry a cookie the caller asked for, and a scope that covered them would
+    // be a scope in which nothing ran that could have asked.
+    return asResponder("a server action", async () => {
+      let result: mixed;
+      try {
+        // The build-time contract says this is `async (...ActionValue) => …`
+        // (`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
+        // shape of the function and not the shape of the payload.
+        const call = action as $FlowFixMe;
+        result = await call(...args);
+      } catch (error) {
+        report(record, error);
+        return refusal(500);
+      }
 
-    let answer: string;
-    try {
-      answer = encodeActionResult(result);
-    } catch (error) {
-      // The action ran and its return value cannot cross. Flow says so at
-      // build time — `ServerActionBoundary` in `../action.js` holds every
-      // action's return type against the grammar — so this is the case where
-      // it was reached anyway, and half a value is worse than none.
-      report(record, error);
-      return refusal(500);
-    }
-    return new Response(answer, { status: 200, headers: { ...ANSWER_HEADERS } });
+      let answer: string;
+      try {
+        answer = encodeActionResult(result);
+      } catch (error) {
+        // The action ran and its return value cannot cross. Flow says so at
+        // build time — `ServerActionBoundary` in `../action.js` holds every
+        // action's return type against the grammar — so this is the case where
+        // it was reached anyway, and half a value is worse than none.
+        report(record, error);
+        return refusal(500);
+      }
+      return new Response(answer, { status: 200, headers: { ...ANSWER_HEADERS } });
+    });
   };
 }
 

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

@@ -0,0 +1,169 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the way a diagnostic the browser produced
+// reaches the terminal.
+//
+// Every other uf diagnostic — a type error, a lint finding, a failing test, a
+// page that rendered its error boundary — arrives in the terminal the
+// developer already has open. One produced *in the browser* had nowhere to go:
+// the page is the only process that knows about it, and `uf dev`'s diagnostics
+// come up the driver's event channel from the Node process. So the hydration
+// report added in ubugeeei-prod/uf#582 lived in a browser overlay and in the
+// console, which has to be noticed, in a window that may not be in front, by
+// somebody who does not know to look. See ubugeeei-prod/uf#583.
+//
+// This is the client half. The server half is `uf dev`, through
+// `@uniflowed/vite`'s `internal/diagnostics.js`, which turns what arrives into
+// the same rendering the terminal gives everything else: a severity, the page
+// it came from, and a code frame when there is a position to draw one around.
+//
+// # One channel, and why the poster is not shared
+//
+// `/__uf/diagnostic` and `/__uf/vitals` are one channel: two paths, one payload
+// shape, one `diagnostic` event out of the driver, one renderer. What is *not*
+// shared is the twenty lines that post to it. `@uniflowed/web/vitals` has its
+// own `vitalsBeacon`, and this is the router's.
+//
+// `@uniflowed/hmr` would have been the tidier home — it is already "the browser
+// half of `uf dev`" — and it cannot be one. `tools/ci/publishable.sh` refuses a
+// published package that depends on an unpublished one, because the tarball
+// would name a version the registry does not have; `@uniflowed/router` is on
+// npm and `@uniflowed/hmr` is a declaration package that is not. What the two
+// posters do share is the contract, and `tests/library/dev-channel.test.js`
+// asserts that every spelling of these paths agrees — a duplicated constant
+// with a test on it is honest, and one without is how a browser ends up
+// posting to a path nothing serves.
+//
+// # It is development only, and it is best effort
+//
+// `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 — 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
+// a URL, so it cannot be pointed at somebody else's server. Nothing leaves the
+// machine.
+
+/**
+ * The path `uf dev` serves the diagnostic channel on.
+ *
+ * Under `/__uf/`, beside the update stream `@uniflowed/hmr` opens and the
+ * vitals endpoint `@uniflowed/web/vitals` posts to, for the reason that prefix
+ * exists: a directory in `app/` whose name begins with `_` is not a route, so
+ * no application can put anything here and nothing here can shadow a path a
+ * project wrote.
+ */
+export const DIAGNOSTIC_ENDPOINT: string = "/__uf/diagnostic";
+
+/**
+ * How loudly a diagnostic reads in the terminal.
+ *
+ * `error` for something that is wrong, `warn` for something that is worth
+ * knowing, `info` for something that is only a measurement. Three rather than
+ * two because the vitals report on the same channel needs the third: a page
+ * whose numbers are all good has still reported, and printing that as a warning
+ * would teach the reader to ignore the warnings.
+ */
+export type DiagnosticSeverity = "error" | "warn" | "info";
+
+/**
+ * One diagnostic, as the channel carries it.
+ *
+ * `message` is the headline and the only required field: one line, the thing
+ * that is wrong. `detail` is everything under it — the values that differed,
+ * the path through the tree, the advice — and is a list of lines rather than a
+ * blob so the terminal can indent them without guessing where they break.
+ *
+ * `url` is the page the browser was on, which the reporter fills in when the
+ * caller does not: a diagnostic that does not say which page produced it is a
+ * diagnostic somebody has to reproduce before they can act on it.
+ *
+ * `file`, `line` and `column` are for the rare browser-side report that knows a
+ * source position. When the file and the line are both there `uf dev` draws its
+ * ordinary code frame; when they are not it prints the headline and the detail,
+ * which is what a hydration mismatch — a fact about a DOM node rather than
+ * about a line — can honestly offer.
+ */
+export type BrowserDiagnostic = {
+  readonly severity: DiagnosticSeverity,
+  readonly message: string,
+  readonly detail?: $ReadOnlyArray<string>,
+  readonly url?: string,
+  readonly file?: string,
+  readonly line?: number,
+  readonly column?: number,
+};
+
+/** The part of the browser this module needs. */
+type ReportingWindow = {
+  readonly location?: { readonly href?: string, ... },
+  readonly fetch?: (input: string, init: { ... }) => Promise<mixed>,
+  ...
+};
+
+/** For a promise whose outcome is deliberately not looked at. */
+function noop(): void {}
+
+/**
+ * Send one diagnostic to `uf dev`, if there is a `uf dev` to send it to.
+ *
+ * Returns nothing and throws nothing. A diagnostic is a thing a person reads,
+ * not a thing an application branches on, and a reporter that could fail would
+ * make every caller wrap it — from a code path that is, by construction,
+ * already handling something that went wrong.
+ *
+ * `fetch` rather than `sendBeacon`, which is the opposite of the choice
+ * `vitalsBeacon` makes and for the opposite reason: a vital is measured as the
+ * page is put away and needs a transport that outlives it, while a diagnostic
+ * is produced by a page that is still running and had better arrive in the
+ * order it happened. `keepalive` covers the case where the page goes away
+ * immediately afterwards anyway.
+ *
+ * @param diagnostic what to report
+ * @param endpoint where to post it; [`DIAGNOSTIC_ENDPOINT`] by default
+ */
+export function reportDiagnostic(diagnostic: BrowserDiagnostic, endpoint?: string): void {
+  const win = reportingWindow();
+  if (win == null) {
+    return;
+  }
+  const post = win.fetch;
+  if (post == null) {
+    return;
+  }
+
+  const body = JSON.stringify({
+    ...diagnostic,
+    url: diagnostic.url ?? win.location?.href ?? "",
+  });
+  // A rejected promise nobody is holding becomes an unhandled rejection, which
+  // arrives in whatever error reporter the application installed — from a line
+  // about development tooling. Losing the report is the right outcome when
+  // there is nothing listening; reporting the loss as an application error is
+  // not.
+  post(endpoint ?? DIAGNOSTIC_ENDPOINT, {
+    method: "POST",
+    body,
+    keepalive: true,
+    headers: { "content-type": "application/json" },
+  }).then(noop, noop);
+}
+
+/**
+ * The window to report from, or `null` where there is no browser.
+ *
+ * The same reading `@uniflowed/web/vitals` makes, and for the same reason: in a
+ * browser `globalThis` *is* the window, but not where a document has been
+ * installed onto another host's global, which is every uf test process. Asking
+ * for the document first is what makes both cases work.
+ */
+function reportingWindow(): ReportingWindow | null {
+  if (typeof globalThis.document === "undefined") {
+    return null;
+  }
+  return globalThis.window ?? globalThis;
+}

package/internal/hydration.js

@@ -84,10 +84,21 @@
 // seed decided once and read by both sides (ubugeeei-prod/uf#554) — and this is
 // for the ones that still do.
 //
-// It does not reach the terminal either. `uf dev`'s diagnostics come up the
-// driver's event channel from the Node process, and a hydration mismatch
-// happens in the browser, which has no channel to send one back on. Naming
-// that here is more use than a half-built one: see ubugeeei-prod/uf#508.
+// # It does reach the terminal
+//
+// It did not, once. `uf dev`'s diagnostics come up the driver's event channel
+// from the Node process, and a hydration mismatch happens in the browser, which
+// had no channel to send one back on — so this report existed in an overlay and
+// in the console, and had to be noticed by somebody who knew to look. There is
+// a channel now: `./diagnostics.js` posts to `/__uf/diagnostic`, `uf dev`
+// answers it, and the same words this module formats for the overlay are
+// printed by the same renderer that prints a type error. See
+// ubugeeei-prod/uf#583, and #508 for where the gap was named.
+//
+// The overlay stays. It is in front of the reader who caused the mismatch by
+// editing the page, and the terminal is for the one who did not.
+
+import { reportDiagnostic } from "./diagnostics.js";
 
 /** Which of the usual causes the difference looks like. */
 export type HydrationCause = "variable-input" | "browser-only" | "invalid-nesting" | "unknown";
@@ -813,6 +824,13 @@ function paragraph(document: Document, text: string, className: string | null):
  * `reportError`, which is what React would have done: this callback replaces
  * React's default rather than adding to it, so anything it swallows is
  * swallowed for good.
+ *
+ * A mismatch goes to three places, and all three say the same words because all
+ * three come out of [`formatHydrationReport`]: the overlay, for the reader
+ * looking at the page; the console, for a headless run, a CI browser and a
+ * reader who closed the panel; and `uf dev`'s terminal, through
+ * [`reportDiagnostic`], for the reader who is not looking at the browser at
+ * all. See ubugeeei-prod/uf#583.
  */
 export function hydrationErrorHandler(
   container: Node,
@@ -848,6 +866,19 @@ export function hydrationErrorHandler(
     // console is where a headless run, a CI browser and a reader who closed
     // the panel all still see the report.
     console.error(text);
+    // And the terminal, where every other uf diagnostic already is. The
+    // headline is the first line and the rest is the detail, which is the
+    // shape the channel carries and is why the formatter puts the sentence
+    // first: one report, one wording, three places. No position goes with it —
+    // a mismatch is a fact about a DOM node rather than about a line of a
+    // file, and inventing a file and a line to earn a code frame would send
+    // the reader somewhere that is not the answer.
+    const [headlineLine, ...rest] = text.split("\n");
+    reportDiagnostic({
+      severity: "error",
+      message: headlineLine,
+      detail: rest,
+    });
   };
 }
 

package/internal/runtime.js

@@ -15,10 +15,8 @@ import {
   createContext,
   startTransition,
   use,
-  useCallback,
   useContext,
   useEffect,
-  useMemo,
   useState,
   useSyncExternalStore,
 } from "react";
@@ -31,6 +29,12 @@ import {
 // being evaluated.
 import { flushSync } from "react-dom";
 
+// The two things a render has to fix — its instant and its random seed — and
+// the provider that fixes them. Imported here rather than left to the
+// application, because a hydration guarantee nobody wires is not a guarantee:
+// see [`routerView`] and ubugeeei-prod/uf#559.
+import { RenderProvider } from "@uniflowed/hooks/render";
+
 // The id of the script the loader data is embedded in. It moved out of the
 // head and into the tree with ubugeeei-prod/uf#373 — see [`loaderDataScript`]
 // — so the module that renders it is this one rather than `../server.js`.
@@ -1530,9 +1534,9 @@ component RouteErrorView(module: ?ErrorModule, error: RouteError, reset: () => v
  */
 component ResolvedErrorPage() {
   const { resolved, router } = useRouterState();
-  const reset = useCallback(() => {
+  const reset = () => {
     router.refresh().catch(() => {});
-  }, [router]);
+  };
 
   if (resolved.error == null) {
     // Unreachable: this module is only ever the page of a resolved error route.
@@ -1850,7 +1854,7 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
   const [resolved, setResolved] = useState<ResolvedRoute>(initial);
   const [pending, setPending] = useState<boolean>(false);
 
-  const navigate = useCallback(async (to: string, options?: NavigateOptions): Promise<void> => {
+  const navigate = async (to: string, options?: NavigateOptions): Promise<void> => {
     if (!isBrowser()) {
       return;
     }
@@ -1899,7 +1903,7 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
       setPending(false);
       throw error;
     }
-  }, []);
+  };
 
   useEffect(() => {
     if (!isBrowser()) {
@@ -1930,59 +1934,53 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
     };
   }, []);
 
-  const router = useMemo<Router>(
-    () => ({
-      push: (to, options) => navigate(to, options),
-      replace: (to) => navigate(to, { replace: true }),
-      prefetch: async (to) => {
-        if (!isBrowser()) {
-          return;
-        }
-        const target = new URL(to, window.location.href);
-        const matched = matchRoute(routeTable().routes, target.pathname);
-        const load = matched?.route.page;
-        if (matched == null || load == null) {
-          return;
-        }
-        await Promise.all([
-          loadOnce(load),
-          ...matched.route.layouts.map((layout) => loadOnce(layout)),
-        ]);
-      },
-      refresh: async () => {
-        if (!isBrowser()) {
-          return;
-        }
-        const nextResolved = await resolveMatch(
-          routeTable(),
-          window.location.pathname + window.location.search,
-        );
-        // No view transition, and it is the one place that is right: a refresh
-        // is the same URL resolved again, so a transition would animate a page
-        // into itself — a cross-fade between two frames of the same thing,
-        // which is a flicker with a name.
-        startTransition(() => {
-          setResolved(nextResolved);
-        });
-      },
-      back: () => {
-        if (isBrowser()) {
-          window.history.back();
-        }
-      },
-      forward: () => {
-        if (isBrowser()) {
-          window.history.forward();
-        }
-      },
-    }),
-    [navigate],
-  );
+  const router: Router = {
+    push: (to, options) => navigate(to, options),
+    replace: (to) => navigate(to, { replace: true }),
+    prefetch: async (to) => {
+      if (!isBrowser()) {
+        return;
+      }
+      const target = new URL(to, window.location.href);
+      const matched = matchRoute(routeTable().routes, target.pathname);
+      const load = matched?.route.page;
+      if (matched == null || load == null) {
+        return;
+      }
+      await Promise.all([
+        loadOnce(load),
+        ...matched.route.layouts.map((layout) => loadOnce(layout)),
+      ]);
+    },
+    refresh: async () => {
+      if (!isBrowser()) {
+        return;
+      }
+      const nextResolved = await resolveMatch(
+        routeTable(),
+        window.location.pathname + window.location.search,
+      );
+      // No view transition, and it is the one place that is right: a refresh
+      // is the same URL resolved again, so a transition would animate a page
+      // into itself — a cross-fade between two frames of the same thing,
+      // which is a flicker with a name.
+      startTransition(() => {
+        setResolved(nextResolved);
+      });
+    },
+    back: () => {
+      if (isBrowser()) {
+        window.history.back();
+      }
+    },
+    forward: () => {
+      if (isBrowser()) {
+        window.history.forward();
+      }
+    },
+  };
 
-  const value = useMemo<RouterState>(
-    () => ({ resolved, router, pending }),
-    [resolved, router, pending],
-  );
+  const value: RouterState = { resolved, router, pending };
   return <RouterContext.Provider value={value}>{children}</RouterContext.Provider>;
 }
 
@@ -2697,14 +2695,37 @@ function isExternal(to: string): boolean {
  * The argument documents where the routes live; the table itself is generated
  * from that directory at build time and installed by the entry that starts
  * the app, so the component only has to render it.
+ *
+ * # Why the render anchor is here
+ *
+ * `RenderProvider` fixes the render's instant, time zone and random seed once,
+ * writes them into the markup and reads them back on the client, which is what
+ * makes `useRenderedAt` and `useRandom` agree across hydration. An application
+ * that did not render one got no error — it got the old behaviour, which is a
+ * silent hydration mismatch in every page with a clock or a shuffle on it. A
+ * guarantee that depends on remembering to opt in is not one, so the router
+ * provides it and an application that wants different values *replaces* it by
+ * rendering its own inside this one. See ubugeeei-prod/uf#559.
+ *
+ * Above `RouterProvider` rather than below it, because the route's own
+ * modules — layouts as much as pages — are things that read a clock, and a
+ * masthead showing the time is the first component anybody writes that does.
+ *
+ * It is safe above a root layout that renders `<html>` only because the
+ * envelope's carrier is a `<meta>`: React hoists one into the head of a
+ * document it rendered, and to the front of a tree that is not one, where uf's
+ * shell lifts it into the head it wrote itself. `packages/hooks/render.js` has
+ * the argument, and it is the reason the carrier is no longer a `<script>`.
  */
 export function routerView(root: string): React.ComponentType<AppProps> {
   void root;
   component App(url: string, initial: ResolvedRoute) {
     return (
-      <RouterProvider url={url} initial={initial}>
-        <RouteView />
-      </RouterProvider>
+      <RenderProvider>
+        <RouterProvider url={url} initial={initial}>
+          <RouteView />
+        </RouterProvider>
+      </RenderProvider>
     );
   }
   return App;

package/middleware.js

@@ -38,9 +38,18 @@
 // `@uniflowed/server/host`, once per request, around everything that answers
 // it — and the guard, the handler or page underneath it, and the render all
 // see that one context. So `cookies()` in a guard and `cookies()` in the page
-// it guards are the same cookies, `draftMode().enable()` in a guard is visible
-// to what it guards, and every `after()` on the request is one ordered list
-// the host drains after the response has gone.
+// it guards are the same cookies, `draftMode().isEnabled` gives a guard and
+// the page under it the same answer, and every `after()` on the request is one
+// ordered list the host drains after the response has gone.
+//
+// *Changing* draft mode is not a guard's to do, and that is a separate rule
+// with a separate reason: `enable()` writes a cookie, a cookie is part of a
+// response, and a guard may decline — so a guard that turned draft mode on and
+// then let the request through would have made a decision with nowhere to be
+// written. `asResponder` marks the two calls that do own a response, a route
+// handler and a server action, and `draftMode().enable()` refuses anywhere
+// else by name. A guard that wants draft mode on answers with a redirect to
+// the handler that turns it on. See ubugeeei-prod/uf#282.
 //
 // It used to be the other way, and it is worth saying why that was wrong
 // rather than merely different: this module built its own context and drained
@@ -140,8 +149,8 @@ export function createMiddlewareRunner(options: {|
       const middleware = pick(await record.load(), record.file);
       // In the host's context, not one of this module's own. Two middleware on
       // the same path see the same cookies, and so does the handler or the page
-      // underneath them: `draftMode().enable()` in a guard is visible to what
-      // it guards, and every `after()` on the request lands in one ordered list
+      // underneath them: `draftMode().isEnabled` is one answer for the whole
+      // request, and every `after()` on the request lands in one ordered list
       // that the host drains once, after the response has gone.
       const result = await middleware(request, { params, searchParams: url.searchParams });
       if (result != null) {

package/package.json

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