@uniflowed/router 0.0.0-alpha.18 → 0.0.0-alpha.21

package/internal/runtime.js

@@ -36,10 +36,39 @@ import { flushSync } from "react-dom";
 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`]
+// head and into the tree with ubugeeei-prod/uf#373 — see [`payloadElements`]
 // — so the module that renders it is this one rather than `../server.js`.
 import { DATA_ID } from "./document.js";
 
+// The payload the loader's answer is written as, and the rows it defers. Row 0
+// is the element `DATA_ID` names and is byte-identical to what this file wrote
+// inline before the payload existed whenever nothing is deferred; a promise
+// anywhere in the data turns into a reference and a row of its own. See
+// `./payload.js` for the format and ubugeeei-prod/uf#519 for the half of it
+// that is still an element payload rather than a data one.
+import {
+  type PayloadRowMessage,
+  PayloadRowError,
+  encodePayload,
+  encodeRowValue,
+  payloadJson,
+} from "./payload.js";
+
+// The development-only half of [`RouteView`]: the marks that say which DOM
+// subtree each boundary owns, and the report that reads them. Every reference
+// to it is inside a `BOUNDARY_MARKS` branch, which is why a static import is
+// safe here where `../client.js` needs a dynamic one — a component cannot be
+// awaited in the middle of a render, and `false` folds the references away
+// before the bundler is asked to keep the module. See [`BOUNDARY_MARKS`].
+import {
+  BoundaryReporter,
+  ROOT_ERROR_ID,
+  ROUTE_ERROR_ID,
+  insideBoundary,
+  routeBoundaries,
+  suspenseId,
+} from "./boundaries.js";
+
 /** One parameter a route path captures. */
 export type RouteParamSpec = {| readonly name: string, readonly catchAll: boolean |};
 
@@ -90,11 +119,24 @@ type PageRenderProps = {|
   readonly data: mixed,
 |};
 
-/** The props `RouteView` gives each layout, outermost first. */
-type LayoutRenderProps = {|
+/**
+ * The props `RouteView` gives each layout, outermost first.
+ *
+ * Inexact, and that is the parallel routes reaching the type: a layout on a
+ * segment that declares `@team` is handed a `team` prop beside `children`, and
+ * the names are the project's rather than this file's. Every extra prop is a
+ * `React.Node` — a rendered slot, or `null` when the URL addressed neither the
+ * slot's routes nor a `$default.js`.
+ *
+ * The exactness is not lost so much as moved: what a layout may be *given* is
+ * open, and what it *declares* is still its own exact props type, which is
+ * where a typo in a slot name shows up.
+ */
+type LayoutRenderProps = {
   readonly params: RouteParams,
   readonly children: React.Node,
-|};
+  ...
+};
 
 /** What a page module may export. The component is `default` or `Page`. */
 export type PageModule = {
@@ -405,24 +447,99 @@ export type RouteRecord = {|
   /**
    * The `<Suspense>` boundaries this route renders inside, root first.
    *
-   * Optional because a table written before `_uf.loading.js` existed — a
+   * Optional because a table written before `$loading.js` existed — a
    * hand-written one in a test, a server bundle built by an older `uf` —
    * is still a table this router can render, and a route with no boundary is
    * exactly what it had before.
    */
   readonly loading?: $ReadOnlyArray<LoadingRecord>,
   /**
-   * The `_uf.template.js` wrappers this route renders inside, root first.
+   * The `$template.js` wrappers this route renders inside, root first.
    *
    * Optional for the reason `loading` is: a table written before templates
    * existed is still a table this router can render, and a route with no
    * template renders exactly the tree it did before.
    */
   readonly templates?: $ReadOnlyArray<TemplateRecord>,
+  /**
+   * The parallel-route slots in scope on this route, outermost first.
+   *
+   * Optional for the reason `templates` is. A route with no slot renders
+   * exactly the tree it did before slots existed, which is most routes.
+   */
+  readonly slots?: $ReadOnlyArray<SlotRecord>,
 |};
 
 /**
- * One `_uf.template.js`, as the route table carries it.
+ * One parallel-route slot, as the route table carries it.
+ *
+ * A slot is a second thing a layout renders. `app/dashboard/@team/` gives
+ * `app/dashboard/$layout.js` a `team` prop beside `children`, and the slot's
+ * pages are matched against the same URL the page is: `/dashboard/members`
+ * renders `app/dashboard/members/$page.js` as `children` and
+ * `app/dashboard/@team/members/$page.js` as `team`, at once, each inside its
+ * own layouts.
+ *
+ * A slot never adds a URL — the directory contributes no path segment — so
+ * `routes` here is a second table matched against paths the main table already
+ * defines. That is uf's answer to the question Next.js answers with a
+ * `default.js` for `children`: there is no such thing, because `children` is
+ * the page the URL matched and a URL that matches no page is a 404.
+ *
+ * `above` is how many of the route's `layouts` are outside the slot, so
+ * `layouts[above - 1]` is the one that receives it — the same number, spelled
+ * the same way, as [`TemplateRecord`]'s and [`LoadingRecord`]'s.
+ */
+export type SlotRecord = {|
+  readonly name: string,
+  readonly above: number,
+  /**
+   * `$default.js`: what this slot renders when the URL matches none of its
+   * routes.
+   *
+   * `null` for a slot that declares none, and then the slot renders nothing at
+   * all. That is what an unaddressed slot does on a soft navigation in Next.js
+   * too, and it is the honest answer for a slot that only some URLs have
+   * something to put in — a modal, a detail pane.
+   */
+  readonly defaultPage: ?() => Promise<PageModule>,
+  /** The default's source path, for diagnostics; absent when there is none. */
+  readonly defaultFile?: string,
+  /** Whether that default is MDX content. */
+  readonly defaultMdx?: boolean,
+  readonly routes: $ReadOnlyArray<SlotRouteRecord>,
+|};
+
+/**
+ * One page inside a slot.
+ *
+ * A [`RouteRecord`] without the parts a slot does not have. No `loading` and no
+ * `templates`: those belong to the segment, and they already wrap the layout
+ * the slot renders into. Per-slot boundaries are the part of parallel routes uf
+ * has not built, and `@uniflowed/vite`'s scan refuses the files rather than
+ * leaving them unopened — see ubugeeei-prod/uf#267.
+ *
+ * `page` is required, unlike a `RouteRecord`'s: a slot route that ships no
+ * client page has no URL of its own to hand the browser, so there would be
+ * nothing to do with the entry. The client table drops the whole route when its
+ * page is dropped, slots and all.
+ *
+ * `layouts` are the layouts *inside* the slot, and `slots` are the slots a
+ * layout inside this one declares — the recursion is the feature rather than a
+ * special case.
+ */
+export type SlotRouteRecord = {|
+  readonly path: string,
+  readonly params: $ReadOnlyArray<RouteParamSpec>,
+  readonly mdx: boolean,
+  readonly file: string,
+  readonly page: () => Promise<PageModule>,
+  readonly layouts: $ReadOnlyArray<() => Promise<LayoutModule>>,
+  readonly slots: $ReadOnlyArray<SlotRecord>,
+|};
+
+/**
+ * One `$template.js`, as the route table carries it.
  *
  * The same shape as [`LoadingRecord`] and the same `above`, because it answers
  * the same question — where in the stack of layouts this thing sits — and
@@ -434,7 +551,7 @@ export type TemplateRecord = {|
 |};
 
 /**
- * One `_uf.loading.js`, as the route table carries it.
+ * One `$loading.js`, as the route table carries it.
  *
  * `above` is how many of the route's `layouts` are outside the boundary, which
  * is the same number `ResolvedRoute["errorBoundary"].above` means and is
@@ -450,7 +567,7 @@ export type LoadingRecord = {|
  * One not-found boundary: the page for a path under `path` that matched
  * nothing.
  *
- * `_uf.not-found.js` is a segment file, so `path` is the route path of the
+ * `$not-found.js` is a segment file, so `path` is the route path of the
  * directory that declares it and `layouts` are the layouts in scope *there* —
  * which is what the boundary renders inside. A project with one at the router
  * root has one of these; a project whose manual answers its own 404 has two.
@@ -461,7 +578,7 @@ export type NotFoundBoundary = {|
   readonly file: string,
   /**
    * The page this boundary renders — `null` for the one the build synthesises
-   * at the router root when a project declares no `_uf.not-found.js` there.
+   * at the router root when a project declares no `$not-found.js` there.
    *
    * A project that had declared none used to get `layouts: []` along with the
    * framework's page: not the nearest-ancestor rule failing, but the fallback
@@ -516,8 +633,8 @@ export type RouteMatch = {|
  * `unauthorized()` are not different *kinds* of file to write; they are
  * different sentences an error page says, and `match` over this is where a
  * page says all three and the checker confirms it covered them. Deciding it
- * the other way — `_uf.forbidden.js` and `_uf.unauthorized.js` beside
- * `_uf.error.js`, which is what Next.js does — is three files per segment to
+ * the other way — `$forbidden.js` and `$unauthorized.js` beside
+ * `$error.js`, which is what Next.js does — is three files per segment to
  * express one thing, and nothing would check that any of them handled the
  * case it was named for.
  *
@@ -563,7 +680,7 @@ export type ResolvedRoute = {|
    * to a question the router asked, so it says so.
    *
    * Set only by a streaming render of a route that declares a
-   * `_uf.loading.js` and generates no metadata from its data — the two
+   * `$loading.js` and generates no metadata from its data — the two
    * conditions under which deferring buys anything and costs nothing that was
    * not already spent. [`resolveRoute`] is where that is decided and argued.
    */
@@ -590,7 +707,7 @@ export type ResolvedRoute = {|
    * The boundary that would catch a throw while rendering this route.
    *
    * Always present, because every route has an answer for a throw: `module`
-   * is `null` when the project declares no `_uf.error.js` above the path, and
+   * is `null` when the project declares no `$error.js` above the path, and
    * the framework's own error page renders instead. `above` is how many of
    * `layouts` are outside the boundary — the ones that stay mounted, which is
    * what "the rest of the document is still interactive" means.
@@ -605,14 +722,14 @@ export type ResolvedRoute = {|
    * Imported rather than lazy: React decides to render a fallback
    * synchronously, during the render that suspended, so a module that is still
    * being fetched is a module that is not there at the only moment it is
-   * wanted. Empty for a route with no `_uf.loading.js` above it, which is the
+   * wanted. Empty for a route with no `$loading.js` above it, which is the
    * ordinary case and renders exactly the tree it did before.
    */
   readonly loading: $ReadOnlyArray<{| readonly above: number, readonly module: LoadingModule |}>,
   /**
    * The templates around this route, root first, already imported.
    *
-   * Empty for a route with no `_uf.template.js` above it, which is the
+   * Empty for a route with no `$template.js` above it, which is the
    * ordinary case and renders exactly the tree it did before templates
    * existed. Empty too on a resolution that *is* a boundary — a not-found or
    * an error page — for the reason its `loading` is: those are matched rather
@@ -623,6 +740,36 @@ export type ResolvedRoute = {|
     readonly above: number,
     readonly module: TemplateModule,
   |}>,
+  /**
+   * The slots this route renders, outermost first, already imported.
+   *
+   * Empty for a route with no slot above it, and empty on a resolution that
+   * *is* a boundary — a not-found or an error page — for the reason its
+   * `templates` is: a boundary is matched rather than walked to, and a slot
+   * belongs to the segment the walk went through.
+   */
+  readonly slots: $ReadOnlyArray<ResolvedSlot>,
+|};
+
+/**
+ * One slot, matched against the URL and imported.
+ *
+ * `page` is `null` for a slot the URL addressed and that declares no
+ * `$default.js`, and the layout receives `null` rather than nothing at all:
+ * a layout that declares a slot always gets that prop, so a project can write
+ * `{team ?? <Empty />}` and mean it.
+ *
+ * `params` are the slot's own. A slot matches the same URL by its own patterns,
+ * so `@team/[member]` captures `member` while the page beside it captures
+ * nothing — which is the point of matching twice rather than sharing one match.
+ */
+export type ResolvedSlot = {|
+  readonly name: string,
+  readonly above: number,
+  readonly page: ?PageModule,
+  readonly params: RouteParams,
+  readonly layouts: $ReadOnlyArray<LayoutModule>,
+  readonly slots: $ReadOnlyArray<ResolvedSlot>,
 |};
 
 /** Thrown by `notFound()`; the renderer answers with the not-found page. */
@@ -818,8 +965,25 @@ export function hasClientPage(route: RouteRecord): boolean {
  * Match a pathname against the table, preferring the most specific route.
  */
 export function matchRoute(routes: $ReadOnlyArray<RouteRecord>, pathname: string): ?RouteMatch {
+  return matchIn(routes, pathname);
+}
+
+/**
+ * The same match, over anything that has a route path.
+ *
+ * A slot is a second table matched against the same URL — see [`SlotRecord`] —
+ * and it has to be matched by *this* function rather than by one of its own:
+ * two matchers would be two answers to "which of these paths does this URL
+ * name", and the one that disagreed would show up as a slot holding somebody
+ * else's page. The generic is only about the record type; the ranking, the
+ * parameters and the tie-break are the route table's.
+ */
+function matchIn<TRecord: { +path: string, ... }>(
+  routes: $ReadOnlyArray<TRecord>,
+  pathname: string,
+): ?{| readonly route: TRecord, readonly params: RouteParams |} {
   const parts = pathname.split("/").filter((part) => part !== "");
-  let best: ?RouteMatch = null;
+  let best: ?{| readonly route: TRecord, readonly params: RouteParams |} = null;
   let bestScore = -1;
   for (const route of routes) {
     const segments = compile(route.path);
@@ -862,7 +1026,7 @@ function covers(segments: $ReadOnlyArray<Segment>, parts: $ReadOnlyArray<string>
 /**
  * The nearest boundary above `pathname`, or `null` when none covers it.
  *
- * The one rule both `_uf.not-found.js` and `_uf.error.js` are resolved by, and
+ * The one rule both `$not-found.js` and `$error.js` are resolved by, and
  * the same one layouts already follow: nearest means the longest path that
  * covers the URL. It is decided here rather than by the table's order — the
  * table is sorted by path so the generated module is stable, and a resolver
@@ -1059,6 +1223,11 @@ async function resolveRoute(
   // depends on nothing the loader produces.
   const loading = resolveLoading(matched.route, matched.route.layouts.length);
   const templates = resolveTemplates(matched.route, matched.route.layouts.length);
+  // Started alongside and awaited at the end, for the reason the boundaries
+  // are: a slot is matched against the URL and depends on nothing the loader
+  // produces, so the second match and its imports overlap the first page's
+  // loader rather than following it.
+  const slots = resolveSlots(matched.route.slots ?? [], pathname, matched.route.layouts.length);
 
   // The loader, run here and awaited below — or not awaited at all.
   //
@@ -1066,7 +1235,7 @@ async function resolveRoute(
   // on its loader could not, because this function awaited the loader before it
   // returned and by the time React saw the tree the data was already in hand.
   // The fallback beside such a page showed for zero milliseconds, which made
-  // `_uf.loading.js` useful for the one case a page usually is not slow for.
+  // `$loading.js` useful for the one case a page usually is not slow for.
   //
   // Two things stand in the way of simply not awaiting, and both are about the
   // document rather than about the route. Metadata goes in the head and the
@@ -1120,9 +1289,141 @@ async function resolveRoute(
     errorBoundary: await boundary,
     loading: await loading,
     templates: await templates,
+    slots: await slots,
+  };
+}
+
+/**
+ * The route's slots, matched against the URL and imported.
+ *
+ * The second matching pass parallel routes are, and it is a pass rather than a
+ * branch of the first: a slot has its own patterns over the same path, so
+ * `/dashboard/members` can be `[member]` to one slot, a static segment to
+ * another and nothing at all to a third, at once.
+ *
+ * A slot that will not load renders nothing rather than taking the page with
+ * it, which is the judgement `resolveTemplates` and `resolveLoading` already
+ * make: a slot is a second thing beside the page, and a broken second thing
+ * must not become a broken route. The entry stays in the list with `page:
+ * null`, so the layout still receives the prop it declares.
+ */
+async function resolveSlots(
+  records: $ReadOnlyArray<SlotRecord>,
+  pathname: string,
+  layoutCount: number,
+): Promise<$ReadOnlyArray<ResolvedSlot>> {
+  if (records.length === 0) {
+    return [];
+  }
+  return Promise.all(records.map((record) => resolveSlot(record, pathname, layoutCount)));
+}
+
+async function resolveSlot(
+  record: SlotRecord,
+  pathname: string,
+  layoutCount: number,
+): Promise<ResolvedSlot> {
+  // Clamped exactly as a template's `above` is, and for the same reason: a
+  // hand-written table, or a `(group)` between the layout and the route, can
+  // leave a route with fewer layouts than the slot was declared above.
+  const above = Math.min(record.above, layoutCount);
+  const empty: ResolvedSlot = {
+    name: record.name,
+    above,
+    page: null,
+    params: {},
+    layouts: [],
+    slots: [],
+  };
+
+  const matched = matchIn(record.routes, pathname);
+  if (matched == null) {
+    // The URL says nothing about this slot. `$default.js` is what it says
+    // instead, and a slot that declares none renders nothing at all.
+    const load = record.defaultPage;
+    if (load == null) {
+      return empty;
+    }
+    const module = await loadOrNull(load);
+    if (module == null) {
+      return empty;
+    }
+    return { ...empty, page: withoutLoader(module, record.defaultFile ?? record.name) };
+  }
+
+  const route = matched.route;
+  // Started together and awaited apart, so the two `await`s are not a
+  // waterfall and each keeps the type its loader had.
+  const pending = loadOrNull(route.page);
+  const pendingLayouts = Promise.all(route.layouts.map((layout) => loadOrNull(layout)));
+  const page = await pending;
+  const layouts = await pendingLayouts;
+  if (page == null) {
+    return empty;
+  }
+  const loaded = layouts.filter(Boolean);
+  if (loaded.length !== layouts.length) {
+    return empty;
+  }
+  return {
+    name: record.name,
+    above,
+    page: withoutLoader(page, route.file),
+    params: matched.params,
+    layouts: loaded,
+    // The slot's own layouts are what a nested slot is measured against, so
+    // the count handed down is this slot's rather than the route's.
+    slots: await resolveSlots(route.slots, pathname, loaded.length),
   };
 }
 
+/**
+ * A module, or `null` when it would not import.
+ *
+ * The judgement [`resolveTemplates`] and [`resolveLoading`] already make, at
+ * the granularity a slot needs it: a slot is a second thing beside the page, so
+ * a slot whose module is missing renders nothing rather than taking the route
+ * down with it — and the import error surfaces where it belongs, the next time
+ * the module is asked for.
+ */
+async function loadOrNull<TModule>(load: () => Promise<TModule>): Promise<?TModule> {
+  try {
+    return await loadOnce(load);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The same page module, having said out loud that a slot's loader does not run.
+ *
+ * A slot page is a component. It is *not* handed data, and this throws rather
+ * than passing `undefined` to a page that asked for some, because a slot whose
+ * loader is quietly skipped is exactly the failure ubugeeei-prod/uf#267 is
+ * about — a file written to a convention, and nothing that reads it.
+ *
+ * Why not run it. A page's loader answer is embedded in the document for the
+ * browser to hydrate from, once, under one id; a slot's would have nowhere to
+ * go, so it would run on the server and again in the browser on the way in.
+ * That is not merely two fetches: a loader that reads `cookies()` succeeds on
+ * the server and throws in the browser, and the slot would render on one side
+ * and not the other — a hydration mismatch produced by the router. So the rule
+ * is the narrow one, and lifting it means embedding per-slot data, which is
+ * named in the issue as what is left.
+ */
+function withoutLoader(module: PageModule, file: string): PageModule {
+  if (typeof module.loader === "function") {
+    throw new Error(
+      `@uniflowed/router: ${file} is inside a \`@slot\` and exports a \`loader\`, which the ` +
+        "router does not run — a slot's data has nowhere to be embedded for hydration, so it " +
+        "would be fetched again in the browser and a server-only loader would render one tree " +
+        "on the server and another in the page. Fetch inside the component, or move the data to " +
+        "the page the URL names. https://github.com/ubugeeei-prod/uf/issues/267",
+    );
+  }
+  return module;
+}
+
 /**
  * The route's templates, imported.
  *
@@ -1352,6 +1653,11 @@ async function resolveError(
     // show, which is worse than none.
     loading: [],
     templates: [],
+    // And slots for the third time: a slot belongs to the segment the walk went
+    // through, and an error page is matched rather than walked to. A layout
+    // that declares one is still mounted above the boundary, holding the slot
+    // it was rendered with — the boundary replaces what is under it.
+    slots: [],
   };
 }
 
@@ -1363,13 +1669,13 @@ async function resolveError(
  * Taking the matched route's layouts was the other candidate and it is wrong
  * in both directions: for an unmatched URL there is no matched route to take
  * them from, and for `notFound()` thrown from a page they would keep the
- * layouts *below* the boundary — so `app/guide/[slug]/_uf.layout.js` would
- * wrap a 404 that `app/guide/_uf.not-found.js` answered, which is the layout
+ * layouts *below* the boundary — so `app/guide/[slug]/$layout.js` would
+ * wrap a 404 that `app/guide/$not-found.js` answered, which is the layout
  * of the page that just said it does not exist.
  *
  * # The record with no page
  *
- * A project that declares no `_uf.not-found.js` anywhere still has a record —
+ * A project that declares no `$not-found.js` anywhere still has a record —
  * the one the build synthesises for the router root — and it names the root's
  * layouts and no module. Before that record existed this function answered
  * with `layouts: []`, so a site whose root layout owns the masthead, the
@@ -1423,6 +1729,8 @@ async function resolveNotFound(
     loading: [],
     // Templates are accumulated on that same walk, and for the same reason.
     templates: [],
+    // Slots too: a URL that matched no route addressed no slot either.
+    slots: [],
   };
 }
 
@@ -1520,7 +1828,7 @@ function errorTitle(error: RouteError): string {
 }
 
 /**
- * The framework's error page, for a project that declares no `_uf.error.js`.
+ * The framework's error page, for a project that declares no `$error.js`.
  *
  * It says which of the three happened and offers the reset, and it does *not*
  * print the thrown error: on the server that message is written for whoever
@@ -1687,7 +1995,7 @@ class RouteErrorBoundary extends React.Component<RouteErrorBoundaryProps, RouteE
 //
 // The cost is real and worth stating rather than discovering. Inside a
 // transition the commit is synchronous, so a route that suspends *while
-// rendering* shows its `_uf.loading.js` fallback instead of leaving the
+// rendering* shows its `$loading.js` fallback instead of leaving the
 // previous page up until it resolves. Its modules and its loader are already
 // finished by this point — `resolveMatch` awaited both — so what is left is a
 // component suspending on something else, and it degrades to the fallback the
@@ -1854,10 +2162,19 @@ export type RouteInfo = {|
   readonly pending: boolean,
 |};
 
+/**
+ * What this application does when a visitor follows a link.
+ *
+ * `app.rendering.navigation` in `uf.config.js`, and the same two words: the
+ * client router takes the link over, or the browser does.
+ */
+export type Navigation = "client" | "document";
+
 type RouterState = {|
   readonly resolved: ResolvedRoute,
   readonly router: Router,
   readonly pending: boolean,
+  readonly navigation: Navigation,
 |};
 
 const RouterContext: React.Context<?RouterState> = createContext(null);
