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

package/client.js

@@ -12,15 +12,15 @@ import { startTransition } from "react";
 import { hydrateRoot } from "react-dom/client";
 
 import { type AppProps, type RouteTable, installRoutes, resolveMatch } from "./internal/runtime.js";
-import { DATA_ID, ROOT_ID } from "./server.js";
+import { DATA_ID, ROOT_ID } from "./internal/document.js";
 
 /**
  * Hydrate the current document.
  */
 export async function hydrate(options: {|
-  +App: React.ComponentType<AppProps>,
-  +routes: RouteTable["routes"],
-  +notFound: RouteTable["notFound"],
+  readonly App: React.ComponentType<AppProps>,
+  readonly routes: RouteTable["routes"],
+  readonly notFound: RouteTable["notFound"],
 |}): Promise<void> {
   const table: RouteTable = { routes: options.routes, notFound: options.notFound };
   installRoutes(table);

package/handler.js

@@ -0,0 +1,210 @@
+// @flow
+//
+// Route handlers: a path that answers a request instead of rendering a page.
+//
+// `app/api/users/_uf.route.js` exporting `GET` and `POST` serves
+// `/api/users`. A handler takes a `Request` and returns a `Response` — the
+// platform's own types, not a framework's wrapper — because that is what runs
+// unchanged on Node.js, Bun, Deno and a Cloudflare Worker, and uf's whole
+// position is that the host is a capability rather than a target.
+//
+//   // app/api/users/[id]/_uf.route.js
+//   // @flow
+//   export async function GET(request: Request, context: HandlerContext) {
+//     const user = await find(context.params.id);
+//     return user == null
+//       ? new Response("not found", { status: 404 })
+//       : Response.json(user);
+//   }
+//
+// # What the dispatcher decides, and what it does not
+//
+// It matches a path and a method and calls a function. It does not catch the
+// handler's errors, because a handler that throws is a bug the host's own
+// error reporting should see, and swallowing it into a 500 here would hide it.
+// It does answer `405` itself when the path matches and the method does not,
+// with the `Allow` header the specification requires — that is not the
+// handler's business, and every handler would otherwise write it.
+
+import { contextFor, drainDeferred, runWithContext } from "@uniflowed/server/host";
+import type { RouteParams } from "./internal/runtime.js";
+
+/** What a handler is given besides the request. */
+export type HandlerContext = {|
+  /** The `[param]` and `[...rest]` segments of the matched path. */
+  readonly params: RouteParams,
+  /** The parsed query string, for the common case of reading one value. */
+  readonly searchParams: URLSearchParams,
+|};
+
+/** One exported method of a handler module. */
+export type Handler = (request: Request, context: HandlerContext) => Response | Promise<Response>;
+
+/** A handler module, as the generated table loads it. */
+export type HandlerModule = { readonly [method: string]: mixed };
+
+/** One entry of the generated handler table. */
+export type HandlerRecord = {|
+  readonly path: string,
+  readonly params: $ReadOnlyArray<{| readonly name: string, readonly catchAll: boolean |}>,
+  readonly file: string,
+  readonly load: () => Promise<HandlerModule>,
+|};
+
+/**
+ * The methods a handler may export.
+ *
+ * A closed list, because the alternative is treating every export as a method
+ * — and a module that exports a helper would then answer requests with it.
+ * `HEAD` falls back to `GET` with the body dropped, which is what a client
+ * asking for headers expects and what nobody remembers to write.
+ */
+const METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+
+/**
+ * Match a request against the handler table and run it.
+ *
+ * Returns `null` when no path matches, which is the caller's signal to carry
+ * on — a request for `/about` is a page, and the dispatcher declining is how
+ * it says so.
+ */
+export function createDispatcher(options: {|
+  readonly handlers: $ReadOnlyArray<HandlerRecord>,
+|}): (request: Request) => Promise<Response | null> {
+  // Longest path first, so `/api/users/new` wins over `/api/users/[id]` and a
+  // catch-all is the last thing tried.
+  const table = [...options.handlers].sort((a, b) => specificity(b.path) - specificity(a.path));
+
+  return async function dispatch(request: Request): Promise<Response | null> {
+    const url = new URL(request.url);
+    for (const record of table) {
+      const params = matchPath(record.path, url.pathname);
+      if (params == null) {
+        continue;
+      }
+
+      const module = await record.load();
+      const method = request.method.toUpperCase();
+      const handler = pick(module, method);
+      if (handler == null) {
+        return methodNotAllowed(module);
+      }
+
+      // Inside the request, so a handler that calls `headers()`, `cookies()`
+      // or `after()` has something to answer about. `drainDeferred` runs after
+      // the response is in hand, which is what `after()` means.
+      const context = contextFor(request);
+      const response = await runWithContext(context, () =>
+        handler(request, {
+          params,
+          searchParams: url.searchParams,
+        }),
+      );
+      await drainDeferred(context);
+
+      // A `HEAD` answered by `GET` must not carry the body. The test is
+      // against the module's own `HEAD`, not `pick`'s — `pick` falls back to
+      // `GET`, so asking it whether a `HEAD` exists always said yes and the
+      // body went out anyway.
+      if (method === "HEAD" && typeof module.HEAD !== "function") {
+        return new Response(null, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers,
+        });
+      }
+      return response;
+    }
+    return null;
+  };
+}
+
+/** The function for a method, falling back to `GET` for `HEAD`. */
+function pick(module: HandlerModule, method: string): Handler | null {
+  const own = module[method];
+  if (typeof own === "function") {
+    return own as $FlowFixMe;
+  }
+  if (method === "HEAD" && typeof module.GET === "function") {
+    return module.GET as $FlowFixMe;
+  }
+  return null;
+}
+
+/**
+ * `405`, with the `Allow` header naming what the path does accept.
+ *
+ * Required by the specification, and the reason a client can tell "you may not
+ * do that here" from "there is nothing here".
+ */
+function methodNotAllowed(module: HandlerModule): Response {
+  const own = new Set(METHODS.filter((method) => typeof module[method] === "function"));
+  // A module exporting `GET` also answers `HEAD`, so `Allow` has to say so.
+  if (own.has("GET")) {
+    own.add("HEAD");
+  }
+  // Filtered through `METHODS` rather than listed in insertion order, so the
+  // header reads in the conventional order however the module was written.
+  return new Response(null, {
+    status: 405,
+    headers: { allow: METHODS.filter((method) => own.has(method)).join(", ") },
+  });
+}
+
+/**
+ * Match one route path against a pathname, returning its parameters.
+ *
+ * `null` rather than an empty object when it does not match, so a route with
+ * no parameters is still distinguishable from a miss.
+ */
+function matchPath(routePath: string, pathname: string): RouteParams | null {
+  const wanted = segmentsOf(routePath);
+  const given = segmentsOf(pathname);
+  const params: { [string]: string | Array<string> } = {};
+
+  for (let index = 0; index < wanted.length; index += 1) {
+    const segment = wanted[index];
+    if (segment.startsWith(":") && segment.endsWith("*")) {
+      // A catch-all takes the rest, and matches zero segments as well as many.
+      params[segment.slice(1, -1)] = given.slice(index);
+      return params as $FlowFixMe;
+    }
+    if (index >= given.length) {
+      return null;
+    }
+    if (segment.startsWith(":")) {
+      params[segment.slice(1)] = given[index];
+      continue;
+    }
+    if (segment !== given[index]) {
+      return null;
+    }
+  }
+
+  return wanted.length === given.length ? (params as $FlowFixMe) : null;
+}
+
+function segmentsOf(value: string): Array<string> {
+  return value.split("/").filter((segment) => segment !== "");
+}
+
+/**
+ * How specific a path is, so the table can be tried in the right order.
+ *
+ * A literal segment is worth more than a parameter and a parameter more than a
+ * catch-all, and a longer path outranks a shorter one — which is what makes
+ * `/api/users/new` win over `/api/users/[id]`.
+ */
+function specificity(routePath: string): number {
+  let score = 0;
+  for (const segment of segmentsOf(routePath)) {
+    if (segment.startsWith(":") && segment.endsWith("*")) {
+      score += 1;
+    } else if (segment.startsWith(":")) {
+      score += 10;
+    } else {
+      score += 100;
+    }
+  }
+  return score;
+}

