@uniflowed/router 0.0.0-alpha.1 → 0.0.0-alpha.11

package/internal/runtime.js

@@ -11,6 +11,7 @@
 
 import * as React from "react";
 import {
+  Suspense,
   createContext,
   startTransition,
   useCallback,
@@ -22,101 +23,350 @@ import {
 } from "react";
 
 /** One parameter a route path captures. */
-export type RouteParamSpec = {| +name: string, +catchAll: boolean |};
+export type RouteParamSpec = {| readonly name: string, readonly catchAll: boolean |};
 
 /** The parameters captured from a URL. A catch-all captures the rest as a list. */
-export type RouteParams = { +[string]: string | $ReadOnlyArray<string> };
+export type RouteParams = { readonly [string]: string | $ReadOnlyArray<string> };
 
 /** The query string, as a read-only map. */
-export type SearchParams = { +[string]: string };
+export type SearchParams = { readonly [string]: string };
+
+/**
+ * A component found in a route module.
+ *
+ * `React.ComponentType<empty>` is "some React component", and it is a claim
+ * rather than a shrug. `ComponentType` is contravariant in its props — Flow's
+ * library definition writes it `component(...P)` with `in P` — so `empty` is
+ * the *top* of the component types: every component is one, and nothing may be
+ * passed to one until a caller has said which props it is passing. That is
+ * exactly what is known here. The router finds these by dynamic import, and
+ * nobody has told it what a page's props are.
+ *
+ * It cannot be `React.ComponentType<PageRenderProps>`, the props the router
+ * actually passes, because Flow's `component` syntax gives a component *exact*
+ * props and a page is free to want none of them. This repository's own pages
+ * and layouts are `component NotFound()` and
+ * `component Layout(children: React.Node)`, and against the props the router
+ * hands them that reads:
+ *
+ *     error[incompatible-type]: property `data`, property `params`, and
+ *     property `searchParams` are extra in `PageRenderProps` but missing in
+ *     `props of component NotFound`. Exact objects do not accept extra props.
+ *
+ * React passing a component a prop it did not declare is allowed and always
+ * has been. `renderable` is the one line that says so.
+ */
+type RouteComponent = React.ComponentType<empty>;
+
+/**
+ * The props `RouteView` gives the page it renders.
+ *
+ * The same three as the public `PageProps` in `../index.js`, at the arguments
+ * the runtime instantiates it with: the runtime knows the parameters as
+ * strings and the loader's data as `mixed`, and a page narrows both by
+ * annotating its own props.
+ */
+type PageRenderProps = {|
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  readonly data: mixed,
+|};
+
+/** The props `RouteView` gives each layout, outermost first. */
+type LayoutRenderProps = {|
+  readonly params: RouteParams,
+  readonly children: React.Node,
+|};
 
 /** What a page module may export. The component is `default` or `Page`. */
 export type PageModule = {
-  +default?: React.ComponentType<any>,
-  +Page?: React.ComponentType<any>,
-  +loader?: (args: LoaderArgs) => mixed | Promise<mixed>,
-  +metadata?: Metadata,
-  +generateMetadata?: (args: MetadataArgs) => Metadata | Promise<Metadata>,
-  +generateStaticParams?: () => $ReadOnlyArray<RouteParams> | Promise<$ReadOnlyArray<RouteParams>>,
-  +frontmatter?: { +title?: string, +description?: string, ... },
+  readonly default?: RouteComponent,
+  readonly Page?: RouteComponent,
+  readonly loader?: (args: LoaderArgs) => mixed | Promise<mixed>,
+  readonly metadata?: Metadata,
+  readonly generateMetadata?: (args: MetadataArgs) => Metadata | Promise<Metadata>,
+  readonly generateStaticParams?: () =>
+    | $ReadOnlyArray<RouteParams>
+    | Promise<$ReadOnlyArray<RouteParams>>,
+  readonly frontmatter?: { readonly title?: string, readonly description?: string, ... },
   ...
 };
 
 /** What a layout module may export. The component is `default` or `Layout`. */
 export type LayoutModule = {
-  +default?: React.ComponentType<any>,
-  +Layout?: React.ComponentType<any>,
-  +metadata?: Metadata,
+  readonly default?: RouteComponent,
+  readonly Layout?: RouteComponent,
+  readonly metadata?: Metadata,
+  ...
+};
+
+/**
+ * What an error module may export. The component is `default` or `Error`.
+ *
+ * `Error` shadows the global inside the file that writes it, which is the
+ * cost of naming the export after what it is; a file that needs the
+ * constructor still has `globalThis.Error`. The alternative was a name the
+ * convention would have to explain — `ErrorPage`, `Boundary` — for a file
+ * whose whole job is already in its name.
+ */
+export type ErrorModule = {
+  readonly default?: RouteComponent,
+  readonly Error?: RouteComponent,
+  readonly metadata?: Metadata,
+  ...
+};
+
+/**
+ * What a loading module may export. The component is `default` or `Loading`.
+ *
+ * No `metadata`, and that is the type saying something true rather than an
+ * omission. A fallback renders while the route is still resolving, and the
+ * route's metadata was decided before the first byte — a title on a file that
+ * renders after the head has gone could never be used. `packages/web/head.js`
+ * documents the same constraint from the other side.
+ */
+export type LoadingModule = {
+  readonly default?: RouteComponent,
+  readonly Loading?: RouteComponent,
   ...
 };
 
+/**
+ * How a Twitter card is laid out, which is the whole of what `card` may be.
+ *
+ * A union rather than a string: every one of the four is spelled exactly this
+ * way and a fifth value is silently ignored by the crawler, so a typo in it
+ * costs a card and produces no error anywhere.
+ */
+export type TwitterCard = "summary" | "summary_large_image" | "app" | "player";
+
 /** Document metadata a page or layout declares. */
 export type Metadata = {
-  +title?: string,
-  +description?: string,
-  +openGraph?: {
-    +title?: string,
-    +description?: string,
-    +images?: $ReadOnlyArray<string>,
+  readonly title?: string,
+  readonly description?: string,
+  /**
+   * The absolute URL every other URL here is resolved against.
+   *
+   * Open Graph and Twitter both require absolute image URLs, and a route
+   * module has no way to know the host it will be served from — so without
+   * this, `openGraph.images: ["/og.png"]` ships exactly as written and is not
+   * a valid `og:image`. Declare it once on the root layout and every
+   * descendant inherits it through the same merge as everything else.
+   *
+   * Resolution is the URL standard's, so `"/og.png"` is resolved against the
+   * *origin* and `"og.png"` against the base's own path — not against the
+   * page's URL, which `Head` does not know.
+   */
+  readonly metadataBase?: string,
+  /**
+   * This page's canonical URL, for `<link rel="canonical">` and `og:url`.
+   *
+   * Relative to `metadataBase` when it is not absolute. A page
+   * reachable at more than one path — a query a filter added, a duplicate
+   * under a second section — is one page, and this is how it says so.
+   */
+  readonly canonical?: string,
+  readonly openGraph?: {
+    readonly title?: string,
+    readonly description?: string,
+    readonly images?: $ReadOnlyArray<string>,
+  },
+  readonly twitter?: {
+    readonly card?: TwitterCard,
+    readonly site?: string,
+    readonly creator?: string,
+    readonly title?: string,
+    readonly description?: string,
+    readonly images?: $ReadOnlyArray<string>,
   },
 };
 
 /** Arguments a loader receives. */
 export type LoaderArgs = {|
-  +params: RouteParams,
-  +searchParams: SearchParams,
-  +pathname: string,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  readonly pathname: string,
 |};
 
 /** Arguments `generateMetadata` receives. */
 export type MetadataArgs = {|
-  +params: RouteParams,
-  +searchParams: SearchParams,
-  +data: mixed,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  readonly data: mixed,
 |};
 
 /** One entry of the generated route table. */
 export type RouteRecord = {|
-  +path: string,
-  +params: $ReadOnlyArray<RouteParamSpec>,
-  +mdx: boolean,
-  +file: string,
-  +page: () => Promise<PageModule>,
-  +layouts: $ReadOnlyArray<() => Promise<LayoutModule>>,
+  readonly path: string,
+  readonly params: $ReadOnlyArray<RouteParamSpec>,
+  readonly mdx: boolean,
+  readonly file: string,
+  /**
+   * The page module — absent when this table cannot render the route.
+   *
+   * The server's table always has one: the server renders every route. The
+   * browser's may not. `@uniflowed/vite` leaves the page out of the client
+   * route table when uf's server-component analysis finds no `"use client"`
+   * boundary reachable from the page, its layouts or its fallbacks, and with
+   * the `import()` gone so is the whole subtree it reached — which is the
+   * point of leaving it out.
+   *
+   * The route stays in the table because the router still has to *match* the
+   * URL. Matching is what tells a `Link` that the destination is a document
+   * the browser must fetch rather than a page this bundle can render; a route
+   * missing from the table entirely would be a 404 instead. See
+   * [`hasClientPage`], which is the question every caller asks.
+   */
+  readonly page?: () => Promise<PageModule>,
+  readonly layouts: $ReadOnlyArray<() => Promise<LayoutModule>>,
+  /**
+   * The `<Suspense>` boundaries this route renders inside, root first.
+   *
+   * Optional because a table written before `_uf.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 not-found page, when the app declares one. */
-export type NotFoundRecord = {|
-  +mdx: boolean,
-  +file: string,
-  +page: () => Promise<PageModule>,
-  +layouts: $ReadOnlyArray<() => Promise<LayoutModule>>,
+/**
+ * One `_uf.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
+ * spelled the same way on purpose: both answer "where in the stack of layouts
+ * does this thing sit", and there is no second vocabulary for it.
+ */
+export type LoadingRecord = {|
+  readonly above: number,
+  readonly module: () => Promise<LoadingModule>,
 |};
 
-/** A route table plus the not-found page. */
+/**
+ * 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
+ * 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.
+ */
+export type NotFoundBoundary = {|
+  readonly path: string,
+  readonly mdx: boolean,
+  readonly file: string,
+  readonly page: () => Promise<PageModule>,
+  readonly layouts: $ReadOnlyArray<() => Promise<LayoutModule>>,
+|};
+
+/**
+ * One error boundary: what renders in place of the subtree under `path` when
+ * something in it throws.
+ *
+ * The same nearest-ancestor shape as [`NotFoundBoundary`], and `layouts` means
+ * the same thing — the layouts in scope where the file is, which stay mounted
+ * around the error and are why the rest of the document is still there.
+ */
+export type ErrorBoundary = {|
+  readonly path: string,
+  readonly file: string,
+  readonly module: () => Promise<ErrorModule>,
+  readonly layouts: $ReadOnlyArray<() => Promise<LayoutModule>>,
+|};
+
+/**
+ * A route table plus the boundaries declared under it.
+ *
+ * `errors` is the error boundaries a project declared, not failures that
+ * happened.
+ */
 export type RouteTable = {|
-  +routes: $ReadOnlyArray<RouteRecord>,
-  +notFound: ?NotFoundRecord,
+  readonly routes: $ReadOnlyArray<RouteRecord>,
+  readonly notFound: $ReadOnlyArray<NotFoundBoundary>,
+  readonly errors: $ReadOnlyArray<ErrorBoundary>,
 |};
 
 /** A URL matched against the table. */
 export type RouteMatch = {|
-  +route: RouteRecord,
-  +params: RouteParams,
+  readonly route: RouteRecord,
+  readonly params: RouteParams,
 |};
 
-/** A match whose modules are loaded and whose loader has run. */
+/**
+ * Why the router is rendering an error boundary instead of a page.
+ *
+ * One union rather than one file convention per status. `forbidden()` and
+ * `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
+ * express one thing, and nothing would check that any of them handled the
+ * case it was named for.
+ *
+ * The thrown value is carried but deliberately not rendered by the default
+ * boundary: a server exception's message is written for the person who
+ * deployed the application, not for whoever asks for the page.
+ */
+export type RouteError =
+  | {| readonly kind: "thrown", readonly error: mixed |}
+  | {| readonly kind: "unauthorized" |}
+  | {| readonly kind: "forbidden" |};
+
+/** The status a `RouteError` answers with. */
+export function routeErrorStatus(error: RouteError): 401 | 403 | 500 {
+  return match (error) {
+    {kind: "unauthorized"} => 401,
+    {kind: "forbidden"} => 403,
+    {kind: "thrown"} => 500,
+  };
+}
+
+/**
+ * A match whose modules are loaded and whose loader has run — or, when `error`
+ * is set, the error page that stands in for it.
+ */
 export type ResolvedRoute = {|
-  +pathname: string,
-  +search: string,
-  +path: string,
-  +params: RouteParams,
-  +searchParams: SearchParams,
-  +page: PageModule,
-  +layouts: $ReadOnlyArray<LayoutModule>,
-  +data: mixed,
-  +metadata: Metadata,
-  +status: 200 | 404,
+  readonly pathname: string,
+  readonly search: string,
+  readonly path: string,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  readonly page: PageModule,
+  readonly layouts: $ReadOnlyArray<LayoutModule>,
+  readonly data: mixed,
+  readonly metadata: Metadata,
+  readonly status: 200 | 401 | 403 | 404 | 500,
+  /**
+   * Set when this resolution *is* the error page: the loader threw, or the
+   * server render did and the renderer resolved again. `null` on the ordinary
+   * path.
+   */
+  readonly error: ?RouteError,
+  /**
+   * 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
+   * 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.
+   */
+  readonly errorBoundary: {|
+    readonly module: ?ErrorModule,
+    readonly above: number,
+  |},
+  /**
+   * The loading boundaries around this route, root first, already imported.
+   *
+   * 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
+   * ordinary case and renders exactly the tree it did before.
+   */
+  readonly loading: $ReadOnlyArray<{| readonly above: number, readonly module: LoadingModule |}>,
 |};
 
 /** Thrown by `notFound()`; the renderer answers with the not-found page. */
@@ -127,6 +377,22 @@ export class NotFoundError extends Error {
   }
 }
 
+/** Thrown by `unauthorized()`; the renderer answers with the error boundary. */
+export class UnauthorizedError extends Error {
+  constructor() {
+    super("unauthorized");
+    this.name = "UnauthorizedError";
+  }
+}
+
+/** Thrown by `forbidden()`; the renderer answers with the error boundary. */
+export class ForbiddenError extends Error {
+  constructor() {
+    super("forbidden");
+    this.name = "ForbiddenError";
+  }
+}
+
 /** Thrown by `redirect()`; the renderer answers with a redirect. */
 export class RedirectError extends Error {
   to: string;
@@ -145,9 +411,9 @@ export class RedirectError extends Error {
 // ---------------------------------------------------------------------------
 
 type Segment =
-  | {| +kind: "static", +value: string |}
-  | {| +kind: "param", +name: string |}
-  | {| +kind: "catchAll", +name: string |};
+  | {| readonly kind: "static", readonly value: string |}
+  | {| readonly kind: "param", readonly name: string |}
+  | {| readonly kind: "catchAll", readonly name: string |};
 
 function compile(routePath: string): $ReadOnlyArray<Segment> {
   return routePath
@@ -171,35 +437,37 @@ function compile(routePath: string): $ReadOnlyArray<Segment> {
 function specificity(segments: $ReadOnlyArray<Segment>): number {
   let score = 0;
   for (const segment of segments) {
-    score +=
-      match (segment) {
-        { kind: "static" } => 3,
-        { kind: "param" } => 2,
-        { kind: "catchAll" } => 1,
-      };
+    score += match (segment) {
+      {kind: "static"} => 3,
+      {kind: "param"} => 2,
+      {kind: "catchAll"} => 1,
+    };
   }
   return score;
 }
 
-function matchSegments(segments: $ReadOnlyArray<Segment>, parts: $ReadOnlyArray<string>): ?RouteParams {
+function matchSegments(
+  segments: $ReadOnlyArray<Segment>,
+  parts: $ReadOnlyArray<string>,
+): ?RouteParams {
   const params: { [string]: string | $ReadOnlyArray<string> } = {};
   let index = 0;
   for (const segment of segments) {
     match (segment) {
-      { kind: "static", value: const value } => {
+      {kind: "static", value: const value} => {
         if (parts[index] !== value) {
           return null;
         }
         index += 1;
       }
-      { kind: "param", name: const name } => {
+      {kind: "param", name: const name} => {
         if (index >= parts.length) {
           return null;
         }
         params[name] = decodeSegment(parts[index]);
         index += 1;
       }
-      { kind: "catchAll", name: const name } => {
+      {kind: "catchAll", name: const name} => {
         params[name] = parts.slice(index).map(decodeSegment);
         index = parts.length;
       }
@@ -216,6 +484,18 @@ function decodeSegment(segment: string): string {
   }
 }
 
+/**
+ * Whether this table can render the route in the browser.
+ *
+ * False only in the client bundle, and only for a route uf decided ships no
+ * JavaScript. Every caller that would load a page asks this first, and the two
+ * answers are different actions rather than a success and a failure: render
+ * it, or let the browser fetch the document.
+ */
+export function hasClientPage(route: RouteRecord): boolean {
+  return route.page != null;
+}
+
 /**
  * Match a pathname against the table, preferring the most specific route.
  */
@@ -238,8 +518,62 @@ export function matchRoute(routes: $ReadOnlyArray<RouteRecord>, pathname: string
   return best;
 }
 
+/**
+ * Whether a boundary declared at `segments` is at or above `parts`.
+ *
+ * The same segment kinds as [`matchSegments`], stopping when the boundary's
+ * own segments run out instead of requiring the path to: `/guide` covers
+ * `/guide/nope`, and `/guide` covers `/guide` itself.
+ */
+function covers(segments: $ReadOnlyArray<Segment>, parts: $ReadOnlyArray<string>): boolean {
+  let index = 0;
+  for (const segment of segments) {
+    const next = match (segment) {
+      {kind: "static", value: const value} => parts[index] === value ? index + 1 : -1,
+      {kind: "param"} => index < parts.length ? index + 1 : -1,
+      {kind: "catchAll"} => parts.length,
+    };
+    if (next === -1) {
+      return false;
+    }
+    index = next;
+  }
+  return true;
+}
+
+/**
+ * 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 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
+ * that read "nearest" as "first" would silently depend on that sort. Two
+ * boundaries can share a path (a route group's directory does not appear in
+ * the URL), and then the first in the table wins.
+ */
+function nearestBoundary<TBoundary: { readonly path: string, ... }>(
+  boundaries: $ReadOnlyArray<TBoundary>,
+  pathname: string,
+): ?TBoundary {
+  const parts = pathname.split("/").filter((part) => part !== "");
+  let best: ?TBoundary = null;
+  let bestDepth = -1;
+  for (const boundary of boundaries) {
+    const segments = compile(boundary.path);
+    if (!covers(segments, parts)) {
+      continue;
+    }
+    if (segments.length > bestDepth) {
+      best = boundary;
+      bestDepth = segments.length;
+    }
+  }
+  return best;
+}
+
 /** Split a URL into its pathname and search string. */
-export function splitUrl(url: string): {| +pathname: string, +search: string |} {
+export function splitUrl(url: string): {| readonly pathname: string, readonly search: string |} {
   const hash = url.indexOf("#");
   const withoutHash = hash === -1 ? url : url.slice(0, hash);
   const question = withoutHash.indexOf("?");
@@ -291,11 +625,39 @@ function loadOnce<T>(load: () => Promise<T>): Promise<T> {
  * `data` is what the loader returned; on the client after hydration it is the
  * value the server embedded, so the loader does not run twice for the first
  * page.
+ *
+ * # This resolves or redirects; it does not reject
+ *
+ * Everything a route can go wrong with is a route to render: no match and
+ * `notFound()` are the not-found boundary, a loader that threw and
+ * `forbidden()`/`unauthorized()` are the error boundary. Only `redirect()`
+ * comes back out, because a redirect is a response rather than a page and the
+ * caller is what has one to send.
+ *
+ * That guarantee is the point rather than a convenience. `hydrate` awaits this
+ * before `hydrateRoot`, so a rejection there is not an error page — it is no
+ * `hydrateRoot` call at all, and the document the server sent stays on screen
+ * with nothing attached to it.
  */
 export async function resolveMatch(
   table: RouteTable,
   url: string,
-  options?: {| +data?: mixed, +skipLoader?: boolean |},
+  options?: {| readonly data?: mixed, readonly skipLoader?: boolean |},
+): Promise<ResolvedRoute> {
+  try {
+    return await resolveRoute(table, url, options);
+  } catch (error) {
+    if (error instanceof RedirectError) {
+      throw error;
+    }
+    return resolveFailure(table, url, error);
+  }
+}
+
+async function resolveRoute(
+  table: RouteTable,
+  url: string,
+  options?: {| readonly data?: mixed, readonly skipLoader?: boolean |},
 ): Promise<ResolvedRoute> {
   const { pathname, search } = splitUrl(url);
   const searchParams = parseSearch(search);
@@ -305,24 +667,52 @@ export async function resolveMatch(
     return resolveNotFound(table, pathname, search, searchParams);
   }
 
+  const load = matched.route.page;
+  if (load == null) {
+    // Reachable only by asking this table to render a route it was built
+    // without. `hydrate` and every navigation check `hasClientPage` first and
+    // hand the URL to the browser instead, so arriving here means a caller
+    // went around them — and the honest answer is to say so rather than to
+    // render an empty page.
+    throw new Error(
+      `@uniflowed/router: ${matched.route.path} has no page in this route table; it ships no ` +
+        "client JavaScript, so the browser navigates to it rather than rendering it",
+    );
+  }
   const [page, ...layouts] = await Promise.all([
-    loadOnce(matched.route.page),
+    loadOnce(load),
     ...matched.route.layouts.map((layout) => loadOnce(layout)),
   ]);
+  // Started here and awaited at the end: the boundary's module does not depend
+  // on the loader, so importing it alongside costs a navigation nothing. It
+  // never rejects, so an early throw below leaves no unhandled rejection.
+  const boundary = resolveErrorBoundary(table, pathname, matched.route.layouts.length);
+  // Started alongside for the same reason, and awaited at the end: a fallback
+  // depends on nothing the loader produces.
+  const loading = resolveLoading(matched.route, matched.route.layouts.length);
 
   let data: mixed = options?.data;
   if (options?.skipLoader !== true && typeof page.loader === "function") {
-    try {
-      data = await page.loader({ params: matched.params, searchParams, pathname });
-    } catch (error) {
-      if (error instanceof NotFoundError) {
-        return resolveNotFound(table, pathname, search, searchParams);
-      }
-      throw error;
-    }
+    // Awaited here, so a route's time to first byte is still its slowest
+    // loader. A page that suspends while *rendering* streams — that is what the
+    // `<Suspense>` boundaries below are for — but a page waiting on its loader
+    // has already waited by the time React sees the tree, so its fallback shows
+    // for no time at all.
+    //
+    // Deferring it means handing the page a promise and unwrapping it inside
+    // the boundary, and the obstacle is not the awaiting: it is that
+    // `generateMetadata` reads `data` and metadata goes in the head, and that
+    // the loader data is embedded in the head too, for hydration. Both are
+    // decisions about the document rather than about the route.
+    // ubugeeei-prod/uf#373 has the design.
+    data = await page.loader({ params: matched.params, searchParams, pathname });
   }
 
-  const metadata = await resolveMetadata(page, layouts, { params: matched.params, searchParams, data });
+  const metadata = await resolveMetadata(page, layouts, {
+    params: matched.params,
+    searchParams,
+    data,
+  });
   return {
     pathname,
     search,
@@ -334,16 +724,209 @@ export async function resolveMatch(
     data,
     metadata,
     status: 200,
+    error: null,
+    errorBoundary: await boundary,
+    loading: await loading,
   };
 }
 
+/**
+ * The route's loading boundaries, imported.
+ *
+ * A boundary whose module will not load is dropped rather than thrown for, and
+ * this is the same judgement `resolveErrorBoundary` makes one function above: a
+ * fallback is what the router shows while it does not yet have the page, so a
+ * broken fallback must not become a broken page. The route renders without that
+ * boundary — the next one out, or the shell, waits for it instead — and the
+ * import error surfaces where it belongs, when the module is next asked for.
+ */
+async function resolveLoading(
+  route: RouteRecord,
+  layoutCount: number,
+): Promise<$ReadOnlyArray<{| readonly above: number, readonly module: LoadingModule |}>> {
+  const records = route.loading ?? [];
+  if (records.length === 0) {
+    return [];
+  }
+  const loaded = await Promise.all(
+    records.map(async (record) => {
+      try {
+        return {
+          // Clamped exactly as the error boundary's is, and for the same
+          // reason: a `(group)` directory can leave a route with fewer layouts
+          // than the boundary that covers it.
+          above: Math.min(record.above, layoutCount),
+          module: await loadOnce(record.module),
+        };
+      } catch {
+        return null;
+      }
+    }),
+  );
+  return loaded.filter(Boolean);
+}
+
+/**
+ * The route to render after something threw.
+ *
+ * Two callers, one behaviour: [`resolveMatch`] when a loader or a module
+ * import threw, and `createRenderer` when the *render* did — React's error
+ * boundaries do not run in `renderToString`, so the server has to catch it
+ * itself and resolve again.
+ */
+export async function resolveFailure(
+  table: RouteTable,
+  url: string,
+  error: mixed,
+): Promise<ResolvedRoute> {
+  const { pathname, search } = splitUrl(url);
+  const searchParams = parseSearch(search);
+  if (error instanceof NotFoundError) {
+    try {
+      return await resolveNotFound(table, pathname, search, searchParams);
+    } catch (failure) {
+      // The not-found page itself would not load. Falling through to the error
+      // boundary rather than rethrowing is what keeps the promise above: the
+      // page a project wrote to explain a 404 is not more load-bearing than
+      // the document staying on screen.
+      return resolveError(table, pathname, search, searchParams, routeErrorFor(failure));
+    }
+  }
+  return resolveError(table, pathname, search, searchParams, routeErrorFor(error));
+}
+
+/** What a thrown value means to the router. */
+function routeErrorFor(error: mixed): RouteError {
+  if (error instanceof UnauthorizedError) {
+    return { kind: "unauthorized" };
+  }
+  if (error instanceof ForbiddenError) {
+    return { kind: "forbidden" };
+  }
+  return { kind: "thrown", error };
+}
+
+/**
+ * The error boundary a route renders inside, loaded with the route rather than
+ * when it is needed.
+ *
+ * React decides to show a boundary's fallback synchronously, during the render
+ * that threw. A module that still has to be imported is a module that is not
+ * there at the only moment it can be used, so this is one more dynamic import
+ * per navigation and not a lazy one.
+ *
+ * `above` is the boundary's own layout count, clamped to the route's. The
+ * first attempt compared the two layout arrays for a shared prefix, which is
+ * more precise when a `(group)` directory puts a boundary beside a route
+ * rather than above it — and it worked by *reference identity* of the loader
+ * functions, which holds only because `routesModuleSource` deduplicates them
+ * by file. A rule that depends on an invisible property of the generated
+ * module is a rule that reads as zero the moment a table is built any other
+ * way, and it did: it put the boundary outside the layouts it was written
+ * inside. Nesting a boundary per group needs parallel-route trees (#267);
+ * until then this is the honest approximation, and it is stated rather than
+ * inferred.
+ */
+async function resolveErrorBoundary(
+  table: RouteTable,
+  pathname: string,
+  layoutCount: number,
+): Promise<{| readonly module: ?ErrorModule, readonly above: number |}> {
+  const boundary = nearestBoundary(table.errors, pathname);
+  if (boundary == null) {
+    return { module: null, above: 0 };
+  }
+  // Clamped, because a route group can leave a route with fewer layouts than
+  // the boundary covering it, and an `above` past the end would compose the
+  // layouts out of nothing.
+  const above = Math.min(boundary.layouts.length, layoutCount);
+  try {
+    return { module: await loadOnce(boundary.module), above };
+  } catch {
+    // A boundary whose module will not load cannot be the answer to a throw,
+    // and this is why the field is nullable: containment must not itself
+    // depend on an import working.
+    return { module: null, above: 0 };
+  }
+}
+
+/**
+ * The error page for `pathname`, inside the layouts above the boundary that
+ * answers it.
+ *
+ * The layouts are the boundary's, for the same reason [`resolveNotFound`]
+ * gives: they are what stays mounted around the error, and the layouts below
+ * the boundary belong to the subtree that just stopped.
+ */
+async function resolveError(
+  table: RouteTable,
+  pathname: string,
+  search: string,
+  searchParams: SearchParams,
+  routeError: RouteError,
+): Promise<ResolvedRoute> {
+  const boundary = nearestBoundary(table.errors, pathname);
+  let module: ?ErrorModule = null;
+  let layouts: $ReadOnlyArray<LayoutModule> = [];
+  if (boundary != null) {
+    try {
+      [module, layouts] = await Promise.all([
+        loadOnce(boundary.module),
+        Promise.all(boundary.layouts.map((layout) => loadOnce(layout))),
+      ]);
+    } catch {
+      // See `resolveErrorBoundary`: the framework's own page answers instead.
+      module = null;
+      layouts = [];
+    }
+  }
+
+  const declared = await resolveMetadata(
+    module?.metadata != null ? { metadata: module.metadata } : {},
+    layouts,
+    { params: {}, searchParams, data: undefined },
+  );
+  return {
+    pathname,
+    search,
+    path: "*",
+    params: {},
+    searchParams,
+    page: { default: ResolvedErrorPage },
+    layouts,
+    data: undefined,
+    metadata: declared.title != null ? declared : { ...declared, title: errorTitle(routeError) },
+    status: routeErrorStatus(routeError),
+    error: routeError,
+    // All of the boundary's layouts are above it, and no inner boundary is
+    // inserted around a page that already is one; see `RouteView`.
+    errorBoundary: { module, above: layouts.length },
+    // An error page has nothing left to wait for: it renders the value it was
+    // resolved with. A fallback around it would be a boundary that can never
+    // show, which is worse than none.
+    loading: [],
+  };
+}
+
+/**
+ * The not-found page for `pathname`, inside the layouts above the boundary
+ * that answers it.
+ *
+ * The layouts are the *boundary's*, not the ones the URL had already matched.
+ * 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
+ * of the page that just said it does not exist.
+ */
 async function resolveNotFound(
   table: RouteTable,
   pathname: string,
   search: string,
   searchParams: SearchParams,
 ): Promise<ResolvedRoute> {
-  const record = table.notFound;
+  const record = nearestBoundary(table.notFound, pathname);
   if (record == null) {
     return {
       pathname,
@@ -356,13 +939,20 @@ async function resolveNotFound(
       data: undefined,
       metadata: { title: "Not found" },
       status: 404,
+      error: null,
+      errorBoundary: await resolveErrorBoundary(table, pathname, 0),
+      loading: [],
     };
   }
   const [page, ...layouts] = await Promise.all([
     loadOnce(record.page),
     ...record.layouts.map((layout) => loadOnce(layout)),
   ]);
-  const metadata = await resolveMetadata(page, layouts, { params: {}, searchParams, data: undefined });
+  const metadata = await resolveMetadata(page, layouts, {
+    params: {},
+    searchParams,
+    data: undefined,
+  });
   return {
     pathname,
     search,
@@ -374,6 +964,13 @@ async function resolveNotFound(
     data: undefined,
     metadata,
     status: 404,
+    error: null,
+    // A not-found page is a page: one that throws is contained like any other.
+    errorBoundary: await resolveErrorBoundary(table, pathname, layouts.length),
+    // A not-found boundary is matched, not nested: `nearestBoundary` picked one
+    // record and the loading files are a property of the route that was walked
+    // to, which this URL never reached. Nothing to wait for, so no boundary.
+    loading: [],
   };
 }
 
@@ -390,7 +987,11 @@ async function resolveMetadata(
   }
   if (page.frontmatter != null) {
     const { title, description } = page.frontmatter;
-    merged = { ...merged, ...(title != null ? { title } : {}), ...(description != null ? { description } : {}) };
+    merged = {
+      ...merged,
+      ...(title != null ? { title } : {}),
+      ...(description != null ? { description } : {}),
+    };
   }
   if (page.metadata != null) {
     merged = { ...merged, ...page.metadata };
@@ -411,37 +1012,188 @@ component DefaultNotFound() {
   );
 }
 
+/** The document title an error page gets when nothing declared one. */
+function errorTitle(error: RouteError): string {
+  return match (error) {
+    {kind: "unauthorized"} => "Sign in required",
+    {kind: "forbidden"} => "Not allowed",
+    {kind: "thrown"} => "Something went wrong",
+  };
+}
+
+/**
+ * The framework's error page, for a project that declares no `_uf.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
+ * deployed the application — a query, a path, a token in a stack — and this
+ * markup is sent to whoever asked for the page. `uf dev` reports the throw in
+ * the terminal and `uf build` fails the route, which are the places the person
+ * who can act on it is looking.
+ */
+component DefaultRouteError(error: RouteError, reset: () => void) {
+  const title = errorTitle(error);
+  const detail = match (error) {
+    {kind: "unauthorized"} => "This page needs you to be signed in.",
+    {kind: "forbidden"} => "You do not have access to this page.",
+    {kind: "thrown"} => "This page could not be rendered.",
+  };
+  return (
+    <main>
+      <title>{title}</title>
+      <h1>{title}</h1>
+      <p>{detail}</p>
+      <button type="button" onClick={reset}>
+        Try again
+      </button>
+    </main>
+  );
+}
+
+/** The component an error module renders: `default`, or the named `Error`. */
+function errorComponent(module: ErrorModule): React.ComponentType<ErrorRenderProps> {
+  const component = module.default ?? module.Error;
+  if (component == null) {
+    throw new Error(
+      "@uniflowed/router: an error module must export a component as `default` or `Error`",
+    );
+  }
+  return renderable(component);
+}
+
+/** The props an error boundary's component receives. */
+type ErrorRenderProps = {|
+  readonly error: RouteError,
+  readonly reset: () => void,
+|};
+
+/**
+ * The error UI, from whichever module is in scope.
+ *
+ * One component for both ways in — the class boundary below, which catches a
+ * throw while the browser renders, and `ResolvedErrorPage`, which is what the
+ * server renders because React's boundaries do not run in `renderToString`.
+ * Two paths to the same screen is exactly the pair that drifts.
+ */
+component RouteErrorView(module: ?ErrorModule, error: RouteError, reset: () => void) {
+  if (module == null) {
+    return <DefaultRouteError error={error} reset={reset} />;
+  }
+  const Boundary = errorComponent(module);
+  return <Boundary error={error} reset={reset} />;
+}
+
+/**
+ * The page of a route that resolved to an error.
+ *
+ * A resolved error route carries the error and the module on the route itself,
+ * so this is a static component rather than a closure the resolver builds:
+ * `RouteView` composes it in its layouts exactly like a page, which is what
+ * makes "inside the layouts above the boundary" one code path and not two.
+ *
+ * `reset()` here is `router.refresh()` — this route resolved to an error
+ * because a loader or an import threw, so re-running the resolution is what
+ * trying again means. On the server `refresh` does nothing, which is correct:
+ * a static render has nothing to re-run.
+ */
+component ResolvedErrorPage() {
+  const { resolved, router } = useRouterState();
+  const reset = useCallback(() => {
+    router.refresh().catch(() => {});
+  }, [router]);
+
+  if (resolved.error == null) {
+    // Unreachable: this module is only ever the page of a resolved error route.
+    return null;
+  }
+  return (
+    <RouteErrorView module={resolved.errorBoundary.module} error={resolved.error} reset={reset} />
+  );
+}
+
+type RouteErrorBoundaryProps = {|
+  readonly module: ?ErrorModule,
+  readonly resetKey: string,
+  readonly children: React.Node,
+|};
+
+type RouteErrorBoundaryState = {| readonly error: ?RouteError |};
+
+/**
+ * The boundary that catches a throw while the browser renders the subtree.
+ *
+ * A class, because `getDerivedStateFromError` is React's contract for this and
+ * there is no hook that does it — this is the one place in the router where
+ * following React's public contract means not using a function component.
+ *
+ * Recovering on navigation is `componentDidUpdate` watching `resetKey`, not
+ * `key={pathname}` on the boundary. Keying it remounts the subtree on *every*
+ * navigation, error or not, and everything below the boundary goes with it —
+ * which is the layouts, whose whole purpose is to survive navigation with
+ * their scroll position and their open sections intact.
+ */
+class RouteErrorBoundary extends React.Component<RouteErrorBoundaryProps, RouteErrorBoundaryState> {
+  constructor(props: RouteErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: mixed): RouteErrorBoundaryState {
+    return { error: routeErrorFor(error) };
+  }
+
+  componentDidUpdate(previous: RouteErrorBoundaryProps) {
+    if (this.state.error != null && previous.resetKey !== this.props.resetKey) {
+      this.setState({ error: null });
+    }
+  }
+
+  render(): React.Node {
+    const { error } = this.state;
+    if (error == null) {
+      return this.props.children;
+    }
+    return (
+      <RouteErrorView
+        module={this.props.module}
+        error={error}
+        reset={() => this.setState({ error: null })}
+      />
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // The React binding
 // ---------------------------------------------------------------------------
 
 /** How a navigation is performed. */
-export type NavigateOptions = {| +replace?: boolean, +scroll?: boolean |};
+export type NavigateOptions = {| readonly replace?: boolean, readonly scroll?: boolean |};
 
 /** What `useRouter()` returns. */
 export type Router = {|
-  +push: (to: string, options?: NavigateOptions) => Promise<void>,
-  +replace: (to: string) => Promise<void>,
-  +prefetch: (to: string) => Promise<void>,
-  +refresh: () => Promise<void>,
-  +back: () => void,
-  +forward: () => void,
+  readonly push: (to: string, options?: NavigateOptions) => Promise<void>,
+  readonly replace: (to: string) => Promise<void>,
+  readonly prefetch: (to: string) => Promise<void>,
+  readonly refresh: () => Promise<void>,
+  readonly back: () => void,
+  readonly forward: () => void,
 |};
 
 /** What `useRoute()` returns. */
 export type RouteInfo = {|
-  +path: string,
-  +pathname: string,
-  +params: RouteParams,
-  +searchParams: SearchParams,
-  +data: mixed,
-  +pending: boolean,
+  readonly path: string,
+  readonly pathname: string,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  readonly data: mixed,
+  readonly pending: boolean,
 |};
 
 type RouterState = {|
-  +resolved: ResolvedRoute,
-  +router: Router,
-  +pending: boolean,
+  readonly resolved: ResolvedRoute,
+  readonly router: Router,
+  readonly pending: boolean,
 |};
 
 const RouterContext: React.Context<?RouterState> = createContext(null);
@@ -457,18 +1209,36 @@ export function installRoutes(table: RouteTable): void {
 /** The registered table, or a clear error when the entry forgot to install it. */
 export function routeTable(): RouteTable {
   if (installedTable == null) {
-    throw new Error("@uniflowed/router: no route table is installed; start the app through `uf dev` or `uf build`");
+    throw new Error(
+      "@uniflowed/router: no route table is installed; start the app through `uf dev` or `uf build`",
+    );
   }
   return installedTable;
 }
 
 /** Props the app root receives from the client and server entries. */
 export type AppProps = {|
-  +url: string,
-  +initial: ResolvedRoute,
+  readonly url: string,
+  readonly initial: ResolvedRoute,
 |};
 
-const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+/**
+ * Whether there is a document to navigate.
+ *
+ * Asked every time rather than answered once at module scope, and the
+ * difference is not a style preference. The answer is a constant inside a
+ * browser bundle and inside a server process; it is *not* a constant inside a
+ * test runner, where a DOM is installed on the first render and one worker
+ * serves many files out of one module registry. Latched, the first file in a
+ * worker to import this module decided for every file after it whether a
+ * `Link` navigates or silently does nothing — and a server-rendering test
+ * imports it before any document exists. See ubugeeei-prod/uf#445.
+ *
+ * The cost is a `typeof` per navigation, which is a navigation.
+ */
+function isBrowser(): boolean {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
 
 /**
  * Provides the current route to the tree and performs navigation.
@@ -483,11 +1253,23 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
   const [pending, setPending] = useState<boolean>(false);
 
   const navigate = useCallback(async (to: string, options?: NavigateOptions): Promise<void> => {
-    if (!isBrowser) {
+    if (!isBrowser()) {
       return;
     }
     const target = new URL(to, window.location.href);
     const next = target.pathname + target.search;
+    // 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
+    // and the visitor would be left on the page they clicked from. The browser
+    // has the document, so the browser does the navigation — which is what a
+    // link does when there is no JavaScript at all, and what the anchor
+    // `Link` renders would have done on its own.
+    const matched = matchRoute(routeTable().routes, target.pathname);
+    if (matched != null && !hasClientPage(matched.route)) {
+      window.location.assign(target.href);
+      return;
+    }
     setPending(true);
     try {
       const nextResolved = await resolveMatch(routeTable(), next);
@@ -517,11 +1299,19 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
   }, []);
 
   useEffect(() => {
-    if (!isBrowser) {
+    if (!isBrowser()) {
       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
+      // already the browser's — it moved before this listener ran — so the
+      // document that belongs to it is what has to be fetched.
+      const matched = matchRoute(routeTable().routes, window.location.pathname);
+      if (matched != null && !hasClientPage(matched.route)) {
+        window.location.reload();
+        return;
+      }
       resolveMatch(routeTable(), next).then((nextResolved) => {
         startTransition(() => {
           setResolved(nextResolved);
@@ -539,32 +1329,39 @@ 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) {
+        if (!isBrowser()) {
           return;
         }
         const target = new URL(to, window.location.href);
         const matched = matchRoute(routeTable().routes, target.pathname);
-        if (matched == null) {
+        const load = matched?.route.page;
+        if (matched == null || load == null) {
           return;
         }
-        await Promise.all([loadOnce(matched.route.page), ...matched.route.layouts.map((layout) => loadOnce(layout))]);
+        await Promise.all([
+          loadOnce(load),
+          ...matched.route.layouts.map((layout) => loadOnce(layout)),
+        ]);
       },
       refresh: async () => {
-        if (!isBrowser) {
+        if (!isBrowser()) {
           return;
         }
-        const nextResolved = await resolveMatch(routeTable(), window.location.pathname + window.location.search);
+        const nextResolved = await resolveMatch(
+          routeTable(),
+          window.location.pathname + window.location.search,
+        );
         startTransition(() => {
           setResolved(nextResolved);
         });
       },
       back: () => {
-        if (isBrowser) {
+        if (isBrowser()) {
           window.history.back();
         }
       },
       forward: () => {
-        if (isBrowser) {
+        if (isBrowser()) {
           window.history.forward();
         }
       },
@@ -572,14 +1369,19 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
     [navigate],
   );
 
-  const value = useMemo<RouterState>(() => ({ resolved, router, pending }), [resolved, router, pending]);
+  const value = useMemo<RouterState>(
+    () => ({ resolved, router, pending }),
+    [resolved, router, pending],
+  );
   return <RouterContext.Provider value={value}>{children}</RouterContext.Provider>;
 }
 
 hook useRouterState(): RouterState {
   const state = useContext(RouterContext);
   if (state == null) {
-    throw new Error("@uniflowed/router: this hook must be used inside the app started by `routerView`");
+    throw new Error(
+      "@uniflowed/router: this hook must be used inside the app started by `routerView`",
+    );
   }
   return state;
 }
@@ -602,30 +1404,112 @@ export hook useRouter(): Router {
   return useRouterState().router;
 }
 
-/** The current page's loader data. */
-export hook useLoaderData<T>(): T {
-  // $FlowFixMe[unclear-type] loader data is typed by the page that declares the loader.
-  return (useRouterState().resolved.data: any);
+/**
+ * The current page's loader data.
+ *
+ * `mixed`, so the page that reads it says what it is and the checker watches
+ * it do so. This was `useLoaderData<T>(): T`, which looks like inference and
+ * is a cast a caller writes at a distance: `useLoaderData<Post>()` asserted
+ * that a loader three files away returned a `Post` and nothing anywhere
+ * checked it, so a loader that changed shape produced a `Post`-shaped
+ * `undefined` at the first property read rather than an error where the shape
+ * was decided.
+ *
+ * Narrowing is a line at the top of the page — `if (typeof data !== "object"
+ * || data == null) { … }`, or the page's own validator schema, which is what
+ * `@uniflowed/validator` is for at exactly this boundary.
+ *
+ * The type that would need no narrowing is a *generated* one: the route table
+ * already produces `RoutePath` and `RouteParams` from the `app/` directory
+ * (`crates/uf_router/src/lib.rs`), and a loader's return type belongs in the
+ * same file, keyed by route. Until it is there, this says what is true.
+ */
+export hook useLoaderData(): mixed {
+  return useRouterState().resolved.data;
 }
 
 /**
  * Renders the matched page inside its layouts, innermost last, with the
  * document metadata as hoistable head elements.
+ *
+ * # One walk down the layouts, not three
+ *
+ * The layouts, the error boundary and the `<Suspense>` boundaries all have to
+ * be threaded into the same stack at the depth each was declared at, so this
+ * is one descending loop over that depth rather than a pass per kind. `depth`
+ * counts the layouts still *outside* the element built so far, which is what
+ * `above` means on both a route's `errorBoundary` and each of its `loading`
+ * entries — one number, one meaning, one place it is compared.
+ *
+ * # 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
+ * 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
+ * the error component itself, and an unmounted document. A single boundary
+ * cannot be both: put it outside and a page's throw takes the navigation down
+ * with it; put it inside and nothing catches the layout above.
+ *
+ * # Where the loading boundaries go
+ *
+ * Inside the layout of the segment that declared the file and outside
+ * 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
+ * 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
+ * should rather than silently rendering nothing.
+ *
+ * The error boundary goes *outside* the fallback at the same depth. A throw
+ * while the page is resolving has to reach a boundary that is still mounted,
+ * and the `<Suspense>` is part of what the throw came out of.
  */
 export component RouteView() {
   const { resolved } = useRouterState();
+  const { module, above } = resolved.errorBoundary;
   const Page = pageComponent(resolved.page);
   let element: React.Node = (
     <Page params={resolved.params} searchParams={resolved.searchParams} data={resolved.data} />
   );
-  for (let index = resolved.layouts.length - 1; index >= 0; index -= 1) {
-    const Layout = layoutComponent(resolved.layouts[index]);
-    element = <Layout params={resolved.params}>{element}</Layout>;
+
+  for (let depth = resolved.layouts.length; depth >= 0; depth -= 1) {
+    // Backwards over a root-first list, so the deepest segment's fallback ends
+    // up closest to the page. Two segments land on the same depth whenever the
+    // inner one declares no layout of its own, and then this order is the only
+    // thing that keeps them nested the way the directories are.
+    for (let index = resolved.loading.length - 1; index >= 0; index -= 1) {
+      const boundary = resolved.loading[index];
+      if (boundary.above !== depth) {
+        continue;
+      }
+      const Fallback = loadingComponent(boundary.module);
+      element = <Suspense fallback={<Fallback />}>{element}</Suspense>;
+    }
+    // Not around a route that already resolved to its error page: that page is
+    // the boundary's own component, and wrapping it in the same boundary would
+    // answer a throw inside it with itself.
+    if (depth === above && module != null && resolved.error == null) {
+      element = (
+        <RouteErrorBoundary module={module} resetKey={resolved.pathname}>
+          {element}
+        </RouteErrorBoundary>
+      );
+    }
+    if (depth > 0) {
+      const Layout = layoutComponent(resolved.layouts[depth - 1]);
+      element = <Layout params={resolved.params}>{element}</Layout>;
+    }
   }
   return (
     <>
       <Head metadata={resolved.metadata} />
-      {element}
+      <RouteErrorBoundary module={null} resetKey={resolved.pathname}>
+        {element}
+      </RouteErrorBoundary>
     </>
   );
 }
@@ -634,33 +1518,130 @@ export component RouteView() {
  * The component a page module renders: its default export, or the named
  * `Page` that `uf create` scaffolds. An MDX page always has a default export.
  */
-function pageComponent(module: PageModule): React.ComponentType<any> {
+function pageComponent(module: PageModule): React.ComponentType<PageRenderProps> {
   const component = module.default ?? module.Page;
   if (component == null) {
-    throw new Error("@uniflowed/router: a page module must export a component as `default` or `Page`");
+    throw new Error(
+      "@uniflowed/router: a page module must export a component as `default` or `Page`",
+    );
   }
-  return component;
+  return renderable(component);
+}
+
+/**
+ * The component a loading module renders: `default`, or the named `Loading`.
+ *
+ * No props, unlike a page or a layout. A fallback is what the router shows
+ * when it does not have the route's answer yet, so there is nothing it could
+ * be handed that would be true — not `data`, which is the thing being waited
+ * for, and not `children`, because it renders instead of them.
+ */
+function loadingComponent(module: LoadingModule): React.ComponentType<{||}> {
+  const component = module.default ?? module.Loading;
+  if (component == null) {
+    throw new Error(
+      "@uniflowed/router: a loading module must export a component as `default` or `Loading`",
+    );
+  }
+  return renderable(component);
 }
 
 /** The component a layout module renders: `default`, or the named `Layout`. */
-function layoutComponent(module: LayoutModule): React.ComponentType<any> {
+function layoutComponent(module: LayoutModule): React.ComponentType<LayoutRenderProps> {
   const component = module.default ?? module.Layout;
   if (component == null) {
-    throw new Error("@uniflowed/router: a layout module must export a component as `default` or `Layout`");
+    throw new Error(
+      "@uniflowed/router: a layout module must export a component as `default` or `Layout`",
+    );
+  }
+  return renderable(component);
+}
+
+/**
+ * A route module's component, as the router is about to render it.
+ *
+ * # The one cast in this file, and why it is here rather than in six places
+ *
+ * A `RouteComponent` is a component about whose props nothing was claimed, and
+ * `RouteView` is about to pass it three. React allows that — a component
+ * receives the props its parent wrote and ignores the ones it did not declare
+ * — but Flow cannot be told it: a page's props are exact, so no props type but
+ * that page's own is assignable, and the router does not know which page it
+ * has. `React.ComponentType<any>` on the module types was this same
+ * unsoundness spread over six declarations, where it also stopped anyone from
+ * checking that `RouteView` passes the props a page is documented to receive.
+ * Here it is one line, and everything on either side of it is checked: what a
+ * module may export, and what a page is handed. Suppressed by name so that
+ * `check:lib` can gate CI without this file being the thing that stops it; the
+ * directive names the rule, and this is the argument for escaping it.
+ */
+function renderable<TProps extends { ... }>(
+  component: RouteComponent,
+): React.ComponentType<TProps> {
+  // uf-lint-disable-next-line flow/unclear-type
+  return component as any;
+}
+
+/**
+ * One URL from a route's metadata, made absolute if it can be.
+ *
+ * Open Graph, Twitter and `rel="canonical"` all want an absolute URL, and a
+ * route module cannot know the host it is served from — so `metadataBase` is
+ * how a site says it once, and this is where it is applied.
+ *
+ * Three things it deliberately does not do. It does not resolve against the
+ * *page's* URL: `Head` renders inside the route and does not know it, and a
+ * `metadataBase` is a site-wide fact rather than a per-page one. It does not
+ * invent a base: with none declared the value is emitted exactly as written,
+ * which is what every page that predates this field already gets. And it does
+ * not throw — a `metadataBase` that is not a URL is a mistake in one field,
+ * and turning it into a blank page would be a worse answer than an unresolved
+ * `og:image`.
+ */
+function absoluteUrl(value: string, base: void | string): string {
+  if (base == null) return value;
+  try {
+    return new URL(value, base).href;
+  } catch {
+    return value;
   }
-  return component;
 }
 
 component Head(metadata: Metadata) {
-  const { title, description, openGraph } = metadata;
+  const { title, description, metadataBase, canonical, openGraph, twitter } = metadata;
+  const href = canonical != null ? absoluteUrl(canonical, metadataBase) : null;
   return (
     <>
       {title != null ? <title>{title}</title> : null}
       {description != null ? <meta name="description" content={description} /> : null}
+      {href != null ? <link rel="canonical" href={href} /> : null}
+      {/* `og:url` *is* the canonical URL of the page, in Open Graph's own
+          words, so one declaration answers both rather than asking a project
+          to write the same URL twice and keep them in step. */}
+      {href != null ? <meta property="og:url" content={href} /> : null}
       {openGraph?.title != null ? <meta property="og:title" content={openGraph.title} /> : null}
-      {openGraph?.description != null ? <meta property="og:description" content={openGraph.description} /> : null}
+      {openGraph?.description != null ? (
+        <meta property="og:description" content={openGraph.description} />
+      ) : null}
       {openGraph?.images != null
-        ? openGraph.images.map((image) => <meta key={image} property="og:image" content={image} />)
+        ? openGraph.images.map((image) => (
+            <meta key={image} property="og:image" content={absoluteUrl(image, metadataBase)} />
+          ))
+        : null}
+      {/* `name`, not `property`: Open Graph is RDFa and Twitter's cards are
+          not, and a `property="twitter:card"` is ignored by the crawler that
+          reads it. */}
+      {twitter?.card != null ? <meta name="twitter:card" content={twitter.card} /> : null}
+      {twitter?.site != null ? <meta name="twitter:site" content={twitter.site} /> : null}
+      {twitter?.creator != null ? <meta name="twitter:creator" content={twitter.creator} /> : null}
+      {twitter?.title != null ? <meta name="twitter:title" content={twitter.title} /> : null}
+      {twitter?.description != null ? (
+        <meta name="twitter:description" content={twitter.description} />
+      ) : null}
+      {twitter?.images != null
+        ? twitter.images.map((image) => (
+            <meta key={image} name="twitter:image" content={absoluteUrl(image, metadataBase)} />
+          ))
         : null}
     </>
   );
@@ -683,7 +1664,7 @@ export component Link(
   children?: React.Node,
   className?: string,
   onClick?: (event: SyntheticMouseEvent<HTMLAnchorElement>) => mixed,
-  ...rest: { +[string]: mixed }
+  ...rest: { readonly [string]: mixed }
 ) {
   const router = useRouter();
   const prefetched = React.useRef(false);
@@ -767,6 +1748,16 @@ export function notFound(): empty {
   throw new NotFoundError();
 }
 
+/** Stop rendering the current page and show the error boundary, as a 401. */
+export function unauthorized(): empty {
+  throw new UnauthorizedError();
+}
+
+/** Stop rendering the current page and show the error boundary, as a 403. */
+export function forbidden(): empty {
+  throw new ForbiddenError();
+}
+
 /** Stop rendering the current page and send the visitor elsewhere. */
 export function redirect(to: string): empty {
   throw new RedirectError(to, false);