@uniflowed/router 0.0.0-alpha.7 → 0.0.0-alpha.9

package/client.js

@@ -6,16 +6,37 @@
 // The current route's chunks are loaded and its embedded loader data read
 // *before* `hydrateRoot`, so the first client render is synchronous and
 // matches the server's markup exactly.
+//
+// # A route can decline to be hydrated
+//
+// uf's server-component analysis decides which routes have a `"use client"`
+// boundary anywhere in them, and `@uniflowed/vite` leaves the page out of the
+// client route table for the ones that have none. Such a route has nothing in
+// the browser to attach: the document the server wrote is the whole of it. So
+// this returns without calling `hydrateRoot`, and the `<a>` elements a `Link`
+// rendered stay what the server made them — real links the browser follows.
+// See ubugeeei-prod/uf#350.
 
 import * as React from "react";
 import { startTransition } from "react";
 import { hydrateRoot } from "react-dom/client";
 
-import { type AppProps, type RouteTable, installRoutes, resolveMatch } from "./internal/runtime.js";
+import {
+  type AppProps,
+  type RouteTable,
+  hasClientPage,
+  installRoutes,
+  matchRoute,
+  resolveMatch,
+} from "./internal/runtime.js";
 import { DATA_ID, ROOT_ID } from "./internal/document.js";
 
 /**
  * Hydrate the current document.
+ *
+ * Resolves without mounting anything when the current route ships no client
+ * page — see the header. The promise settling is not a claim that React is on
+ * the document.
  */
 export async function hydrate(options: {|
   readonly App: React.ComponentType<AppProps>,
@@ -30,6 +51,13 @@ export async function hydrate(options: {|
   };
   installRoutes(table);
 
+  // Before the loader data is read and before `resolveMatch` is called: both
+  // would go looking for a page module that is not in this bundle.
+  const matched = matchRoute(table.routes, window.location.pathname);
+  if (matched != null && !hasClientPage(matched.route)) {
+    return;
+  }
+
   const url = window.location.pathname + window.location.search;
   const embedded = document.getElementById(DATA_ID);
   const data = embedded != null ? JSON.parse(embedded.textContent ?? "null") : undefined;

package/handler.js

@@ -25,8 +25,16 @@
 // 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";
+//
+// It also does not establish the request a handler is inside. The host does,
+// around the whole of it, so a handler and the guard above it share one
+// context; see the same section in `./middleware.js`. This module used to
+// build its own and drain it the moment the handler returned, which the
+// comment there called "the response is in hand" — true, and not what
+// `after()` promises. A handler that streams its body has not sent a byte at
+// that point. See ubugeeei-prod/uf#389.
+
+import { requireRequest } from "./internal/request.js";
 import type { RouteParams } from "./internal/runtime.js";
 
 /** What a handler is given besides the request. */
@@ -76,6 +84,9 @@ export function createDispatcher(options: {|
   const table = [...options.handlers].sort((a, b) => specificity(b.path) - specificity(a.path));
 
   return async function dispatch(request: Request): Promise<Response | null> {
+    // The host's half of the contract, checked rather than assumed; see
+    // `./internal/request.js`.
+    requireRequest("dispatch");
     const url = new URL(request.url);
     for (const record of table) {
       const params = matchPath(record.path, url.pathname);
@@ -90,17 +101,13 @@ export function createDispatcher(options: {|
         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);
+      // In the host's request, so a handler that calls `headers()`,
+      // `cookies()` or `after()` answers about the same one its guard did, and
+      // what it defers is drained once, by the host, after the bytes are out.
+      const response = await handler(request, {
+        params,
+        searchParams: url.searchParams,
+      });
 
       // 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

package/index.js

@@ -11,6 +11,8 @@
 // path that matched nothing, and what renders in place of a subtree that threw.
 // Both are segment files, resolved by the nearest one above the path.
 
+import * as React from "react";
+
 import type { RouteError } from "./internal/runtime.js";
 
 export type {
@@ -46,6 +48,7 @@ export {
   RouterProvider,
   UnauthorizedError,
   forbidden,
+  hasClientPage,
   matchRoute,
   notFound,
   parseSearch,
@@ -84,5 +87,5 @@ export type LayoutProps<
   TParams extends { readonly [string]: string | $ReadOnlyArray<string> } = {},
 > = {|
   readonly params: TParams,
-  readonly children: React$Node,
+  readonly children: React.Node,
 |};

package/internal/request.js

@@ -0,0 +1,43 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the request the server half runs inside.
+//
+// One function, and it exists because two modules need the same refusal.
+// `createMiddlewareRunner` and `createDispatcher` both used to build a request
+// context of their own — `contextFor`, then `runWithContext`, then
+// `drainDeferred` — which gave one request up to two contexts and ran what
+// `after()` deferred before the response was written, and in the middleware's
+// case before there was a response at all. See ubugeeei-prod/uf#389.
+//
+// Both now run inside whatever request the host established, which means both
+// depend on the host having established one. That dependency is checked rather
+// than assumed, for the reason `createApplicationHandler` gives about
+// `entry.runMiddleware` itself: a missing half of the contract should be a
+// failure on the first request, not an application that answers strangely.
+//
+// Server-only, like the two modules that import it. Nothing the browser loads
+// reaches this.
+
+import { insideRequest } from "@uniflowed/server/host";
+
+/**
+ * Refuse to run outside a request, naming what has to establish one.
+ *
+ * The message is addressed to whoever wired the host, because that is who can
+ * fix it. Left to fail on its own, a mis-wired host would surface as the first
+ * `cookies()` in somebody's guard throwing "called outside a request … a
+ * static prerender, a module's top level, or a client component" — three
+ * places to look, none of them this one — and an application that calls no
+ * server function at all would sail past that and lose every `after()` instead.
+ */
+export function requireRequest(entry: string): void {
+  if (insideRequest()) {
+    return;
+  }
+  throw new Error(
+    `@uniflowed/router: ${entry}() was called outside a request. A host owns the request: ` +
+      "begin it with `beginRequest` from `@uniflowed/server/host` (a bundled application " +
+      "re-exports it from `virtual:uf/server`), run the whole request inside `run`, and call " +
+      "`settle` once the response has been sent. See ubugeeei-prod/uf#389.",
+  );
+}

package/internal/runtime.js

@@ -11,6 +11,7 @@
 
 import * as React from "react";
 import {
+  Suspense,
   createContext,
   startTransition,
   useCallback,
@@ -115,6 +116,21 @@ export type ErrorModule = {
   ...
 };
 
+/**
+ * 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,
@@ -146,8 +162,46 @@ 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>,
+|};
+
+/**
+ * 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>,
 |};
 
 /**
@@ -264,6 +318,16 @@ export type ResolvedRoute = {|
     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. */
@@ -381,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.
  */
@@ -552,17 +628,44 @@ async function resolveRoute(
     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") {
+    // 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 });
   }
 
@@ -584,9 +687,46 @@ async function resolveRoute(
     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.
  *
@@ -722,6 +862,10 @@ async function resolveError(
     // 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: [],
   };
 }
 
@@ -758,6 +902,7 @@ async function resolveNotFound(
       status: 404,
       error: null,
       errorBoundary: await resolveErrorBoundary(table, pathname, 0),
+      loading: [],
     };
   }
   const [page, ...layouts] = await Promise.all([
@@ -783,6 +928,10 @@ async function resolveNotFound(
     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: [],
   };
 }
 
@@ -1034,7 +1183,23 @@ export type AppProps = {|
   readonly initial: ResolvedRoute,
 |};
 
-const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+/**
+ * Whether there is a document to navigate.
+ *
+ * Asked every time rather than answered once at module scope, and the
+ * difference is not a style preference. The answer is a constant inside a
+ * browser bundle and inside a server process; it is *not* a constant inside a
+ * test runner, where a DOM is installed on the first render and one worker
+ * serves many files out of one module registry. Latched, the first file in a
+ * worker to import this module decided for every file after it whether a
+ * `Link` navigates or silently does nothing — and a server-rendering test
+ * imports it before any document exists. See ubugeeei-prod/uf#445.
+ *
+ * The cost is a `typeof` per navigation, which is a navigation.
+ */
+function isBrowser(): boolean {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
 
 /**
  * Provides the current route to the tree and performs navigation.
@@ -1049,11 +1214,23 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
   const [pending, setPending] = useState<boolean>(false);
 
   const navigate = useCallback(async (to: string, options?: NavigateOptions): Promise<void> => {
-    if (!isBrowser) {
+    if (!isBrowser()) {
       return;
     }
     const target = new URL(to, window.location.href);
     const next = target.pathname + target.search;
+    // The half of the split that is not about bytes. A route whose page is not
+    // in this bundle is not a route this router can render, and pretending
+    // otherwise is the silent break: the navigation would resolve to nothing
+    // and the visitor would be left on the page they clicked from. The browser
+    // has the document, so the browser does the navigation — which is what a
+    // link does when there is no JavaScript at all, and what the anchor
+    // `Link` renders would have done on its own.
+    const matched = matchRoute(routeTable().routes, target.pathname);
+    if (matched != null && !hasClientPage(matched.route)) {
+      window.location.assign(target.href);
+      return;
+    }
     setPending(true);
     try {
       const nextResolved = await resolveMatch(routeTable(), next);
@@ -1083,11 +1260,19 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
   }, []);
 
   useEffect(() => {
-    if (!isBrowser) {
+    if (!isBrowser()) {
       return undefined;
     }
     const onPopState = () => {
       const next = window.location.pathname + window.location.search;
+      // Back into a route this bundle has no page for. The history entry is
+      // already the browser's — it moved before this listener ran — so the
+      // document that belongs to it is what has to be fetched.
+      const matched = matchRoute(routeTable().routes, window.location.pathname);
+      if (matched != null && !hasClientPage(matched.route)) {
+        window.location.reload();
+        return;
+      }
       resolveMatch(routeTable(), next).then((nextResolved) => {
         startTransition(() => {
           setResolved(nextResolved);
@@ -1105,21 +1290,22 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
       push: (to, options) => navigate(to, options),
       replace: (to) => navigate(to, { replace: true }),
       prefetch: async (to) => {
-        if (!isBrowser) {
+        if (!isBrowser()) {
           return;
         }
         const target = new URL(to, window.location.href);
         const matched = matchRoute(routeTable().routes, target.pathname);
-        if (matched == null) {
+        const load = matched?.route.page;
+        if (matched == null || load == null) {
           return;
         }
         await Promise.all([
-          loadOnce(matched.route.page),
+          loadOnce(load),
           ...matched.route.layouts.map((layout) => loadOnce(layout)),
         ]);
       },
       refresh: async () => {
-        if (!isBrowser) {
+        if (!isBrowser()) {
           return;
         }
         const nextResolved = await resolveMatch(
@@ -1131,12 +1317,12 @@ export component RouterProvider(url: string, initial: ResolvedRoute, children: R
         });
       },
       back: () => {
-        if (isBrowser) {
+        if (isBrowser()) {
           window.history.back();
         }
       },
       forward: () => {
-        if (isBrowser) {
+        if (isBrowser()) {
           window.history.forward();
         }
       },
@@ -1207,6 +1393,15 @@ 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
@@ -1217,6 +1412,22 @@ export hook useLoaderData(): mixed {
  * 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();
@@ -1225,23 +1436,34 @@ export component RouteView() {
   let element: React.Node = (
     <Page params={resolved.params} searchParams={resolved.searchParams} data={resolved.data} />
   );
-  for (let index = resolved.layouts.length - 1; index >= above; index -= 1) {
-    const Layout = layoutComponent(resolved.layouts[index]);
-    element = <Layout params={resolved.params}>{element}</Layout>;
-  }
-  // 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 (module != null && resolved.error == null) {
-    element = (
-      <RouteErrorBoundary module={module} resetKey={resolved.pathname}>
-        {element}
-      </RouteErrorBoundary>
-    );
-  }
-  for (let index = above - 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 (
     <>
@@ -1267,6 +1489,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;
@@ -1292,11 +1532,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;
 }