package/index.js

@@ -49,16 +49,18 @@ export {
 
 /** Props a page receives. */
 export type PageProps<
-  TParams: { +[string]: string | $ReadOnlyArray<string> } = {},
+  TParams extends { readonly [string]: string | $ReadOnlyArray<string> } = {},
   TData = void,
 > = {|
-  +params: TParams,
-  +searchParams: { +[string]: string },
-  +data: TData,
+  readonly params: TParams,
+  readonly searchParams: { readonly [string]: string },
+  readonly data: TData,
 |};
 
 /** Props a layout receives. */
-export type LayoutProps<TParams: { +[string]: string | $ReadOnlyArray<string> } = {}> = {|
-  +params: TParams,
-  +children: React$Node,
+export type LayoutProps<
+  TParams extends { readonly [string]: string | $ReadOnlyArray<string> } = {},
+> = {|
+  readonly params: TParams,
+  readonly children: React$Node,
 |};

package/internal/document.js

@@ -0,0 +1,24 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the two ids the server writes and the
+// client reads.
+//
+// Their own module because both halves need them and neither should import the
+// other. The client used to take them from `./server.js`, which meant a client
+// bundle reached the request dispatcher — and through it `node:async_hooks`,
+// by way of `@uniflowed/server`. Nothing was *called*, so a bundler dropped the
+// code, but the import of a Node builtin survived into a browser bundle and
+// Vite said so on every build.
+//
+// Two string constants are not worth a boundary violation.
+
+/**
+ * The element the client hydrates when the app does not render `<html>`.
+ *
+ * An app whose root layout renders the whole document owns it and hydrates
+ * `document` instead; this is the wrapper for the ones that render content.
+ */
+export const ROOT_ID = "uf-root";
+
+/** The script element the server's resolved route data is written into. */
+export const DATA_ID = "__uf_data";

package/internal/runtime.js

@@ -22,101 +22,150 @@ 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,
   ...
 };
 
 /** 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,
+  readonly openGraph?: {
+    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,
+  readonly page: () => Promise<PageModule>,
+  readonly layouts: $ReadOnlyArray<() => Promise<LayoutModule>>,
 |};
 
 /** The not-found page, when the app declares one. */
 export type NotFoundRecord = {|
-  +mdx: boolean,
-  +file: string,
-  +page: () => Promise<PageModule>,
-  +layouts: $ReadOnlyArray<() => Promise<LayoutModule>>,
+  readonly mdx: boolean,
+  readonly file: string,
+  readonly page: () => Promise<PageModule>,
+  readonly layouts: $ReadOnlyArray<() => Promise<LayoutModule>>,
 |};
 
 /** A route table plus the not-found page. */
 export type RouteTable = {|
-  +routes: $ReadOnlyArray<RouteRecord>,
-  +notFound: ?NotFoundRecord,
+  readonly routes: $ReadOnlyArray<RouteRecord>,
+  readonly notFound: ?NotFoundRecord,
 |};
 
 /** 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. */
 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 | 404,
 |};
 
 /** Thrown by `notFound()`; the renderer answers with the not-found page. */
