@uniflowed/router 0.0.0-alpha.31 → 0.0.0-alpha.33

package/internal/boundaries.js

@@ -86,7 +86,18 @@
 import * as React from "react";
 import { useEffect, useState } from "react";
 
+import { SYNTHESISED_SOURCE } from "./boundary-data.js";
 import { reportDiagnostic } from "./diagnostics.js";
+import type { RouteBoundary } from "./boundary-data.js";
+
+export type { BoundaryKind, RouteBoundary } from "./boundary-data.js";
+export {
+  ROOT_ERROR_ID,
+  ROUTE_ERROR_ID,
+  SYNTHESISED_SOURCE,
+  routeBoundaries,
+  suspenseId,
+} from "./boundary-data.js";
 
 /** The attribute a mark carries its boundary's id in. */
 export const BOUNDARY_ATTRIBUTE: string = "data-uf-boundary";
@@ -100,116 +111,6 @@ export const SOURCE_ATTRIBUTE: string = "data-uf-boundary-source";
 /** The name `uf dev` installs the on-demand report under. */
 export const BOUNDARY_GLOBAL: string = "__ufBoundaries";
 
-/**
- * What `file` says for the error boundary the build synthesises.
- *
- * `routesModuleSource` writes this string where a declared boundary has a path,
- * because the record has no module to name — the framework's own error page
- * renders in its place. Written out again rather than imported for the reason
- * `./devtools.js` gives about `DEVTOOLS_HOOK`: `@uniflowed/vite` is plain
- * JavaScript loaded by Vite before any Flow transform exists, so the import
- * cannot go either way. `boundaries.test.js` holds the two spellings together.
- */
-export const SYNTHESISED_SOURCE: string = "@uniflowed/router";
-
-/** Which kind of boundary a mark belongs to. */
-export type BoundaryKind = "suspense" | "error";
-
-/**
- * One boundary of a resolved route, as the marks and the report name it.
- *
- * `id` pairs the two marks and is stable for a boundary across renders, so a
- * navigation that keeps a boundary keeps its marks mounted. `above` is how many
- * of the route's layouts are outside it — the same number, spelled the same
- * way, that `ResolvedRoute["errorBoundary"].above` and every `loading` entry
- * carry, because there is no second vocabulary for where a thing sits in the
- * stack.
- *
- * `source` is the file it was declared in, and is `null` for every `<Suspense>`
- * boundary. That asymmetry is the route table's rather than this module's: an
- * error boundary is matched by path, so the table carries its `file`, while a
- * `$loading.js` is carried by depth alone. Adding a path to the loading
- * records would put one in every visitor's bundle to serve a report only
- * `uf dev` reads.
- */
-export type RouteBoundary = {|
-  readonly id: string,
-  readonly kind: BoundaryKind,
-  readonly above: number,
-  readonly source: ?string,
-|};
-
-/** The id of the `<Suspense>` boundary at `index` of a route's `loading`. */
-export function suspenseId(index: number): string {
-  return `suspense:${index}`;
-}
-
-/** The id of the boundary a route's own `$error.js` renders. */
-export const ROUTE_ERROR_ID: string = "error:route";
-
-/**
- * The id of the boundary that stands outside every layout.
- *
- * It has no module and renders the framework's page; it is what is between a
- * throw in a root layout, or in the error component itself, and an unmounted
- * document. Marked like any other, because "which subtree does the last resort
- * own" is exactly as unanswerable from the page as the rest.
- */
-export const ROOT_ERROR_ID: string = "error:root";
-
-/** The part of a resolved route this module reads. */
-type BoundedRoute = {
-  readonly errorBoundary: { readonly above: number, ... },
-  readonly loading: $ReadOnlyArray<{ readonly above: number, ... }>,
-  readonly error: mixed,
-  ...
-};
-
-/**
- * Every boundary a resolved route renders, in the order they nest.
- *
- * A `Map` rather than a list because it is read both ways: `RouteView` asks for
- * one by id as it builds the stack, and the report walks the values. One
- * function answering both is the point — an id `RouteView` marks and the report
- * cannot find is a boundary that silently disappears from the map, and
- * ubugeeei-prod/uf#636 made the same argument about an explanation that can
- * disagree with the thing it explains.
- *
- * The route's own error boundary is absent when the route *is* its error page,
- * which is exactly when `RouteView` does not render one: wrapping that page in
- * the boundary whose component it is would answer a throw inside it with
- * itself.
- *
- * @param resolved the route being rendered
- * @param errorSource the `file` of the nearest `$error.js`, when the table
- *   has one; `null` leaves the boundary named by its depth alone
- */
-export function routeBoundaries(
-  resolved: BoundedRoute,
-  errorSource: ?string,
-): Map<string, RouteBoundary> {
-  const found: Map<string, RouteBoundary> = new Map();
-  found.set(ROOT_ERROR_ID, {
-    id: ROOT_ERROR_ID,
-    kind: "error",
-    above: 0,
-    source: SYNTHESISED_SOURCE,
-  });
-  if (resolved.error == null) {
-    found.set(ROUTE_ERROR_ID, {
-      id: ROUTE_ERROR_ID,
-      kind: "error",
-      above: resolved.errorBoundary.above,
-      source: errorSource,
-    });
-  }
-  resolved.loading.forEach((boundary, index) => {
-    const id = suspenseId(index);
-    found.set(id, { id, kind: "suspense", above: boundary.above, source: null });
-  });
-  return found;
-}
-
 /**
  * Whether an edge that mounts now should be in the DOM immediately.
  *

package/internal/boundary-data.js

@@ -0,0 +1,88 @@
+// @flow
+//
+// React-free names for the boundaries a resolved route renders.
+
+/**
+ * What `file` says for the error boundary the build synthesises.
+ *
+ * `routesModuleSource` writes this string where a declared boundary has a path,
+ * because the record has no module to name: the framework's own error page
+ * renders in its place. This module is plain data so the routing surface and
+ * the dev-only DOM marker code can share one spelling without importing React.
+ */
+export const SYNTHESISED_SOURCE: string = "@uniflowed/router";
+
+/** Which kind of boundary a mark or payload row belongs to. */
+export type BoundaryKind = "suspense" | "error";
+
+/** The id of the `<Suspense>` boundary at `index` of a route's `loading`. */
+export function suspenseId(index: number): string {
+  return `suspense:${index}`;
+}
+
+/** The id of the boundary a route's own `$error.js` renders. */
+export const ROUTE_ERROR_ID: string = "error:route";
+
+/**
+ * The id of the boundary that stands outside every layout.
+ *
+ * It has no module and renders the framework's page; it is what is between a
+ * throw in a root layout, or in the error component itself, and an unmounted
+ * document.
+ */
+export const ROOT_ERROR_ID: string = "error:root";
+
+/**
+ * One boundary of a resolved route, in uf's vocabulary rather than React's.
+ *
+ * `id` is the stable name `RouteView` marks in the DOM today and the name a
+ * future element payload can put beside the chunk that completed it. `above`
+ * is how many layouts are outside the boundary.
+ */
+export type RouteBoundary = {|
+  readonly id: string,
+  readonly kind: BoundaryKind,
+  readonly above: number,
+  readonly source: ?string,
+|};
+
+/** The part of a resolved route the boundary map reads. */
+type BoundedRoute = {
+  readonly errorBoundary: { readonly above: number, ... },
+  readonly loading: $ReadOnlyArray<{ readonly above: number, ... }>,
+  readonly error: mixed,
+  ...
+};
+
+/**
+ * Every boundary a resolved route renders, in the order they nest.
+ *
+ * A `Map` rather than a list because callers read it both ways: `RouteView`
+ * asks for one by id as it builds the stack, while diagnostics and payload
+ * summaries walk the values.
+ */
+export function routeBoundaries(
+  resolved: BoundedRoute,
+  errorSource: ?string,
+): Map<string, RouteBoundary> {
+  const found: Map<string, RouteBoundary> = new Map();
+  found.set(ROOT_ERROR_ID, {
+    id: ROOT_ERROR_ID,
+    kind: "error",
+    above: 0,
+    source: SYNTHESISED_SOURCE,
+  });
+  if (resolved.error == null) {
+    found.set(ROUTE_ERROR_ID, {
+      id: ROUTE_ERROR_ID,
+      kind: "error",
+      above: resolved.errorBoundary.above,
+      source: errorSource,
+    });
+  }
+  resolved.loading.forEach((boundary, index) => {
+    const id = suspenseId(index);
+    found.set(id, { id, kind: "suspense", above: boundary.above, source: null });
+  });
+  return found;
+}

