@uniflowed/router 0.0.0-alpha.6 → 0.0.0-alpha.8

package/internal/runtime.js

@@ -11,6 +11,7 @@
 
 import * as React from "react";
 import {
+  Suspense,
   createContext,
   startTransition,
   useCallback,
@@ -99,6 +100,37 @@ export type LayoutModule = {
   ...
 };
 
+/**
+ * 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,
+  ...
+};
+
 /** Document metadata a page or layout declares. */
 export type Metadata = {
   readonly title?: string,
@@ -130,22 +162,90 @@ export type RouteRecord = {|
   readonly params: $ReadOnlyArray<RouteParamSpec>,
   readonly mdx: boolean,
   readonly file: string,
-  readonly page: () => Promise<PageModule>,
+  /**
+   * 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 = {|
+/**
+ * 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>,
+|};
+
+/**
+ * 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>>,
 |};
 
-/** A route table plus the not-found page. */
+/**
+ * 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 = {|
   readonly routes: $ReadOnlyArray<RouteRecord>,
-  readonly notFound: ?NotFoundRecord,
+  readonly notFound: $ReadOnlyArray<NotFoundBoundary>,
+  readonly errors: $ReadOnlyArray<ErrorBoundary>,
 |};
 
 /** A URL matched against the table. */
@@ -154,7 +254,40 @@ export type RouteMatch = {|
   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 = {|
   readonly pathname: string,
   readonly search: string,
@@ -165,7 +298,36 @@ export type ResolvedRoute = {|
   readonly layouts: $ReadOnlyArray<LayoutModule>,
   readonly data: mixed,
   readonly metadata: Metadata,
-  readonly status: 200 | 404,
+  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. */
@@ -176,6 +338,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;
@@ -267,6 +445,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.
  */
@@ -289,6 +479,60 @@ 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): {| readonly pathname: string, readonly search: string |} {
   const hash = url.indexOf("#");
@@ -342,11 +586,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?: {| 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);
@@ -356,21 +628,45 @@ 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, {
@@ -389,16 +685,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,
@@ -411,6 +900,9 @@ 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([
@@ -433,6 +925,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: [],
   };
 }
 
@@ -474,6 +973,157 @@ 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
 // ---------------------------------------------------------------------------
@@ -553,6 +1203,18 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
     }
     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);
@@ -587,6 +1249,14 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
     }
     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);
@@ -609,11 +1279,12 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
         }
         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),
+          loadOnce(load),
           ...matched.route.layouts.map((layout) => loadOnce(layout)),
         ]);
       },
@@ -705,21 +1376,85 @@ export hook useLoaderData(): mixed {
 /**
  * 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>
     </>
   );
 }
@@ -738,6 +1473,24 @@ function pageComponent(module: PageModule): React.ComponentType<PageRenderProps>
   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<LayoutRenderProps> {
   const component = module.default ?? module.Layout;
@@ -763,11 +1516,14 @@ function layoutComponent(module: LayoutModule): React.ComponentType<LayoutRender
  * 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.
+ * 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;
 }
 
@@ -889,6 +1645,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);