@@ -145,9 +194,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 +220,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;
       }
@@ -239,7 +290,7 @@ export function matchRoute(routes: $ReadOnlyArray<RouteRecord>, pathname: string
 }
 
 /** 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("?");
@@ -295,7 +346,7 @@ function loadOnce<T>(load: () => Promise<T>): Promise<T> {
 export async function resolveMatch(
   table: RouteTable,
   url: string,
-  options?: {| +data?: mixed, +skipLoader?: boolean |},
+  options?: {| readonly data?: mixed, readonly skipLoader?: boolean |},
 ): Promise<ResolvedRoute> {
   const { pathname, search } = splitUrl(url);
   const searchParams = parseSearch(search);
@@ -322,7 +373,11 @@ export async function resolveMatch(
     }
   }
 
-  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,
@@ -362,7 +417,11 @@ async function resolveNotFound(
     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,
@@ -390,7 +449,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 };
@@ -416,32 +479,32 @@ component DefaultNotFound() {
 // ---------------------------------------------------------------------------
 
 /** 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,15 +520,17 @@ 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";
@@ -547,13 +612,19 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
         if (matched == null) {
           return;
         }
-        await Promise.all([loadOnce(matched.route.page), ...matched.route.layouts.map((layout) => loadOnce(layout))]);
+        await Promise.all([
+          loadOnce(matched.route.page),
+          ...matched.route.layouts.map((layout) => loadOnce(layout)),
+        ]);
       },
       refresh: async () => {
         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);
         });
@@ -572,14 +643,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,10 +678,28 @@ 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;
 }
 
 /**
@@ -634,21 +728,47 @@ 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 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 component;
+  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.
+ */
+function renderable<TProps extends { ... }>(
+  component: RouteComponent,
+): React.ComponentType<TProps> {
+  return component as any;
 }
 
 component Head(metadata: Metadata) {
@@ -658,7 +778,9 @@ component Head(metadata: Metadata) {
       {title != null ? <title>{title}</title> : null}
       {description != null ? <meta name="description" content={description} /> : 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} />)
         : null}