package/internal/inspector.js

@@ -27,7 +27,7 @@
 // lands this is the recorder it is fed to: `inspectStream` takes chunks and
 // knows nothing about who produced them.
 //
-// # It reads React's own markers, and no others
+// # It reads React's markers, plus uf's row marker
 //
 // Fizz writes a suspended boundary into the shell as an empty
 // `<template id="B:0">` followed by the fallback and closed by a `<!--/$-->`
@@ -46,6 +46,11 @@
 // content of these chunks is the application's own — with a step limit on every
 // loop for the same reason `./boundaries.js` has a `WALK_LIMIT`.
 //
+// The one uf-owned marker read here is `data-uf-row` on deferred payload row
+// scripts. The inspector does not parse the row JSON or attach semantics to
+// the value; it only keeps the terminal report from saying a row boundary built
+// an anonymous `script`.
+//
 // A marker that a chunk boundary happened to split is not attributed rather
 // than guessed at: the chunk is still counted, still timed, and says so. The
 // alternative is a report that is confidently wrong about which part of the
@@ -81,6 +86,8 @@
 // honest report is silence. That is also what keeps this from being a request
 // log: it fires for the pages the feature is about and for no others.
 
+import { PAYLOAD_ROW_ATTRIBUTE } from "./payload.js";
+
 /** How many chunks of one document are recorded before the rest are counted. */
 const CHUNK_LIMIT = 64;
 