@@ -1865,6 +2182,38 @@ const RouterContext: React.Context<?RouterState> = createContext(null);
 /** The route table the application was started with. */
 let installedTable: ?RouteTable = null;
 
+/**
+ * How the application navigates, installed by the entry that started it.
+ *
+ * Module state beside `installedTable`, and for the same reason: the entry is
+ * the only thing that knows, and every component that needs the answer is
+ * somewhere under a `RouterProvider` it did not construct. `routerView` builds
+ * that provider from two props the server handed it, and threading a third one
+ * from the entry through the application root would have made every
+ * hand-written `<App>` in a test a place the default lives.
+ *
+ * `"client"` until something says otherwise, which is what every uf
+ * application did before `app.rendering.navigation` existed and what a test
+ * that renders `routerView` directly still gets.
+ */
+let installedNavigation: Navigation = "client";
+
+/**
+ * Say how this application navigates. Called once, by the client entry.
+ *
+ * `@uniflowed/vite` generates the call into `virtual:uf/client` from
+ * `app.rendering.navigation`; nothing else should call it, and calling it after
+ * the first render is a change no rendered `Link` will notice.
+ */
+export function installNavigation(navigation: Navigation): void {
+  installedNavigation = navigation;
+}
+
+/** How this application navigates. */
+export function navigationMode(): Navigation {
+  return installedNavigation;
+}
+
 /** Register the generated route table. Called once by the client and server entries. */
 export function installRoutes(table: RouteTable): void {
   installedTable = table;
@@ -1911,10 +2260,31 @@ function isBrowser(): boolean {
  * provider listens to history and to `Link` clicks; a navigation resolves the
  * next route (loading its chunks and running its loader) *before* committing,
  * inside a transition, so the previous page stays interactive meanwhile.
+ *
+ * # Unless the application asked the browser to do it
+ *
+ * Under `app.rendering.navigation: "document"` every one of those sentences
+ * stops being true, and the provider is still here: the tree below it still
+ * reads `useRoute`, still renders `<RouteView>`, and still hydrates whatever
+ * `"use client"` boundary made the document interactive. What it does not do is
+ * take the link over. `navigate` hands the URL to the browser, no `popstate`
+ * listener is installed, and `prefetch` — which exists to load the chunks of a
+ * route this page will render — has no page to load them for.
+ *
+ * That is one branch rather than a second provider because the two differ in
+ * what happens on a click and in nothing else. A second implementation would
+ * have had to keep `resolved`, `pending`, the context and every hook that
+ * reads it in step with this one, which is four things to keep in step for one
+ * that actually differs.
  */
 export component RouterProvider(url: string, initial: ResolvedRoute, children: React.Node) {
   const [resolved, setResolved] = useState<ResolvedRoute>(initial);
   const [pending, setPending] = useState<boolean>(false);
+  // Read once per render rather than per navigation: it is installed by the
+  // entry before the first render and never changes after it, and a `Link`
+  // that asked at click time would be asking a question whose answer decided
+  // what it rendered.
+  const navigation = navigationMode();
 
   const navigate = async (to: string, options?: NavigateOptions): Promise<void> => {
     if (!isBrowser()) {
@@ -1922,6 +2292,19 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
     }
     const target = new URL(to, window.location.href);
     const next = target.pathname + target.search;
+    // The browser's job in this application. `assign` and `replace` rather
+    // than the history API, because the point is a document request: the
+    // history entry, the scroll position, the `Referer` and the unload
+    // handlers are then the browser's, done the way they are done for a link
+    // in a page with no JavaScript on it at all.
+    if (navigation === "document") {
+      if (options?.replace === true) {
+        window.location.replace(target.href);
+      } else {
+        window.location.assign(target.href);
+      }
+      return;
+    }
     // The half of the split that is not about bytes. A route whose page is not
     // in this bundle is not a route this router can render, and pretending
     // otherwise is the silent break: the navigation would resolve to nothing
@@ -1971,6 +2354,15 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
     if (!isBrowser()) {
       return undefined;
     }
+    // Nothing pushed a history entry, so there is nothing to pop back into: a
+    // document-navigating application left this page when the link was
+    // followed, and the back button asks the browser for the previous document
+    // rather than asking this listener to rebuild it. Installing one anyway
+    // would put a `resolveMatch` on the back button of a page that is about to
+    // be replaced by the one the browser already has.
+    if (navigation === "document") {
+      return undefined;
+    }
     const onPopState = () => {
       const next = window.location.pathname + window.location.search;
       // Back into a route this bundle has no page for. The history entry is
@@ -2000,7 +2392,12 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
     push: (to, options) => navigate(to, options),
     replace: (to) => navigate(to, { replace: true }),
     prefetch: async (to) => {
-      if (!isBrowser()) {
+      // A prefetch loads the modules the *next render* will need, and under
+      // document navigation there is no next render in this page: the browser
+      // fetches a document and throws this one away. Loading the chunks would
+      // be bytes spent on a page that is leaving, so this declines rather than
+      // warming a cache nothing reads.
+      if (!isBrowser() || navigation === "document") {
         return;
       }
       const target = new URL(to, window.location.href);
@@ -2018,6 +2415,14 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
       if (!isBrowser()) {
         return;
       }
+      // The same URL, rendered again — which under document navigation is what
+      // the browser calls a reload. Resolving it in the page instead would
+      // re-run the loader and commit a tree whose links this application has
+      // already said it does not drive.
+      if (navigation === "document") {
+        window.location.reload();
+        return;
+      }
       const nextResolved = await resolveMatch(
         routeTable(),
         window.location.pathname + window.location.search,
@@ -2042,7 +2447,7 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
     },
   };
 
-  const value: RouterState = { resolved, router, pending };
+  const value: RouterState = { resolved, router, pending, navigation };
   return <RouterContext.Provider value={value}>{children}</RouterContext.Provider>;
 }
 
@@ -2119,6 +2524,25 @@ export hook useLoaderData(): mixed {
   return useResolvedData(useRouterState().resolved);
 }
 
+/**
+ * Whether this bundle marks the boundaries it renders.
+ *
+ * `import.meta.hot` is the same gate `../client.js` uses for the hydration
+ * report and the DevTools check, chosen there for the reason it is chosen here:
+ * Vite defines it while serving and replaces it with `undefined` in a build, so
+ * every branch below is statically dead in a production bundle and the module
+ * behind it — `@uniflowed/router` is `sideEffects: false` — is dropped rather
+ * than shipped unused. Node leaves it undefined, so a host that imports this
+ * file without a bundler gets the production path, and so does the test suite.
+ *
+ * It is a module constant rather than a per-render question because the branch
+ * has to be foldable, and it may answer differently in the browser and on the
+ * server without costing anything: a mark renders nothing until it has mounted,
+ * so neither the server's markup nor the tree React hydrates against it can
+ * contain one. See `./boundaries.js`, which has the argument.
+ */
+const BOUNDARY_MARKS: boolean = import.meta.hot != null;
+
 /**
  * Renders the matched page inside its layouts, innermost last, with the
  * document metadata as hoistable head elements.
@@ -2135,7 +2559,7 @@ export hook useLoaderData(): mixed {
  * # Where the error boundaries go
  *
  * Two, and they are not the same thing twice. The inner one is the project's
- * `_uf.error.js`, placed at the depth the file sits at, so the layouts above
+ * `$error.js`, placed at the depth the file sits at, so the layouts above
  * it stay mounted and interactive while the subtree below is replaced — that
  * placement *is* the feature. The outer one has no module and so renders the
  * framework's page; it is what stands between a throw in a root layout, or in
@@ -2149,7 +2573,7 @@ export hook useLoaderData(): mixed {
  * everything under it, which is what makes the shell arrive first: a renderer
  * streaming this tree can send every layout down to the boundary, and the
  * fallback, before whatever the page is waiting for has resolved. A segment
- * with no `_uf.loading.js` contributes no boundary at all — it is not wrapped
+ * with no `$loading.js` contributes no boundary at all — it is not wrapped
  * in a `<Suspense fallback={null}>` on the way past — so a project that
  * declares none renders the tree it rendered before this existed, and a page
  * that suspends without a boundary above it still fails the way React says it
@@ -2168,11 +2592,33 @@ export hook useLoaderData(): mixed {
  * with opposite answers to one question, so they are one line apart here, and
  * the whole of the difference is the `key` — see [`insideTemplates`], which is
  * that line's other half.
+ *
+ * # Where the boundary marks go
+ *
+ * Inside each boundary and around nothing else, under `uf dev` only. A
+ * `<Suspense>` and a class boundary each render no element of their own, so the
+ * run of nodes one owns is indistinguishable on the page from the layout's own
+ * nodes beside it — the marks are what distinguish it, and this loop is the
+ * only place that knows which boundary is which. `./boundaries.js` has the
+ * mechanism and the argument; every reference to it here is inside a
+ * [`BOUNDARY_MARKS`] branch, so a build has none of it. See
+ * ubugeeei-prod/uf#520.
  */
 export component RouteView() {
   const { resolved } = useRouterState();
   const { module, above } = resolved.errorBoundary;
   const loader = resolved.deferred;
+  // The route's boundaries, named once and read by both the marks below and the
+  // report that watches them. `installedTable` rather than [`routeTable`],
+  // which throws: a test may render this view without an entry having installed
+  // a table, and an error boundary named by its depth alone is worth less than
+  // one named by its file rather than wrong.
+  const marks = BOUNDARY_MARKS
+    ? routeBoundaries(
+        resolved,
+        nearestBoundary(installedTable?.errors ?? [], resolved.pathname)?.file,
+      )
+    : null;
   // The innermost element, so the `use` inside `AwaitedPage` suspends below
   // every boundary the loop below adds — which is what makes the layouts and
   // the fallback the shell rather than something waiting behind the loader.
@@ -2190,12 +2636,16 @@ export component RouteView() {
         continue;
       }
       const Fallback = loadingComponent(boundary.module);
-      element = <Suspense fallback={<Fallback />}>{element}</Suspense>;
+      element = (
+        <Suspense fallback={<Fallback />}>
+          {BOUNDARY_MARKS ? insideBoundary(marks?.get(suspenseId(index)), element) : element}
+        </Suspense>
+      );
     }
     // Placed on `above` alone, and not on there being a module: a `null` one is
     // the framework's own error page, and where it renders is exactly the
     // question ubugeeei-prod/uf#351 asks. A project that declares no
-    // `_uf.error.js` has the record the build synthesises for the router root,
+    // `$error.js` has the record the build synthesises for the router root,
     // whose `above` is the root's layouts — so the framework's page appears
     // inside the masthead rather than in place of the document. A table with no
     // record at all answers 0, which puts this boundary outside every layout,
@@ -2207,22 +2657,42 @@ export component RouteView() {
     if (depth === above && resolved.error == null) {
       element = (
         <RouteErrorBoundary module={module} resetKey={resolved.pathname}>
-          {element}
+          {BOUNDARY_MARKS ? insideBoundary(marks?.get(ROUTE_ERROR_ID), element) : element}
         </RouteErrorBoundary>
       );
     }
     element = insideTemplates(element, resolved, depth);
     if (depth > 0) {
       const Layout = layoutComponent(resolved.layouts[depth - 1]);
-      element = <Layout params={resolved.params}>{element}</Layout>;
+      // The slots declared on this layout's own segment, beside `children`.
+      // Spread rather than passed as one `slots` object, because a slot is a
+      // prop a layout declares by name — `component Dashboard(children, team)`
+      // — and a bag would make every layout destructure a map to find out
+      // whether the router had anything for it.
+      // The spread first and `params` after it, so that a slot named after a
+      // prop the layout already has loses rather than wins. `@params` and
+      // `@children` are refused by the scan, and this is the second line of
+      // that defence for a table written by hand: losing a slot is a hole in
+      // the page, and overwriting `params` is every route in the segment
+      // rendering against the wrong parameters.
+      element = (
+        <Layout {...slotsAt(resolved.slots, depth)} params={resolved.params}>
+          {element}
+        </Layout>
+      );
     }
   }
   return (
     <>
       <Head metadata={resolved.metadata} />
       <RouteErrorBoundary module={null} resetKey={resolved.pathname}>
-        {element}
+        {BOUNDARY_MARKS ? insideBoundary(marks?.get(ROOT_ERROR_ID), element) : element}
       </RouteErrorBoundary>
+      {/* After the tree rather than before it, so its effect runs once every
+          mark below has had its own — which is the commit the marks are in. */}
+      {BOUNDARY_MARKS && marks != null ? (
+        <BoundaryReporter path={resolved.path} boundaries={marks} />
+      ) : null}
     </>
   );
 }
@@ -2238,6 +2708,12 @@ export component RouteView() {
  * innermost `<Suspense>` when the route deferred its loader on the server, and
  * exactly there again on the client, where the data is already in hand and
  * nothing suspends at all.
+ *
+ * "The loader's answer" is now a payload rather than a value, so what
+ * [`payloadElements`] renders is that script plus one boundary per value the
+ * answer deferred. The same argument covers all of them: the browser's copy of
+ * this component renders the same rows in the same places, from the values it
+ * read out of those very elements.
  */
 component RenderedPage(data: mixed) {
   const { resolved } = useRouterState();
@@ -2245,7 +2721,7 @@ component RenderedPage(data: mixed) {
   return (
     <>
       <Page params={resolved.params} searchParams={resolved.searchParams} data={data} />
-      {loaderDataScript(data)}
+      {payloadElements(data)}
     </>
   );
 }
@@ -2284,25 +2760,159 @@ component AwaitedPage(loader: Promise<mixed>) {
  *
  * `<` is escaped inside the JSON so a string holding `</script>` cannot end the
  * element early, and U+2028 and U+2029 because a JSON document is not
- * JavaScript source but is sometimes read as if it were.
+ * JavaScript source but is sometimes read as if it were — the escape moved to
+ * `./payload.js` when the model stopped being the only thing written that way.
  * `dangerouslySetInnerHTML` rather than a text child because React escapes a
  * text child and `&quot;` is not JSON any more. `security/no-dangerously-set-
  * inner-html` is about markup that came from somewhere and has to be sanitized
  * before a browser parses it as HTML; this is `JSON.stringify`'s output with
  * `<` escaped, in an element the browser never parses as HTML and never runs.
- * `docs/app/_uf.layout.js` carries the same suppression for the same reason.
+ * `docs/app/$layout.js` carries the same suppression for the same reason.
+ *
+ * # And the rows the model deferred
+ *
+ * A promise anywhere in the loader's answer used to be `JSON.stringify`'d to
+ * `{}`. It is now a `"$P<n>"` reference in the element above and a `<script
+ * data-uf-row="n">` of its own, inside a `<Suspense fallback={null}>` — which
+ * is what makes React stream it at the moment the promise settles rather than
+ * holding the document for it. Each row is its own boundary, so two deferred
+ * values arrive in the order they resolved in and not in the order they were
+ * written. `./payload.js` is the format; `./payload-rows.js` is the browser
+ * reading them back.
+ *
+ * The boundaries sit after the page rather than before it, where the data
+ * element already was. A page that suspends with no `$loading.js` above it
+ * holds the whole shell — that is React's rule and uf does not work around it
+ * — so the position buys nothing either way, and "the scripts are where the
+ * script was" is worth more than a rearrangement that is not.
+ *
+ * # Why the rows are inside an element
+ *
+ * Because a `<Suspense>` that is a direct child of the *render root* stops the
+ * shell being flushed at all. React's renderer can only write a segment once
+ * the segment is complete, and the root segment holds an unresolved boundary
+ * open: measured against React 19.2.8, a tree of `[<div>, <Suspense>]` writes
+ * its first byte when the boundary resolves, and the same tree with the
+ * boundary inside any host element writes it immediately. Every component
+ * between the root and here — `RenderProvider`, `RouterProvider`, `RouteView`,
+ * `RouteErrorBoundary` — renders no element of its own, so without this
+ * `<span>` the rows would be exactly that first shape and a payload would have
+ * streamed nothing.
+ *
+ * `hidden` because it holds no content a reader is meant to see: `<script
+ * type="application/json">` renders nothing either way, and the attribute is
+ * what says so to anything that inspects the document. One element for all the
+ * rows rather than one each — the boundaries inside it still resolve
+ * independently, since each is its own.
+ *
+ * The same rule catches a route whose `$loading.js` sits above no layout:
+ * `RouteView` puts that boundary in the same position, and it does not stream
+ * either. That is a bug this file did not introduce and does not fix; it is
+ * written down in ubugeeei-prod/uf#519 rather than left to be rediscovered.
  */
-function loaderDataScript(data: mixed): React.Node {
+function payloadElements(data: mixed): React.Node {
   if (data === undefined) {
     return null;
   }
-  const json = JSON.stringify(data)
-    .replace(/</g, "\\u003c")
-    .replace(/\u2028/g, "\\u2028")
-    .replace(/\u2029/g, "\\u2029");
-  const html = { __html: json };
+  const { model, rows } = encodePayload(data, "the route's loader data");
+  // Before anything renders, so a promise that has already rejected is one
+  // somebody is listening to. `settledRow` is memoized, so the components
+  // below get these same promises rather than a second set.
+  for (const row of rows) {
+    settledRow(row.value);
+  }
+  const html = { __html: payloadJson(model) };
   // uf-lint-disable-next-line security/no-dangerously-set-inner-html
-  return <script id={DATA_ID} type="application/json" dangerouslySetInnerHTML={html} />;
+  const row0 = <script id={DATA_ID} type="application/json" dangerouslySetInnerHTML={html} />;
+  return (
+    <>
+      {row0}
+      {rows.length === 0 ? null : (
+        <span hidden>
+          {rows.map((row) => (
+            <Suspense key={row.id} fallback={null}>
+              <PayloadRow id={row.id} value={row.value} />
+            </Suspense>
+          ))}
+        </span>
+      )}
+    </>
+  );
+}
+
+/**
+ * One deferred value, written when it settles.
+ *
+ * Rendered on both sides, which is the thing to keep in mind about it. On the
+ * server `value` is the loader's own promise; in the browser it is the promise
+ * `./payload-rows.js` created for this row and resolved out of this very
+ * element. Both then write the element from the settled result through the
+ * same [`payloadJson`], so the bytes agree and hydration has nothing to
+ * report. `encodeRowValue` is what re-applies the reference escape to a value
+ * the browser has already had it removed from.
+ *
+ * It never rejects. `use` on a rejected promise throws, and a throw here would
+ * put the *row's* boundary into the error boundary above it — which is the
+ * page, for a value the page may not even be reading. The failure travels as a
+ * row instead, and the page's own `use` of the same promise is what reaches
+ * the page's boundary, exactly as it would have without a payload.
+ */
+component PayloadRow(id: number, value: Promise<mixed>) {
+  const message = use(settledRow(value));
+  const html = { __html: payloadJson(message) };
+  return (
+    // uf-lint-disable-next-line security/no-dangerously-set-inner-html
+    <script type="application/json" data-uf-row={String(id)} dangerouslySetInnerHTML={html} />
+  );
+}
+
+/**
+ * The message a row will carry, as a promise that always fulfils.
+ *
+ * Keyed by the promise rather than recomputed, because `use` wants the same
+ * promise every render and a render is repeated: React renders a component
+ * again after it suspends, and Strict Mode renders it twice more. A `WeakMap`
+ * so a route that has navigated away takes its rows with it.
+ */
+const settledRows: WeakMap<Promise<mixed>, Promise<PayloadRowMessage>> = new WeakMap();
+
+function settledRow(value: Promise<mixed>): Promise<PayloadRowMessage> {
+  const existing = settledRows.get(value);
+  if (existing != null) {
+    return existing;
+  }
+  const settled = value.then(
+    (resolved) => ({ value: encodeRowValue(resolved, "a deferred value") }),
+    (error) => ({ error: rowFailure(error) }),
+  );
+  settledRows.set(value, settled);
+  return settled;
+}
+
+/**
+ * What a row says when the value failed.
+ *
+ * A fixed sentence in a build, and the error's own words where
+ * `import.meta.hot` says a developer is reading them — the same gate
+ * [`BOUNDARY_MARKS`] uses, and the same argument: a message that came out of a
+ * loader can name a table, a query or a file path, and a browser is not where
+ * any of those belong.
+ *
+ * A `PayloadRowError` short-circuits both, and has to. That error is what the
+ * browser's reader rejects with, carrying the row's own text, so echoing it is
+ * what makes the element the browser renders equal the one the server sent
+ * whichever of the two builds was the development one.
+ */
+const ROW_FAILURE = "@uniflowed/router: a deferred value failed on the server.";
+
+function rowFailure(error: mixed): string {
+  if (error instanceof PayloadRowError) {
+    return error.wire;
+  }
+  if (!BOUNDARY_MARKS) {
+    return ROW_FAILURE;
+  }
+  return error instanceof Error ? `${ROW_FAILURE} ${error.message}` : ROW_FAILURE;
 }
 
 /**
@@ -2359,7 +2969,7 @@ function insideTemplates(element: React.Node, resolved: ResolvedRoute, depth: nu
     }
     const Template = templateComponent(entry.module);
     // Keyed on the pathname, which is the whole difference between this file
-    // and `_uf.layout.js`: React throws the subtree away and builds it again
+    // and `$layout.js`: React throws the subtree away and builds it again
     // whenever the key changes, and a navigation that changes only the query
     // string leaves it alone.
     out = (
@@ -2371,6 +2981,79 @@ function insideTemplates(element: React.Node, resolved: ResolvedRoute, depth: nu
   return out;
 }
 
+/**
+ * The slots declared at `depth`, as the props the layout there receives.
+ *
+ * One object per layout rather than one lookup per slot, so the common case —
+ * a project with no slots at all — allocates nothing and spreads nothing.
+ *
+ * A slot the URL addressed and that has no `$default.js` is `null` rather
+ * than absent: a layout that declares `team` receives `team` on every route,
+ * so `{team ?? <Empty />}` is a thing a project can write and rely on.
+ */
+function slotsAt(
+  slots: $ReadOnlyArray<ResolvedSlot>,
+  depth: number,
+): { readonly [string]: React.Node } {
+  if (slots.length === 0) {
+    return EMPTY_SLOTS;
+  }
+  const props: { [string]: React.Node } = {};
+  for (const slot of slots) {
+    if (slot.above === depth) {
+      // `null` rather than an element that renders nothing, and the difference
+      // is the whole of what the prop is for: `{team ?? <Empty />}` has to be
+      // able to tell "this slot has nothing in it" from "this slot rendered
+      // something empty", and an element is never `null`.
+      props[slot.name] = slot.page == null ? null : <SlotView slot={slot} />;
+    }
+  }
+  return props;
+}
+
+/** One object for every layout on a project that declares no slot. */
+const EMPTY_SLOTS: { readonly [string]: React.Node } = Object.freeze({});
+
+/**
+ * One slot's tree: its page, inside the layouts declared under the slot, with
+ * the slots those layouts declare in turn.
+ *
+ * The same composition [`RouteView`] does and deliberately not the same
+ * function. A route's tree carries the things a slot does not have — the error
+ * boundary, the `<Suspense>` fallbacks, the templates, the head — and folding
+ * a second, simpler case into that loop would be four `if`s asking which of the
+ * two this is. What the two share is the *order*, page innermost and layouts
+ * backwards over a root-first list, and that is short enough to be right twice.
+ *
+ * A slot with no page is never rendered through this component at all —
+ * [`slotsAt`] hands the layout `null` instead, so the layout can tell an empty
+ * slot from one that rendered something empty. The guard below is what makes
+ * that a fact about one place rather than a convention two places share.
+ */
+component SlotView(slot: ResolvedSlot) {
+  // Before the early return, because a hook after one is a hook that runs on
+  // some renders and not others. The search string is the route's — a slot
+  // matches the path and the query belongs to the URL, not to either match.
+  const { resolved } = useRouterState();
+  const page = slot.page;
+  if (page == null) {
+    return null;
+  }
+  const Page = pageComponent(page);
+  let element: React.Node = (
+    <Page params={slot.params} searchParams={resolved.searchParams} data={undefined} />
+  );
+  for (let depth = slot.layouts.length; depth > 0; depth -= 1) {
+    const Layout = layoutComponent(slot.layouts[depth - 1]);
+    element = (
+      <Layout {...slotsAt(slot.slots, depth)} params={slot.params}>
+        {element}
+      </Layout>
+    );
+  }
+  return element;
+}
+
 /**
  * The component a template module renders: `default`, or the named `Template`.
  *
@@ -2501,7 +3184,7 @@ function jsonLdText(entry: JsonLd): string {
  * One JSON-LD object, as the element that carries it.
  *
  * A function rather than an element written inline, because the suppression
- * needs a line of its own; `docs/app/_uf.layout.js` has the same shape for the
+ * needs a line of its own; `docs/app/$layout.js` has the same shape for the
  * same reason. `security/no-dangerously-set-inner-html` is about markup that
  * came from somewhere and has to be sanitized before a browser parses it as
  * HTML, and its escape hatch is a `@uniflowed/markdown` sanitizer — the right
@@ -2682,6 +3365,22 @@ export type LinkPrefetch = "off" | "intent" | "render";
  * default) loads the destination's chunks on hover or focus, and
  * `transition={false}` makes this one navigation a cut — most navigations are
  * a link, so the opt-out in [`NavigateOptions`] has to be reachable from one.
+ *
+ * # Under `app.rendering.navigation: "document"` it is only the anchor
+ *
+ * No click handler of uf's, no `preventDefault`, no prefetch listeners: the
+ * element the browser gets is the one it would have got from `<a href>` in the
+ * source. That is the whole of what changing the mode does to a component,
+ * which is the point — a project moving between the two rewrites its
+ * `uf.config.js` and none of its pages, and a component library built on
+ * `Link` works in both without knowing which it is in.
+ *
+ * It matters that the handler is *absent* rather than a handler that calls
+ * `location.assign`. The two look the same for a left click and are not the
+ * same link: `preventDefault` and a scripted navigation lose `download`, lose
+ * a `target`, and change what the browser does with a middle click and with a
+ * gesture uf has not heard of. An ordinary link is not an approximation of an
+ * ordinary link.
  */
 export component Link(
   to: string,
@@ -2693,11 +3392,12 @@ export component Link(
   onClick?: (event: SyntheticMouseEvent<HTMLAnchorElement>) => mixed,
   ...rest: { readonly [string]: mixed }
 ) {
-  const router = useRouter();
+  const { router, navigation } = useRouterState();
   const prefetched = React.useRef(false);
+  const drives = navigation === "client";
 
   const doPrefetch = () => {
-    if (prefetch === "off" || prefetched.current || isExternal(to)) {
+    if (!drives || prefetch === "off" || prefetched.current || isExternal(to)) {
       return;
     }
     prefetched.current = true;
@@ -2733,14 +3433,18 @@ export component Link(
     });
   };
 
+  // The caller's own `onClick` still runs under document navigation — it is
+  // theirs, and an application that closes a menu when a link is clicked is
+  // not asking uf to take the navigation over — so it is passed through rather
+  // than dropped with the rest of the behaviour.
   return (
     <a
       {...rest}
       href={to}
       className={className}
-      onClick={handleClick}
-      onMouseEnter={prefetch === "intent" ? doPrefetch : undefined}
-      onFocus={prefetch === "intent" ? doPrefetch : undefined}
+      onClick={drives ? handleClick : onClick}
+      onMouseEnter={drives && prefetch === "intent" ? doPrefetch : undefined}
+      onFocus={drives && prefetch === "intent" ? doPrefetch : undefined}
     >
       {children}
     </a>