@@ -683,7 +805,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.1",
+  "version": "0.0.0-alpha.5",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -14,16 +14,21 @@
     ".": "./index.js",
     "./client": "./client.js",
     "./server": "./server.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./handler": "./handler.js"
   },
   "files": [
-    "index.js",
     "client.js",
-    "server.js",
-    "internal"
+    "handler.js",
+    "index.js",
+    "internal",
+    "server.js"
   ],
   "peerDependencies": {
     "react": ">=19",
     "react-dom": ">=19"
+  },
+  "dependencies": {
+    "@uniflowed/server": "0.0.0-alpha.5"
   }
 }

package/server.js

@@ -7,6 +7,7 @@
 // `uf build` renders every static route through it once. Both produce the
 // same markup from the same code, which is the point.
 
+import { DATA_ID, ROOT_ID } from "./internal/document.js";
 import * as React from "react";
 import { renderToString } from "react-dom/server";
 
@@ -21,31 +22,30 @@ import {
 
 /** Asset URLs to reference from the document. */
 export type RenderAssets = {|
-  +scripts: $ReadOnlyArray<string>,
-  +styles: $ReadOnlyArray<string>,
-  +preloads: $ReadOnlyArray<string>,
+  readonly scripts: $ReadOnlyArray<string>,
+  readonly styles: $ReadOnlyArray<string>,
+  readonly preloads: $ReadOnlyArray<string>,
 |};
 
 /** A rendered document. */
 export type RenderResult = {|
-  +status: number,
-  +html: string,
-  +headers?: { +[string]: string },
+  readonly status: number,
+  readonly html: string,
+  readonly headers?: { readonly [string]: string },
 |};
 
-/** The id of the element the client hydrates when the app does not render `<html>`. */
-export const ROOT_ID = "uf-root";
-
-/** The id of the script carrying the loader data to the client. */
-export const DATA_ID = "__uf_data";
-
 /**
  * Build a `render(url, assets)` for one app.
  */
+export { DATA_ID, ROOT_ID } from "./internal/document.js";
+
+export type { Handler, HandlerContext, HandlerModule, HandlerRecord } from "./handler.js";
+export { createDispatcher } from "./handler.js";
+
 export function createRenderer(options: {|
-  +App: React.ComponentType<AppProps>,
-  +routes: RouteTable["routes"],
-  +notFound: RouteTable["notFound"],
+  readonly App: React.ComponentType<AppProps>,
+  readonly routes: RouteTable["routes"],
+  readonly notFound: RouteTable["notFound"],
 |}): (url: string, assets: RenderAssets) => Promise<RenderResult> {
   const table: RouteTable = { routes: options.routes, notFound: options.notFound };
   installRoutes(table);
@@ -93,7 +93,8 @@ function assemble(markup: string, resolved: ResolvedRoute, assets: RenderAssets)
       : markup.replace(/<html([^>]*)>/i, `<html$1><head>${head}</head>`);
     return `<!doctype html>\n${document}\n`;
   }
-  const title = resolved.metadata.title != null ? `<title>${escapeText(resolved.metadata.title)}</title>` : "";
+  const title =
+    resolved.metadata.title != null ? `<title>${escapeText(resolved.metadata.title)}</title>` : "";
   return `<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${title}${head}</head><body><div id="${ROOT_ID}">${markup}</div></body></html>\n`;
 }