@@ -412,6 +419,10 @@ function topLevelElements(markup: string, from: number): $ReadOnlyArray<string>
 export function describeTag(tag: string): string {
   const space = tag.search(/[\s/>]/);
   const name = tag.slice(1, space === -1 ? tag.length : space).toLowerCase();
+  const row = name === "script" ? attribute(tag, PAYLOAD_ROW_ATTRIBUTE) : null;
+  if (row != null && row !== "") {
+    return `deferred payload row ${row}`;
+  }
   const id = attribute(tag, "id");
   if (id != null && id !== "") {
     return `${name}#${id}`;

package/internal/payload-rows.js

@@ -113,7 +113,7 @@ export function createPayloadReader(
 ): PayloadReader {
   const slots: Map<number, Slot> = new Map();
   let disconnect: (() => void) | null = null;
-  let watching = false;
+  let reading = false;
 
   function slotFor(id: number): Slot {
     const existing = slots.get(id);
@@ -192,7 +192,7 @@ export function createPayloadReader(
   }
 
   function stop(): void {
-    watching = false;
+    reading = false;
     const off = disconnect;
     disconnect = null;
     if (off != null) {
@@ -200,28 +200,39 @@ export function createPayloadReader(
     }
   }
 
+  function observeRest(): void {
+    if (!reading || disconnect != null || finished() || observe == null) {
+      return;
+    }
+    disconnect = observe(sweep);
+    if (disconnect == null) {
+      reading = false;
+    }
+  }
+
   return {
     resolve(id: number): Promise<mixed> {
       const slot = slotFor(id);
       // A reference discovered after the watch started — a client navigation
       // decoding a payload of its own — still gets whatever is already in the
       // document, so the order the two calls happen in does not matter.
-      if (watching) {
+      if (reading) {
         sweep();
+        observeRest();
       }
       return slot.promise;
     },
     watch(): void {
-      if (watching || slots.size === 0) {
+      if (reading) {
         return;
       }
-      watching = true;
+      reading = true;
       sweep();
-      if (finished() || observe == null) {
-        watching = false;
+      if (slots.size > 0 && finished()) {
+        reading = false;
         return;
       }
-      disconnect = observe(sweep);
+      observeRest();
     },
     stop,
   };

package/internal/resolved-summary.js

@@ -0,0 +1,199 @@
+// @flow
+//
+// Module-free summaries of resolved routes.
+
+import { routeBoundaries, suspenseId } from "./boundary-data.js";
+import type { RouteBoundary } from "./boundary-data.js";
+import type { RouteParams, SearchParams } from "./routing.js";
+
+type RouteStatus = 200 | 401 | 403 | 404 | 500;
+
+type RouteMetadata = { readonly [string]: mixed, ... };
+
+type RouteErrorLike = {
+  readonly kind: "thrown" | "unauthorized" | "forbidden",
+  ...
+};
+
+type BoundaryLike = {
+  readonly above: number,
+  ...
+};
+
+type ModuleBoundaryLike = {
+  readonly above: number,
+  readonly module?: mixed,
+  ...
+};
+
+type SlotLike = {
+  readonly name: string,
+  readonly above: number,
+  readonly page: mixed,
+  readonly params: RouteParams,
+  readonly layouts: $ReadOnlyArray<mixed>,
+  readonly loading: $ReadOnlyArray<BoundaryLike>,
+  readonly templates: $ReadOnlyArray<BoundaryLike>,
+  readonly errorBoundary: ?ModuleBoundaryLike,
+  readonly slots: $ReadOnlyArray<SlotLike>,
+  ...
+};
+
+type RouteLike = {
+  readonly pathname: string,
+  readonly search: string,
+  readonly path: string,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  readonly layouts: $ReadOnlyArray<mixed>,
+  readonly data: mixed,
+  readonly deferred: mixed,
+  readonly metadata: RouteMetadata,
+  readonly viewTransition: ?string,
+  readonly status: RouteStatus,
+  readonly error: ?RouteErrorLike,
+  readonly errorBoundary: ModuleBoundaryLike,
+  readonly loading: $ReadOnlyArray<BoundaryLike>,
+  readonly templates: $ReadOnlyArray<BoundaryLike>,
+  readonly slots: $ReadOnlyArray<SlotLike>,
+  ...
+};
+
+export type ResolvedBoundarySummary = {|
+  readonly id: string,
+  readonly above: number,
+|};
+
+export type ResolvedTemplateSummary = {|
+  readonly above: number,
+|};
+
+export type ResolvedRouteErrorSummary =
+  | {| readonly kind: "thrown" |}
+  | {| readonly kind: "unauthorized" |}
+  | {| readonly kind: "forbidden" |};
+
+export type ResolvedErrorBoundarySummary = {|
+  readonly above: number,
+  readonly custom: boolean,
+  readonly rendered: boolean,
+|};
+
+export type ResolvedSlotSummary = {|
+  readonly name: string,
+  readonly above: number,
+  readonly active: boolean,
+  readonly params: RouteParams,
+  readonly layoutCount: number,
+  readonly loading: $ReadOnlyArray<ResolvedBoundarySummary>,
+  readonly templates: $ReadOnlyArray<ResolvedTemplateSummary>,
+  readonly errorBoundary: ?ResolvedErrorBoundarySummary,
+  readonly slots: $ReadOnlyArray<ResolvedSlotSummary>,
+|};
+
+export type ResolvedRouteSummary = {|
+  readonly pathname: string,
+  readonly search: string,
+  readonly path: string,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  readonly layoutCount: number,
+  readonly data: mixed,
+  readonly deferred: boolean,
+  readonly metadata: RouteMetadata,
+  readonly viewTransition: ?string,
+  readonly status: RouteStatus,
+  readonly error: ?ResolvedRouteErrorSummary,
+  readonly errorBoundary: ResolvedErrorBoundarySummary,
+  readonly loading: $ReadOnlyArray<ResolvedBoundarySummary>,
+  readonly templates: $ReadOnlyArray<ResolvedTemplateSummary>,
+  readonly slots: $ReadOnlyArray<ResolvedSlotSummary>,
+  readonly boundaries: $ReadOnlyArray<RouteBoundary>,
+|};
+
+/**
+ * The part of a `ResolvedRoute` that can cross to a payload or diagnostic.
+ *
+ * A resolved route carries loaded modules so `RouteView` can render today.
+ * The element payload in ubugeeei-prod/uf#519 needs the other half: route
+ * identity, data, metadata, status, and boundary names, with page/layout/
+ * fallback modules left behind in the renderer graph.
+ */
+export function summarizeResolvedRoute(
+  route: RouteLike,
+  errorSource?: ?string,
+): ResolvedRouteSummary {
+  return {
+    pathname: route.pathname,
+    search: route.search,
+    path: route.path,
+    params: route.params,
+    searchParams: route.searchParams,
+    layoutCount: route.layouts.length,
+    data: route.data,
+    deferred: route.deferred != null,
+    metadata: route.metadata,
+    viewTransition: route.viewTransition,
+    status: route.status,
+    error: summarizeError(route.error),
+    errorBoundary: summarizeErrorBoundary(route.errorBoundary, route.error == null),
+    loading: summarizeLoading(route.loading),
+    templates: summarizeTemplates(route.templates),
+    slots: route.slots.map(summarizeSlot),
+    boundaries: [...routeBoundaries(route, errorSource).values()],
+  };
+}
+
+function summarizeSlot(slot: SlotLike): ResolvedSlotSummary {
+  return {
+    name: slot.name,
+    above: slot.above,
+    active: slot.page != null,
+    params: slot.params,
+    layoutCount: slot.layouts.length,
+    loading: summarizeLoading(slot.loading),
+    templates: summarizeTemplates(slot.templates),
+    errorBoundary:
+      slot.errorBoundary == null ? null : summarizeErrorBoundary(slot.errorBoundary, true),
+    slots: slot.slots.map(summarizeSlot),
+  };
+}
+
+function summarizeLoading(
+  boundaries: $ReadOnlyArray<BoundaryLike>,
+): $ReadOnlyArray<ResolvedBoundarySummary> {
+  return boundaries.map((boundary, index) => ({
+    id: suspenseId(index),
+    above: boundary.above,
+  }));
+}
+
+function summarizeTemplates(
+  templates: $ReadOnlyArray<BoundaryLike>,
+): $ReadOnlyArray<ResolvedTemplateSummary> {
+  return templates.map((template) => ({ above: template.above }));
+}
+
+function summarizeErrorBoundary(
+  boundary: ModuleBoundaryLike,
+  rendered: boolean,
+): ResolvedErrorBoundarySummary {
+  return {
+    above: boundary.above,
+    custom: boundary.module != null,
+    rendered,
+  };
+}
+
+function summarizeError(error: ?RouteErrorLike): ?ResolvedRouteErrorSummary {
+  if (error == null) {
+    return null;
+  }
+  if (error.kind === "unauthorized") {
+    return { kind: "unauthorized" };
+  }
+  if (error.kind === "forbidden") {
+    return { kind: "forbidden" };
+  }
+  return { kind: "thrown" };
+}

package/internal/routing.js

@@ -31,29 +31,57 @@ export type LoadingRecord<TLoading = mixed> = {|
   readonly module: RouteModule<TLoading>,
 |};
 
+/** One `$error.js` inside a slot, as the route table carries it. */
+export type SlotErrorBoundaryRecord<TError = mixed> = {|
+  readonly above: number,
+  readonly module: RouteModule<TError>,
+|};
+
 /** One parallel-route slot, as the route table carries it. */
-export type SlotRecord<TPage = mixed, TLayout = mixed> = {|
+export type SlotRecord<
+  TPage = mixed,
+  TLayout = mixed,
+  TTemplate = mixed,
+  TLoading = mixed,
+  TError = mixed,
+> = {|
   readonly name: string,
   readonly above: number,
   readonly defaultPage: ?RouteModule<TPage>,
   readonly defaultFile?: string,
   readonly defaultMdx?: boolean,
-  readonly routes: $ReadOnlyArray<SlotRouteRecord<TPage, TLayout>>,
+  readonly defaultErrorBoundary?: ?SlotErrorBoundaryRecord<TError>,
+  readonly routes: $ReadOnlyArray<SlotRouteRecord<TPage, TLayout, TTemplate, TLoading, TError>>,
 |};
 
 /** One page inside a slot. */
-export type SlotRouteRecord<TPage = mixed, TLayout = mixed> = {|
+export type SlotRouteRecord<
+  TPage = mixed,
+  TLayout = mixed,
+  TTemplate = mixed,
+  TLoading = mixed,
+  TError = mixed,
+> = {|
   readonly path: string,
   readonly params: $ReadOnlyArray<RouteParamSpec>,
   readonly mdx: boolean,
   readonly file: string,
   readonly page: RouteModule<TPage>,
   readonly layouts: $ReadOnlyArray<RouteModule<TLayout>>,
-  readonly slots: $ReadOnlyArray<SlotRecord<TPage, TLayout>>,
+  readonly loading?: $ReadOnlyArray<LoadingRecord<TLoading>>,
+  readonly templates?: $ReadOnlyArray<TemplateRecord<TTemplate>>,
+  readonly errorBoundary?: ?SlotErrorBoundaryRecord<TError>,
+  readonly slots: $ReadOnlyArray<SlotRecord<TPage, TLayout, TTemplate, TLoading, TError>>,
 |};
 
 /** One entry of the generated route table. */
-export type RouteRecord<TPage = mixed, TLayout = mixed, TTemplate = mixed, TLoading = mixed> = {|
+export type RouteRecord<
+  TPage = mixed,
+  TLayout = mixed,
+  TTemplate = mixed,
+  TLoading = mixed,
+  TError = mixed,
+> = {|
   readonly path: string,
   readonly params: $ReadOnlyArray<RouteParamSpec>,
   readonly mdx: boolean,
@@ -62,7 +90,7 @@ export type RouteRecord<TPage = mixed, TLayout = mixed, TTemplate = mixed, TLoad
   readonly layouts: $ReadOnlyArray<RouteModule<TLayout>>,
   readonly loading?: $ReadOnlyArray<LoadingRecord<TLoading>>,
   readonly templates?: $ReadOnlyArray<TemplateRecord<TTemplate>>,
-  readonly slots?: $ReadOnlyArray<SlotRecord<TPage, TLayout>>,
+  readonly slots?: $ReadOnlyArray<SlotRecord<TPage, TLayout, TTemplate, TLoading, TError>>,
 |};
 
 /** One not-found boundary: the page for a path under `path` that matched nothing. */
@@ -90,12 +118,12 @@ export type RouteTable<
   TLoading = mixed,
   TError = mixed,
 > = {|
-  readonly routes: $ReadOnlyArray<RouteRecord<TPage, TLayout, TTemplate, TLoading>>,
+  readonly routes: $ReadOnlyArray<RouteRecord<TPage, TLayout, TTemplate, TLoading, TError>>,
   readonly notFound: $ReadOnlyArray<NotFoundBoundary<TPage, TLayout>>,
   readonly errors: $ReadOnlyArray<ErrorBoundary<TError, TLayout>>,
 |};
 
-type UnknownRouteRecord = RouteRecord<mixed, mixed, mixed, mixed>;
+type UnknownRouteRecord = RouteRecord<mixed, mixed, mixed, mixed, mixed>;
 
 /** A URL matched against a table. */
 export type RouteMatch<TRoute: { +path: string, ... } = UnknownRouteRecord> = {|

package/internal/runtime.js

@@ -463,11 +463,24 @@ export type RouteRecord = RoutingRouteRecord<
   LayoutModule,
   TemplateModule,
   LoadingModule,
+  ErrorModule,
 >;
 
-export type SlotRecord = RoutingSlotRecord<PageModule, LayoutModule>;
+export type SlotRecord = RoutingSlotRecord<
+  PageModule,
+  LayoutModule,
+  TemplateModule,
+  LoadingModule,
+  ErrorModule,
+>;
 
-export type SlotRouteRecord = RoutingSlotRouteRecord<PageModule, LayoutModule>;
+export type SlotRouteRecord = RoutingSlotRouteRecord<
+  PageModule,
+  LayoutModule,
+  TemplateModule,
+  LoadingModule,
+  ErrorModule,
+>;
 
 export type TemplateRecord = RoutingTemplateRecord<TemplateModule>;
 
@@ -487,6 +500,21 @@ export type RouteTable = RoutingRouteTable<
 
 export type RouteMatch = RoutingRouteMatch<RouteRecord>;
 
+type ResolvedTemplate = {|
+  readonly above: number,
+  readonly module: TemplateModule,
+|};
+
+type ResolvedSlotErrorBoundary = {|
+  readonly above: number,
+  readonly module: ?ErrorModule,
+|};
+
+type SlotErrorBoundaryLoader = {|
+  readonly above: number,
+  readonly module: () => Promise<ErrorModule>,
+|};
+
 /**
  * A match whose modules are loaded and whose loader has run or is running — or,
  * when `error` is set, the error page that stands in for it.
@@ -567,10 +595,7 @@ export type ResolvedRoute = {|
    * than walked to, and templates are accumulated on the walk down to a route
    * the URL never reached.
    */
-  readonly templates: $ReadOnlyArray<{|
-    readonly above: number,
-    readonly module: TemplateModule,
-  |}>,
+  readonly templates: $ReadOnlyArray<ResolvedTemplate>,
   /**
    * The slots this route renders, outermost first, already imported.
    *
@@ -600,6 +625,9 @@ export type ResolvedSlot = {|
   readonly page: ?PageModule,
   readonly params: RouteParams,
   readonly layouts: $ReadOnlyArray<LayoutModule>,
+  readonly loading: $ReadOnlyArray<{| readonly above: number, readonly module: LoadingModule |}>,
+  readonly templates: $ReadOnlyArray<ResolvedTemplate>,
+  readonly errorBoundary: ?ResolvedSlotErrorBoundary,
   readonly slots: $ReadOnlyArray<ResolvedSlot>,
 |};
 
@@ -860,6 +888,9 @@ async function resolveSlot(
     page: null,
     params: fallbackParams,
     layouts: [],
+    loading: [],
+    templates: [],
+    errorBoundary: null,
     slots: [],
   };
 
@@ -875,7 +906,11 @@ async function resolveSlot(
     if (module == null) {
       return empty;
     }
-    return { ...empty, page: withoutLoader(module, record.defaultFile ?? record.name) };
+    return {
+      ...empty,
+      page: withoutLoader(module, record.defaultFile ?? record.name),
+      errorBoundary: await resolveSlotErrorBoundary(record.defaultErrorBoundary ?? null, 0),
+    };
   }
 
   const route = matched.route;
@@ -892,18 +927,42 @@ async function resolveSlot(
   if (loaded.length !== layouts.length) {
     return empty;
   }
+  const loading = await resolveLoadingRecords(route.loading ?? [], loaded.length);
+  const templates = await resolveTemplateRecords(route.templates ?? [], loaded.length);
+  const errorBoundary = await resolveSlotErrorBoundary(route.errorBoundary ?? null, loaded.length);
   return {
     name: record.name,
     above,
     page: withoutLoader(page, route.file),
     params: matched.params,
     layouts: loaded,
+    loading,
+    templates,
+    errorBoundary,
     // The slot's own layouts are what a nested slot is measured against, so
     // the count handed down is this slot's rather than the route's.
     slots: await resolveSlots(route.slots, pathname, loaded.length, matched.params),
   };
 }
 
+async function resolveSlotErrorBoundary(
+  boundary: ?SlotErrorBoundaryLoader,
+  layoutCount: number,
+): Promise<?ResolvedSlotErrorBoundary> {
+  if (boundary == null) {
+    return null;
+  }
+  const above = Math.min(boundary.above, layoutCount);
+  try {
+    return { module: await loadOnce(boundary.module), above };
+  } catch {
+    // Keep the declared depth even when the custom file fails to import. The
+    // framework fallback still contains the slot instead of escalating the
+    // page beside it.
+    return { module: null, above };
+  }
+}
+
 /**
  * A module, or `null` when it would not import.
  *
@@ -963,8 +1022,14 @@ function withoutLoader(module: PageModule, file: string): PageModule {
 async function resolveTemplates(
   route: RouteRecord,
   layoutCount: number,
-): Promise<$ReadOnlyArray<{| readonly above: number, readonly module: TemplateModule |}>> {
-  const records = route.templates ?? [];
+): Promise<$ReadOnlyArray<ResolvedTemplate>> {
+  return resolveTemplateRecords(route.templates ?? [], layoutCount);
+}
+
+async function resolveTemplateRecords(
+  records: $ReadOnlyArray<TemplateRecord>,
+  layoutCount: number,
+): Promise<$ReadOnlyArray<ResolvedTemplate>> {
   if (records.length === 0) {
     return [];
   }
@@ -1000,7 +1065,13 @@ async function resolveLoading(
   route: RouteRecord,
   layoutCount: number,
 ): Promise<$ReadOnlyArray<{| readonly above: number, readonly module: LoadingModule |}>> {
-  const records = route.loading ?? [];
+  return resolveLoadingRecords(route.loading ?? [], layoutCount);
+}
+
+async function resolveLoadingRecords(
+  records: $ReadOnlyArray<LoadingRecord>,
+  layoutCount: number,
+): Promise<$ReadOnlyArray<{| readonly above: number, readonly module: LoadingModule |}>> {
   if (records.length === 0) {
     return [];
   }
@@ -2510,7 +2581,16 @@ function loadingComponent(module: LoadingModule): React.ComponentType<{||}> {
  * the React Compiler's aliasing inference gave up on, and a component it
  * cannot compile is a component it does not memoise.
  */
-function insideTemplates(element: React.Node, resolved: ResolvedRoute, depth: number): React.Node {
+function insideTemplates(
+  element: React.Node,
+  resolved: {
+    readonly pathname: string,
+    readonly params: RouteParams,
+    readonly templates: $ReadOnlyArray<ResolvedTemplate>,
+    ...
+  },
+  depth: number,
+): React.Node {
   let out = element;
   for (let index = resolved.templates.length - 1; index >= 0; index -= 1) {
     const entry = resolved.templates[index];
@@ -2593,13 +2673,40 @@ component SlotView(slot: ResolvedSlot) {
   let element: React.Node = (
     <Page params={slot.params} searchParams={resolved.searchParams} data={undefined} />
   );
-  for (let depth = slot.layouts.length; depth > 0; depth -= 1) {
-    const Layout = layoutComponent(slot.layouts[depth - 1]);
-    element = (
-      <Layout {...slotsAt(slot.slots, depth)} params={slot.params}>
-        {element}
-      </Layout>
-    );
+  const templateContext = {
+    pathname: resolved.pathname,
+    params: slot.params,
+    templates: slot.templates,
+  };
+  for (let depth = slot.layouts.length; depth >= 0; depth -= 1) {
+    for (let index = slot.loading.length - 1; index >= 0; index -= 1) {
+      const boundary = slot.loading[index];
+      if (boundary.above !== depth) {
+        continue;
+      }
+      const Fallback = loadingComponent(boundary.module);
+      element = <Suspense fallback={<Fallback />}>{element}</Suspense>;
+    }
+    const errorBoundary = slot.errorBoundary;
+    if (errorBoundary != null && errorBoundary.above === depth) {
+      element = (
+        <RouteErrorBoundary
+          module={errorBoundary.module}
+          resetKey={`${resolved.pathname}:${slot.name}`}
+        >
+          {element}
+        </RouteErrorBoundary>
+      );
+    }
+    element = insideTemplates(element, templateContext, depth);
+    if (depth > 0) {
+      const Layout = layoutComponent(slot.layouts[depth - 1]);
+      element = (
+        <Layout {...slotsAt(slot.slots, depth)} params={slot.params}>
+          {element}
+        </Layout>
+      );
+    }
   }
   return element;
 }

package/native.js

@@ -0,0 +1,391 @@
+// @flow
+//
+// `@uniflowed/router/native`: the React Native navigator contract.
+//
+// Native routes use the same generated table as the web router, but not the
+// browser's URL bar or History API. This adapter keeps the shared part small:
+// it resolves a uf route path against the table, refuses destinations the
+// native bundle cannot render, and hands a navigator-shaped event to the app's
+// own navigation runtime. Rendering the tree is still the renderer/host-config
+// half of the React Native target.
+
+import type { RouteParams, RouteRecord, RouteTable } from "./internal/routing.js";
+import { hasClientPage, matchRoute, splitUrl } from "./internal/routing.js";
+
+export type NativeNavigationKind = "push" | "replace" | "prefetch";
+
+export type NativeNavigationEvent = {|
+  readonly kind: NativeNavigationKind,
+  readonly href: string,
+  readonly pathname: string,
+  readonly search: string,
+  readonly route: string,
+  readonly params: RouteParams,
+|};
+
+export type NativeScreenMap = {
+  readonly [route: string]: string,
+};
+
+export type NativeScreenEntry = {|
+  readonly screen: string,
+  readonly route: string,
+  readonly file: string,
+|};
+
+export type NativeScreenManifest = {|
+  readonly screens: NativeScreenMap,
+  readonly entries: $ReadOnlyArray<NativeScreenEntry>,
+|};
+
+export type NativeScreenNameRoute = {|
+  readonly path: string,
+  readonly file: string,
+|};
+
+export type NativeScreenManifestOptions = {|
+  readonly name?: (route: NativeScreenNameRoute) => string,
+|};
+
+export type NativeScreenPayload = {|
+  readonly screen: string,
+  readonly href: string,
+  readonly pathname: string,
+  readonly search: string,
+  readonly route: string,
+  readonly params: RouteParams,
+|};
+
+export type NativeScreenNavigationState = {|
+  readonly params: RouteParams,
+  readonly href: string,
+  readonly pathname: string,
+  readonly search: string,
+  readonly route: string,
+|};
+
+export type NativeNavigator = {|
+  readonly push?: (event: NativeNavigationEvent) => mixed | Promise<mixed>,
+  readonly replace?: (event: NativeNavigationEvent) => mixed | Promise<mixed>,
+  readonly prefetch?: (event: NativeNavigationEvent) => mixed | Promise<mixed>,
+|};
+
+export type NativeScreenNavigator = {|
+  readonly push?: (screen: string, state: NativeScreenNavigationState) => mixed | Promise<mixed>,
+  readonly replace?: (screen: string, state: NativeScreenNavigationState) => mixed | Promise<mixed>,
+  readonly prefetch?: (
+    screen: string,
+    state: NativeScreenNavigationState,
+  ) => mixed | Promise<mixed>,
+|};
+
+export type NativeRouter = {|
+  readonly push: (to: string) => Promise<void>,
+  readonly replace: (to: string) => Promise<void>,
+  readonly prefetch: (to: string) => Promise<void>,
+  readonly resolve: (to: string, kind?: NativeNavigationKind) => NativeNavigationEvent,
+|};
+
+export type NativeNavigationErrorCode =
+  | "duplicate-screen"
+  | "external-url"
+  | "fragment"
+  | "relative-url"
+  | "missing-route"
+  | "missing-screen"
+  | "server-only-route"
+  | "missing-navigator-method";
+
+export class NativeNavigationError extends Error {
+  code: NativeNavigationErrorCode;
+  href: string;
+  route: ?string;
+
+  constructor(code: NativeNavigationErrorCode, message: string, href: string, route?: ?string) {
+    super(message);
+    this.name = "NativeNavigationError";
+    this.code = code;
+    this.href = href;
+    this.route = route ?? null;
+  }
+}
+
+export function createNativeRouter(
+  table: RouteTable<mixed, mixed, mixed, mixed, mixed>,
+  navigator: NativeNavigator,
+): NativeRouter {
+  const resolve = (to: string, kind?: NativeNavigationKind = "push"): NativeNavigationEvent =>
+    resolveNativeNavigation(table, to, kind);
+
+  return {
+    resolve,
+    push: async (to) => {
+      const event = resolve(to, "push");
+      await invokeNavigator(navigator, event);
+    },
+    replace: async (to) => {
+      const event = resolve(to, "replace");
+      await invokeNavigator(navigator, event);
+    },
+    prefetch: async (to) => {
+      const event = resolve(to, "prefetch");
+      await loadNativeRoute(table, event.pathname);
+      if (typeof navigator.prefetch === "function") {
+        await navigator.prefetch(event);
+      }
+    },
+  };
+}
+
+export function createNativeScreenRouter(
+  table: RouteTable<mixed, mixed, mixed, mixed, mixed>,
+  screens: NativeScreenMap,
+  navigator: NativeScreenNavigator,
+): NativeRouter {
+  return createNativeRouter(table, {
+    push: (event) => invokeScreenNavigator(navigator, screens, event),
+    replace: (event) => invokeScreenNavigator(navigator, screens, event),
+    prefetch: (event) => {
+      if (typeof navigator.prefetch !== "function") return;
+      return invokeScreenNavigator(navigator, screens, event);
+    },
+  });
+}
+
+export function createNativeScreenManifest(
+  table: RouteTable<mixed, mixed, mixed, mixed, mixed>,
+  options?: NativeScreenManifestOptions,
+): NativeScreenManifest {
+  const screens: { [string]: string } = {};
+  const entries: Array<NativeScreenEntry> = [];
+  const seen = new Map<string, string>();
+  for (const route of table.routes) {
+    if (!hasClientPage(route)) {
+      continue;
+    }
+    const screen = screenNameFor(route, options);
+    const already = seen.get(screen);
+    if (already != null) {
+      throw new NativeNavigationError(
+        "duplicate-screen",
+        `@uniflowed/router/native: ${route.path} and ${already} both map to native screen ${screen}`,
+        route.path,
+        route.path,
+      );
+    }
+    seen.set(screen, route.path);
+    screens[route.path] = screen;
+    entries.push({ screen, route: route.path, file: route.file });
+  }
+  return { screens, entries };
+}
+
+export function nativeScreenName(routePath: string): string {
+  const segments = routePath.split("/").filter((segment) => segment !== "");
+  if (segments.length === 0) {
+    return "Home";
+  }
+  const name = segments
+    .map((segment) => {
+      if (segment.startsWith(":") && segment.endsWith("*")) {
+        return `All${titlePart(segment.slice(1, -1))}`;
+      }
+      if (segment.startsWith(":")) {
+        return `By${titlePart(segment.slice(1))}`;
+      }
+      return titlePart(segment);
+    })
+    .join("");
+  return name === "" ? "Screen" : name;
+}
+
+export function resolveNativeNavigation(
+  table: RouteTable<mixed, mixed, mixed, mixed, mixed>,
+  to: string,
+  kind?: NativeNavigationKind = "push",
+): NativeNavigationEvent {
+  const href = normalizeNativeHref(to);
+  const { pathname, search } = splitUrl(href);
+  const matched = matchRoute(table.routes, pathname);
+  if (matched == null) {
+    throw new NativeNavigationError(
+      "missing-route",
+      `@uniflowed/router/native: ${href} does not match a native route in this table`,
+      href,
+    );
+  }
+  if (!hasClientPage(matched.route)) {
+    throw new NativeNavigationError(
+      "server-only-route",
+      `@uniflowed/router/native: ${matched.route.path} is not in the native route table; ` +
+        "it has no page module for this bundle",
+      href,
+      matched.route.path,
+    );
+  }
+  return {
+    kind,
+    href,
+    pathname,
+    search,
+    route: matched.route.path,
+    params: matched.params,
+  };
+}
+
+export function nativeScreenPayload(
+  event: NativeNavigationEvent,
+  screens: NativeScreenMap,
+): NativeScreenPayload {
+  const screen = screens[event.route];
+  if (typeof screen !== "string" || screen === "") {
+    throw new NativeNavigationError(
+      "missing-screen",
+      `@uniflowed/router/native: ${event.route} has no native screen mapping`,
+      event.href,
+      event.route,
+    );
+  }
+  return {
+    screen,
+    href: event.href,
+    pathname: event.pathname,
+    search: event.search,
+    route: event.route,
+    params: event.params,
+  };
+}
+
+export function nativeScreenNavigationState(
+  payload: NativeScreenPayload,
+): NativeScreenNavigationState {
+  return {
+    params: payload.params,
+    href: payload.href,
+    pathname: payload.pathname,
+    search: payload.search,
+    route: payload.route,
+  };
+}
+
+function normalizeNativeHref(to: string): string {
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(to) || to.startsWith("//")) {
+    throw new NativeNavigationError(
+      "external-url",
+      `@uniflowed/router/native: ${to} is an external URL, and a native navigator needs an app route`,
+      to,
+    );
+  }
+  if (!to.startsWith("/")) {
+    throw new NativeNavigationError(
+      "relative-url",
+      `@uniflowed/router/native: ${to} is relative, and native navigation has no document URL to resolve it against`,
+      to,
+    );
+  }
+  if (to.includes("#")) {
+    throw new NativeNavigationError(
+      "fragment",
+      `@uniflowed/router/native: ${to} contains a fragment, and native routes do not have document anchors`,
+      to,
+    );
+  }
+  return splitUrl(to).pathname + splitUrl(to).search;
+}
+
+function screenNameFor(
+  route: RouteRecord<mixed, mixed, mixed, mixed, mixed>,
+  options?: NativeScreenManifestOptions,
+): string {
+  const screen =
+    options?.name?.({ path: route.path, file: route.file }) ?? nativeScreenName(route.path);
+  if (screen === "") {
+    throw new NativeNavigationError(
+      "missing-screen",
+      `@uniflowed/router/native: ${route.path} mapped to an empty native screen name`,
+      route.path,
+      route.path,
+    );
+  }
+  return screen;
+}
+
+function titlePart(segment: string): string {
+  const cleaned = segment
+    .replace(/^\[+|\]+$/g, "")
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim();
+  if (cleaned === "") {
+    return "Segment";
+  }
+  return cleaned
+    .split(/\s+/)
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+async function invokeNavigator(
+  navigator: NativeNavigator,
+  event: NativeNavigationEvent,
+): Promise<void> {
+  if (event.kind === "push") {
+    if (typeof navigator.push !== "function") {
+      throw missingMethod(event);
+    }
+    await navigator.push(event);
+    return;
+  }
+  if (event.kind === "replace") {
+    if (typeof navigator.replace !== "function") {
+      throw missingMethod(event);
+    }
+    await navigator.replace(event);
+  }
+}
+
+function missingMethod(event: NativeNavigationEvent): NativeNavigationError {
+  return new NativeNavigationError(
+    "missing-navigator-method",
+    `@uniflowed/router/native: the native navigator does not implement ${event.kind}()`,
+    event.href,
+    event.route,
+  );
+}
+
+async function invokeScreenNavigator(
+  navigator: NativeScreenNavigator,
+  screens: NativeScreenMap,
+  event: NativeNavigationEvent,
+): Promise<void> {
+  const payload = nativeScreenPayload(event, screens);
+  const state = nativeScreenNavigationState(payload);
+  if (event.kind === "push") {
+    if (typeof navigator.push !== "function") {
+      throw missingMethod(event);
+    }
+    await navigator.push(payload.screen, state);
+    return;
+  }
+  if (event.kind === "replace") {
+    if (typeof navigator.replace !== "function") {
+      throw missingMethod(event);
+    }
+    await navigator.replace(payload.screen, state);
+    return;
+  }
+  if (typeof navigator.prefetch !== "function") {
+    throw missingMethod(event);
+  }
+  await navigator.prefetch(payload.screen, state);
+}
+
+async function loadNativeRoute(
+  table: RouteTable<mixed, mixed, mixed, mixed, mixed>,
+  pathname: string,
+): Promise<void> {
+  const matched = matchRoute(table.routes, pathname);
+  if (matched == null || !hasClientPage(matched.route)) {
+    return;
+  }
+  await Promise.all([matched.route.page?.(), ...matched.route.layouts.map((layout) => layout())]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.31",
+  "version": "0.0.0-alpha.33",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -14,6 +14,7 @@
     ".": "./index.js",
     "./action": "./action.js",
     "./client": "./client.js",
+    "./native": "./native.js",
     "./server": "./server.js",
     "./routing": "./routing.js",
     "./package.json": "./package.json",
@@ -27,6 +28,7 @@
     "index.js",
     "internal",
     "middleware.js",
+    "native.js",
     "routing.js",
     "server.js",
     "!*.test.js"
@@ -36,7 +38,7 @@
     "react-dom": ">=19"
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.31",
-    "@uniflowed/server": "0.0.0-alpha.31"
+    "@uniflowed/hooks": "0.0.0-alpha.33",
+    "@uniflowed/server": "0.0.0-alpha.33"
   }
 }

package/routing.js

@@ -22,6 +22,14 @@ export type {
   SlotRouteRecord,
   TemplateRecord,
 } from "./internal/routing.js";
+export type {
+  ResolvedBoundarySummary,
+  ResolvedErrorBoundarySummary,
+  ResolvedRouteErrorSummary,
+  ResolvedRouteSummary,
+  ResolvedSlotSummary,
+  ResolvedTemplateSummary,
+} from "./internal/resolved-summary.js";
 
 export {
   ForbiddenError,
@@ -40,3 +48,4 @@ export {
   splitUrl,
   unauthorized,
 } from "./internal/routing.js";
+export { summarizeResolvedRoute } from "./internal/resolved-summary.js";