@nifrajs/web 3.5.0 → 4.0.0

package/src/internal/web-app.ts

@@ -1,16 +1,24 @@
 import {
+  type BackendEvidenceProvider,
   type BackendMount,
-  type BackendMountHandler,
+  type BackendWebSocketMountHandler,
+  NIFRA_BACKEND_EVIDENCE,
   NIFRA_BACKEND_MOUNT,
+  NIFRA_BACKEND_WS_MOUNT,
+  NIFRA_BACKEND_WS_RUNTIME,
+  preRouteMountPaths,
 } from "@nifrajs/core/mount"
-import type { Platform } from "@nifrajs/core/server"
+import type { MountableApp, MountOptions } from "@nifrajs/core/server"
 import { type ServerOptions, server } from "@nifrajs/core/server"
+import { type CspPolicy, cspNonceResolver, DOCUMENT_POLICY, isCspPolicy } from "../csp.ts"
 import type { CssLoadingMode } from "../css-contract.ts"
+import { CACHE_CHANNEL } from "../isr.ts"
 import { generateLlmsTxt } from "../llms-txt.ts"
 import type { Manifest } from "../manifest.ts"
 import type { RenderAdapter } from "../render-seam.ts"
+import { PRERENDERED_LIST_PATH } from "../router.ts"
+import { formatShadowedPages, shadowedPages } from "./mount-shadow.ts"
 import { createPageRequestExecutor, type NonceResolver } from "./page-execution.ts"
-import { urlPartsFor } from "./request-url.ts"
 
 export type { NonceResolver } from "./page-execution.ts"
 export interface CreateWebAppOptions<Env = unknown> {
@@ -28,6 +36,13 @@ export interface CreateWebAppOptions<Env = unknown> {
    * policy's allowed sources are app-specific.
    */
   readonly nonce?: NonceResolver<Env>
+  /**
+   * A hash-based Content-Security-Policy from `createCspPolicy`, instead of `nonce`. A document then
+   * carries a nonce only when it needs one (it `defer()`s a value, or `meta` names the nonce in
+   * `unsafeInlineScript`); every other page is nonce-free, gets the same CSP header on every request,
+   * and stays cacheable by `withISR` or a CDN. `meta` still receives a nonce to name.
+   */
+  readonly csp?: CspPolicy
   /**
    * Options for the underlying `server()` - `requestTimeoutMs`, `admission`, `gracefulSignals`, and
    * the rest of {@link ServerOptions}.
@@ -89,14 +104,26 @@ export interface CreateWebAppOptions<Env = unknown> {
    * mount interface from `@nifrajs/core/mount`; `createWebApp` also serves that backend over HTTP at
    * {@link apiPrefix} (default `/api`): a request whose pathname starts with the prefix is dispatched
    * before page routing with the same `env`/`waitUntil` platform context, and the backend's `Response`
-   * is returned untouched. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it. */
+   * is returned untouched. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it.
+   *
+   * **Request-scoped loader calls.** While a page renders, its loaders, actions and boundaries get a
+   * `ctx.api` bound to that request's platform identity: a backend handler reached through it sees the
+   * visitor's `c.clientIp` (derived under this app's `server.clientIp` trust declaration), `c.env` and
+   * `c.waitUntil`, so a per-caller rate limit or audit field keys on the real visitor. `c.clientIp` is
+   * the supported way to read the caller - identity travels in the platform, so rebuilding a `Request`
+   * does not lose it. Headers do NOT travel: the page request's `cookie` and `authorization` are never
+   * copied, so a loader call is anonymous unless the loader passes headers on the call itself. */
   readonly api?: unknown
   /** HTTP path prefix the {@link api} backend is auto-mounted at (default `"/api"`). A request whose
    * pathname is exactly the prefix or starts with `prefix + "/"` is dispatched to the backend before
    * page routing; the backend therefore defines its routes at the **full** path (`server().post("/api/
    * sync", …)`), matching the in-process `inProcessClient` call sites. Set to `""` to disable the
    * auto-mount entirely (the app serves pages only and `api` stays a loader-only `ctx.api`). Mounting
-   * is also a no-op when `api` does not expose the symbol mount. */
+   * is also a no-op when `api` does not expose the symbol mount.
+   *
+   * A page file under the prefix (`routes/api/report.tsx`) could never render - the backend answers
+   * first and its 404 is final - so `createWebApp` throws, naming the file. The same holds for every
+   * other pre-route mount. */
   readonly apiPrefix?: string
   /**
    * Strip {@link apiPrefix} from the pathname before dispatching to `api` (default `false`).
@@ -118,14 +145,16 @@ export interface CreateWebAppOptions<Env = unknown> {
    *
    * Tried longest-path-first and BEFORE the `api` mount, so a mount at `/api/auth` wins over a backend
    * at `/api` no matter which was declared first. `stripPrefix` is the per-mount form of {@link apiStrip}:
-   * leave it off to pass the full path through.
+   * leave it off to pass the full path through. `opaque` states why a mount whose routes nifra cannot
+   * read (better-auth's handler) is outside assurance; it is then listed as a known gap.
    */
   readonly mounts?: ReadonlyArray<{
     readonly path: string
-    readonly app: {
-      fetch(request: Request, platform?: Platform<Env>): Response | Promise<Response>
-    }
+    readonly app: MountableApp<Env>
     readonly stripPrefix?: boolean
+    readonly priority?: number
+    readonly fallbackOn?: 404
+    readonly opaque?: string
   }>
   /** Secret for **draft / preview mode** (see `enableDraft`). When set, a request carrying a valid
    * signed `__nifra_draft` cookie gets `ctx.draft === true` in loaders/actions (else always `false`).
@@ -152,14 +181,19 @@ export interface CreateWebAppOptions<Env = unknown> {
    */
   readonly cssLoading?: CssLoadingMode
   /** SSG: the prerendered-path set (e.g. `enumerateStaticRoutes(routes).paths` or the build's
-   * `prerendered.json`). Injected as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
-   * into a prerendered route fetches its static `_data.json` instead of hitting the worker. */
+   * `prerendered.json`). Handed over as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
+   * into a prerendered route fetches its static `_data.json` instead of hitting the worker. A set over
+   * 4 KB of JSON is served once from `/__nifra/prerendered.json?v=<version>`, cacheable for good, and
+   * pages hand over only that URL; `prerenderRoutes` writes the file into a static output. */
   readonly prerenderedPaths?: readonly string[]
   /** Publish the project's `AGENTS.md` inside `/llms.txt` and `/llms-full.txt`. **Off by default**:
    * those endpoints are public and unauthenticated, while `AGENTS.md` is a repo file written for the
    * team - unreleased feature names, internal hostnames, and "don't touch X yet" notes live there
    * routinely. Turn it on only for a repo whose guidelines you would publish as a page. */
   readonly publishLocalGuidelines?: boolean
+  /** Serve `/llms.txt` and `/llms-full.txt` (default `true`): the page routes, and the backend routes
+   * when the backend is mounted over HTTP at {@link apiPrefix}. `false` registers neither path. */
+  readonly llmsTxt?: boolean
   /** SSG: per dynamic route pattern, its `getStaticPaths` `fallback` (from `enumerateStaticRoutes` or
    * the build's `prerendered.json`). A route mapped to `"404"` rejects any path NOT in
    * `prerenderedPaths` with the 404 page - the unlisted path simply doesn't exist. `"ssr"` (the
@@ -184,14 +218,6 @@ export interface CreateWebAppOptions<Env = unknown> {
   ) => void
 }
 
-/** The handler context fields createWebApp uses - a structural subset of nifra's `Context`. */
-interface RouteContext<Env = unknown> {
-  readonly params: Record<string, string>
-  readonly req: Request
-  /** Platform bindings (Workers env), forwarded to each route's loader/action as `args.env`. */
-  readonly env: Env
-}
-
 /**
  * Re-issue `request` with `prefix` removed from its pathname.
  *
@@ -205,32 +231,47 @@ interface RouteContext<Env = unknown> {
  * The `Request` is rebuilt rather than mutated (`url` is read-only), preserving method, headers, body,
  * and duplex streaming - the body is passed through unread, so a large or streamed upload is untouched.
  */
-function stripMountPrefix(request: Request, prefix: string): Request {
-  const url = new URL(request.url)
-  const rest = url.pathname.slice(prefix.length)
-  url.pathname = rest === "" ? "/" : rest
-  // `url.href`, not the `URL`: this type set only declares the string and Request overloads.
-  return new Request(url.href, request)
-}
-
 /**
  * Resolve the explicit symbol-keyed backend mount interface. The symbol seam forwards platform
  * context without making web depend on client.
  */
-function backendMountOf<Env>(api: unknown): BackendMountHandler<Env> | undefined {
+function backendMountOf<Env>(api: unknown): MountableApp<Env> | undefined {
   if ((typeof api !== "object" && typeof api !== "function") || api === null) return undefined
   const explicit = (api as Partial<BackendMount<Env>>)[NIFRA_BACKEND_MOUNT]
   if (typeof explicit !== "function") return undefined
-  return (request, platform) => explicit.call(api, request, platform)
+  const websocket = (api as Partial<BackendMount<Env>>)[NIFRA_BACKEND_WS_MOUNT]
+  const runtime = (api as Partial<BackendMount<Env>>)[NIFRA_BACKEND_WS_RUNTIME]
+  const evidence = (api as Partial<BackendMount<Env>>)[NIFRA_BACKEND_EVIDENCE]
+  const mount: {
+    fetch: MountableApp<Env>["fetch"]
+    resolveWebSocketUpgrade?: BackendWebSocketMountHandler<Env>
+    [NIFRA_BACKEND_WS_RUNTIME]?: NonNullable<BackendMount<Env>[typeof NIFRA_BACKEND_WS_RUNTIME]>
+    [NIFRA_BACKEND_EVIDENCE]?: BackendEvidenceProvider
+  } = {
+    fetch: (request, platform) => explicit.call(api, request, platform),
+  }
+  if (typeof websocket === "function") {
+    mount.resolveWebSocketUpgrade = (request, platform) => websocket.call(api, request, platform)
+  }
+  if (typeof runtime === "function") mount[NIFRA_BACKEND_WS_RUNTIME] = runtime
+  if (typeof evidence === "function") mount[NIFRA_BACKEND_EVIDENCE] = evidence
+  return mount
 }
 
-function requestPathOf(request: Request): string {
-  try {
-    const parts = urlPartsFor(request)
-    return parts.pathname + parts.search
-  } catch {
-    return "/"
-  }
+function evidenceProviderOf(value: unknown): BackendEvidenceProvider | undefined {
+  if ((typeof value !== "object" && typeof value !== "function") || value === null) return undefined
+  const provider = (value as { [NIFRA_BACKEND_EVIDENCE]?: unknown })[NIFRA_BACKEND_EVIDENCE]
+  return typeof provider === "function" ? (provider as BackendEvidenceProvider) : undefined
+}
+
+function mountPathPrefix(path: string): string {
+  const withoutWildcard = path.endsWith("/*") ? path.slice(0, -2) : path
+  if (withoutWildcard === "" || withoutWildcard === "/") return ""
+  // Index-scan instead of `/\/+$/`: mount paths can be library input, and the
+  // unanchored-start trailing-run replacement can backtrack quadratically.
+  let end = withoutWildcard.length
+  while (end > 0 && withoutWildcard.charCodeAt(end - 1) === 47 /* '/' */) end--
+  return withoutWildcard.slice(0, end)
 }
 
 /**
@@ -251,6 +292,12 @@ export function createWebApp<Env = unknown>(
   options: CreateWebAppOptions<Env>,
 ): ReturnType<typeof server<Env>> {
   const { adapter, manifest, clientEntry, title, api } = options
+  if (options.csp !== undefined && options.nonce !== undefined) {
+    throw new TypeError("[nifra/web] createWebApp takes `csp` or `nonce`, not both")
+  }
+  if (options.csp !== undefined && !isCspPolicy(options.csp)) {
+    throw new TypeError("[nifra/web] createWebApp `csp` must come from createCspPolicy()")
+  }
   // Seed the context with the declared `Env` so `app.fetch(req, { env })` / `toFetchHandler(app)` type
   // the platform bindings (see the `createWebApp` doc). The runtime `env` still arrives per-request via
   // `app.fetch(req, { env })`; this is a compile-time-only seed (`server<Env>()` casts, doesn't store).
@@ -259,43 +306,60 @@ export function createWebApp<Env = unknown>(
   // `beforeHandle`, assurance evidence) actually bind to them - see the `use` option. A caller
   // cannot do this after the fact: by the time this function returns, the routes are declared.
   options.use?.(app)
+  // A resolver created by `createNonceResolver({ header })` carries a paired response hook. Register it
+  // after caller middleware so its request-specific CSP value is the last default applied to a page.
+  const nonceResponse = options.nonce?.onResponse
+  if (nonceResponse !== undefined) app.onResponse(nonceResponse)
+  // How this app's documents meet a CSP, for wrappers that cache them (`withISR` warns on "nonce").
+  const documentPolicy =
+    options.csp !== undefined ? "hash" : options.nonce !== undefined ? "nonce" : undefined
+  if (documentPolicy !== undefined) {
+    Object.defineProperty(app, DOCUMENT_POLICY, { value: documentPolicy })
+  }
+  const cacheChannel = { enabled: false }
+  Object.defineProperty(app, CACHE_CHANNEL, {
+    value: () => {
+      cacheChannel.enabled = true
+    },
+  })
   // Auto-mount the in-process backend over HTTP at `apiPrefix` (default `/api`), BEFORE page routing.
-  // `onRequest` runs on the raw request ahead of the router, so this wins over the page wildcard `/*`
-  // for every method (POST/GET/PUT/…) - not just the GET page routes - and a backend 404 (`/api/none`)
-  // surfaces as the backend's own response, never the page 404. We dispatch the SAME `Request` object
-  // (its body unread) so streamed/large bodies pass through untouched; the backend defines its routes
-  // at the full prefixed path (`server().post("/api/sync", …)`), matching the `inProcessClient` call
-  // sites. `apiPrefix: ""` opts out; a non-mountable `api` (no symbol mount) is left pages-only. The hook
-  // is registered ONLY when both hold, so a pages-only app keeps core's synchronous no-hook fast path.
+  // Core's pre-route mount seam runs before the page wildcard `/*`; parent request hooks run first,
+  // child request hooks run inside the mount, and parent response hooks still wrap the result.
+  // The mount handles every HTTP method and preserves backend 404 responses instead of letting the
+  // page catch-all render them. We dispatch the same `Request` object (its body unread), so
+  // streamed/large bodies pass through untouched. The backend defines full prefixed paths
+  // (`server().post("/api/sync", …)`) unless `apiStrip` is enabled. `apiPrefix: ""` opts out;
+  // a non-mountable `api` remains loader-only and pages-only apps keep the no-mount fast path.
   const apiPrefix = options.apiPrefix ?? "/api"
   const apiStrip = options.apiStrip === true
   const mountedApi = backendMountOf<Env>(api)
   // Longest path first, so a more specific mount (`/api/auth`) is tried before a broader one (`/api`)
   // regardless of the order they were declared in.
-  const mounts = [...(options.mounts ?? [])].sort((a, b) => b.path.length - a.path.length)
-  const underPrefix = (pathname: string, prefix: string): boolean =>
-    pathname === prefix || pathname.startsWith(`${prefix}/`)
-
-  if (mounts.length > 0 || (apiPrefix !== "" && mountedApi !== undefined)) {
-    app.onRequest((req, platform) => {
-      const { pathname } = urlPartsFor(req)
-      // Sub-app mounts win over the backend prefix: they are the more specific declaration, and an
-      // auth handler mounted at `/api/auth` must not be swallowed by the backend mounted at `/api`.
-      for (const mount of mounts) {
-        if (!underPrefix(pathname, mount.path)) continue
-        return mount.app.fetch(
-          mount.stripPrefix === true ? stripMountPrefix(req, mount.path) : req,
-          platform,
-        )
-      }
-      // Exactly the prefix (`/api`) or a sub-path (`/api/…`) - NOT a sibling like `/apixyz` that merely
-      // shares the prefix as a string head. Dispatch the original `req` (body intact) to the backend.
-      if (mountedApi !== undefined && apiPrefix !== "" && underPrefix(pathname, apiPrefix)) {
-        return mountedApi(apiStrip ? stripMountPrefix(req, apiPrefix) : req, platform)
-      }
-      return undefined // not an API path → continue to page routing
-    })
+  const configuredMounts: readonly MountOptions<Env>[] = Object.freeze(
+    (options.mounts ?? []).map(
+      (mount): MountOptions<Env> => ({
+        path: mount.path,
+        app: mount.app,
+        ...(mount.stripPrefix === undefined ? {} : { stripPrefix: mount.stripPrefix }),
+        ...(mount.priority === undefined ? {} : { priority: mount.priority }),
+        ...(mount.fallbackOn === undefined ? {} : { fallbackOn: mount.fallbackOn }),
+        ...(mount.opaque === undefined ? {} : { opaque: mount.opaque }),
+      }),
+    ),
+  )
+  const mounts: Array<MountOptions<Env>> = [...configuredMounts]
+  if (mountedApi !== undefined && apiPrefix !== "") {
+    mounts.push({ path: apiPrefix, app: mountedApi, stripPrefix: apiStrip })
   }
+  for (const mount of mounts) app.mount(mount)
+  // Read back the server's own mount table, so a mount added in `use` counts as well: a page under any
+  // pre-route mount is unreachable, and serving it as a silent 404 hides that.
+  const shadowed = shadowedPages(manifest, preRouteMountPaths(app))
+  if (shadowed.length > 0) throw new Error(`[nifra/web] ${formatShadowedPages(shadowed)}`)
+  const ownPatterns = new Set(manifest.routes.map((route) => route.pattern))
+  const prerenderedList = ownPatterns.has(PRERENDERED_LIST_PATH)
+    ? undefined
+    : servedPrerenderedList(options.prerenderedPaths)
   const pageExecutor = createPageRequestExecutor<Env>({
     adapter,
     manifest,
@@ -310,38 +374,152 @@ export function createWebApp<Env = unknown>(
     ...(options.prerenderedPaths === undefined
       ? {}
       : { prerenderedPaths: options.prerenderedPaths }),
+    ...(prerenderedList === undefined ? {} : { prerenderedListUrl: prerenderedList.url }),
     ...(options.staticFallbacks === undefined ? {} : { staticFallbacks: options.staticFallbacks }),
     ...(options.staticBoundaryCache === undefined
       ? {}
       : { staticBoundaryCache: options.staticBoundaryCache }),
     ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
+    ...(options.csp === undefined
+      ? {}
+      : { nonce: cspNonceResolver(options.csp) as NonceResolver<Env>, csp: options.csp }),
     ...(options.onLoaderError === undefined ? {} : { onLoaderError: options.onLoaderError }),
+    cacheChannel,
   })
 
   for (const route of manifest.routes) {
     app.register("GET", route.pattern, undefined, pageExecutor.get(route))
     app.register("POST", route.pattern, undefined, pageExecutor.post(route))
   }
-  // Register llms.txt & llms-full.txt
-  const llmsOptions = { includeLocalGuidelines: options.publishLocalGuidelines === true }
-  app.register("GET", "/llms.txt", undefined, async () => {
-    const text = await generateLlmsTxt(false, manifest.routes, api, llmsOptions)
-    return new Response(text, {
-      headers: { "content-type": "text/plain; charset=utf-8" },
-    })
-  })
+  // llms.txt & llms-full.txt describe what a visitor can reach: the pages, and the backend only when it
+  // is served over HTTP - a backend the loaders call in-process has no public surface to describe. An
+  // app route at either path takes precedence, and each text is built once per app.
+  if (options.llmsTxt !== false) {
+    const llmsOptions = { includeLocalGuidelines: options.publishLocalGuidelines === true }
+    const publicApi = mountedApi !== undefined && apiPrefix !== "" ? api : undefined
+    for (const [path, full] of [
+      ["/llms.txt", false],
+      ["/llms-full.txt", true],
+    ] as const) {
+      if (ownPatterns.has(path)) continue
+      let text: Promise<string> | undefined
+      app.register("GET", path, undefined, async () => {
+        text ??= generateLlmsTxt(full, manifest.routes, publicApi, llmsOptions).catch((error) => {
+          text = undefined
+          throw error
+        })
+        return new Response(await text, {
+          headers: { "content-type": "text/plain; charset=utf-8" },
+        })
+      })
+    }
+  }
 
-  app.register("GET", "/llms-full.txt", undefined, async () => {
-    const text = await generateLlmsTxt(true, manifest.routes, api, llmsOptions)
-    return new Response(text, {
-      headers: { "content-type": "text/plain; charset=utf-8" },
-    })
-  })
+  if (prerenderedList !== undefined) {
+    const { body, version } = prerenderedList
+    app.register(
+      "GET",
+      PRERENDERED_LIST_PATH,
+      undefined,
+      (c: { readonly req: Request }) =>
+        new Response(body, {
+          headers: {
+            "content-type": "application/json",
+            // Only the versioned URL pages hand over is immutable; a bare request gets today's list.
+            "cache-control":
+              new URL(c.req.url).searchParams.get("v") === version
+                ? "public, max-age=31536000, immutable"
+                : "no-cache",
+          },
+        }),
+    )
+  }
 
-  // Wildcard catch-all: unmatched paths render `_404` (404), or a plain text 404 if absent.
-  app.register("GET", "/*", undefined, (c: RouteContext<Env>) =>
-    pageExecutor.notFound(c.req, c.env, requestPathOf(c.req)),
-  )
+  // Wildcard catch-all: unmatched paths render the nearest `_404` (404), or a plain text 404 if
+  // absent.
+  app.register("GET", "/*", undefined, pageExecutor.fallback)
+
+  let evidenceComposing = false
+  const evidenceProvider: BackendEvidenceProvider = async () => {
+    if (evidenceComposing) {
+      throw new Error("[nifra/web] cyclic composed assurance evidence mount")
+    }
+    evidenceComposing = true
+    try {
+      const { composeProjectEvidence, snapshotProjectEvidence } = await import(
+        "@nifrajs/core/evidence"
+      )
+      const parts: Array<{
+        readonly evidence: import("@nifrajs/core/evidence").ProjectEvidenceSnapshot
+        readonly pathPrefix?: string
+      }> = [{ evidence: snapshotProjectEvidence(app) }]
+      for (const mount of configuredMounts) {
+        const provider = evidenceProviderOf(mount.app)
+        if (provider === undefined) {
+          // A declared opaque mount reaches the snapshot as a known gap, through this app's own
+          // mount reflection above.
+          if (mount.opaque !== undefined) continue
+          throw new Error(
+            `[nifra/web] cannot compose assurance evidence: mount "${mount.path}" has no token-only evidence provider - declare why it is not analyzed with { opaque: "<reason>" }`,
+          )
+        }
+        parts.push({
+          evidence: await provider.call(mount.app),
+          ...(mount.stripPrefix === true ? { pathPrefix: mountPathPrefix(mount.path) } : {}),
+        })
+      }
+      if (mountedApi !== undefined && apiPrefix !== "") {
+        const provider = evidenceProviderOf(api)
+        if (provider === undefined) {
+          throw new Error(
+            `[nifra/web] cannot compose assurance evidence: auto-mounted API at "${apiPrefix}" has no token-only evidence provider`,
+          )
+        }
+        parts.push({
+          evidence: await provider.call(api),
+          ...(apiStrip ? { pathPrefix: mountPathPrefix(apiPrefix) } : {}),
+        })
+      }
+      return composeProjectEvidence(parts)
+    } finally {
+      evidenceComposing = false
+    }
+  }
+  Object.defineProperty(app, NIFRA_BACKEND_EVIDENCE, {
+    configurable: false,
+    enumerable: false,
+    value: evidenceProvider,
+    writable: false,
+  })
 
   return app
 }
+
+/** Resolve one composed, token-only evidence snapshot for a web app and its mounted surfaces. */
+export async function webProjectEvidence(
+  source: unknown,
+): Promise<import("@nifrajs/core/evidence").ProjectEvidenceSnapshot> {
+  const provider = evidenceProviderOf(source)
+  if (provider === undefined) {
+    throw new TypeError("webProjectEvidence(): expected an app created by createWebApp")
+  }
+  return provider.call(source)
+}
+
+// Up to this many characters of JSON, the prerendered set rides inline in each page's handover.
+const INLINE_PRERENDERED_CHARS = 4096
+
+/** The prerendered set as a served, content-versioned list, when it is too large to inline. */
+function servedPrerenderedList(
+  paths: readonly string[] | undefined,
+): { readonly body: string; readonly version: string; readonly url: string } | undefined {
+  if (paths === undefined || paths.length === 0) return undefined
+  const body = JSON.stringify(paths)
+  if (body.length <= INLINE_PRERENDERED_CHARS) return undefined
+  // FNV-1a: a version that changes with the list is all the URL needs; a stale cached list only
+  // costs a fallback to the dynamic data request.
+  let hash = 0x811c9dc5
+  for (let i = 0; i < body.length; i++) hash = Math.imul(hash ^ body.charCodeAt(i), 0x01000193)
+  const version = (hash >>> 0).toString(16).padStart(8, "0")
+  return { body, version, url: `${PRERENDERED_LIST_PATH}?v=${version}` }
+}