@nifrajs/web 5.2.0 → 5.4.0

package/src/internal/module-preparation.ts

@@ -0,0 +1,30 @@
+interface ModuleEntry<T extends object> {
+  readonly load: () => Promise<T>
+}
+
+/** Production imports are immutable; failed imports remain retryable. No loader data is cached. */
+export function prepareModules(
+  enabled: boolean,
+): <T extends object>(entry: ModuleEntry<T>) => T | Promise<T> {
+  const modules = new WeakMap<object, object | Promise<object>>()
+  return <T extends object>(entry: ModuleEntry<T>): T | Promise<T> => {
+    if (!enabled) return entry.load()
+    const known = modules.get(entry)
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Only this entry.load populates its slot, so the cached value retains that entry's module type.
+    if (known !== undefined) return known as T | Promise<T>
+    const pending = Promise.resolve()
+      .then(() => entry.load())
+      .then(
+        (module) => {
+          modules.set(entry, module)
+          return module
+        },
+        (error) => {
+          modules.delete(entry)
+          throw error
+        },
+      )
+    modules.set(entry, pending)
+    return pending
+  }
+}

package/src/internal/node-adapter.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+/** A package as installed: its directory and the version its package.json declares. */
+export interface InstalledPackage {
+  readonly dir: string
+  readonly version: string
+}
+
+/** The `version` a package.json declares, or `undefined` when it declares none. */
+function manifestVersion(path: string | URL): string | undefined {
+  const manifest: unknown = JSON.parse(readFileSync(path, "utf8"))
+  return typeof manifest === "object" &&
+    manifest !== null &&
+    "version" in manifest &&
+    typeof manifest.version === "string"
+    ? manifest.version
+    : undefined
+}
+
+/**
+ * The copy of `name` a module in `fromDir` imports: the first `node_modules/<name>` walking up, as
+ * both bundlers resolve a bare specifier. Walked rather than `Bun.resolveSync`, which keeps its first
+ * answer for the life of the process.
+ */
+export function installedPackage(name: string, fromDir: string): InstalledPackage | undefined {
+  for (let dir = resolve(fromDir); ; dir = dirname(dir)) {
+    const manifest = join(dir, "node_modules", name, "package.json")
+    if (existsSync(manifest)) {
+      const version = manifestVersion(manifest)
+      return version === undefined ? undefined : { dir: dirname(manifest), version }
+    }
+    if (dirname(dir) === dir) return undefined
+  }
+}
+
+/**
+ * Why a `--target node` build whose server entry is generated in `workDir` must stop before
+ * bundling, or `undefined`. The entry is written for the `@nifrajs/node` of this package's release and
+ * the bundle inlines whichever copy is installed: a 5.3 adapter built cleanly, then threw at startup
+ * on the static mounts.
+ */
+export function nodeAdapterRefusal(
+  workDir: string,
+  // src/internal/ and dist/internal/ both sit two levels below the package root.
+  webVersion = manifestVersion(new URL("../../package.json", import.meta.url)),
+): string | undefined {
+  const adapter = installedPackage("@nifrajs/node", workDir)
+  if (adapter === undefined || webVersion === undefined) return undefined
+  if (Bun.semver.order(adapter.version, webVersion) >= 0) return undefined
+  return (
+    `[nifra/web] --target node would bundle @nifrajs/node ${adapter.version} (${adapter.dir}), older ` +
+    `than @nifrajs/web ${webVersion}. The server entry is generated for the adapter of the same ` +
+    "release, and an older one can fail when the server starts. Upgrade the nifra packages " +
+    `together: nifra upgrade ${webVersion}`
+  )
+}

package/src/internal/output-guard.ts

@@ -14,6 +14,7 @@
  * its own `validate` output, as zod and valibot objects do by default.
  */
 import type { StandardResult, StandardSchemaV1 } from "@nifrajs/core/server"
+import { markDeferredFree } from "./deferred-free.ts"
 import { wireDate } from "./wire-date.ts"
 
 // Registry symbols shared with core and `@nifrajs/schema`, so two copies of either still agree.
@@ -84,6 +85,8 @@ interface CompiledGuard {
   readonly validate: StandardSchemaV1["~standard"]["validate"]
   /** Dev only: name the keys the guard dropped, so a schema missing a field is not a silent blank. */
   readonly warnDropped: boolean
+  /** No value this guard passes can hold a `defer()` marker (see internal/deferred-free.ts). */
+  readonly deferredFree: boolean
 }
 
 interface Deferred {
@@ -200,7 +203,10 @@ function shapeOf(
 }
 
 class Compiler {
+  /** Some node may pass a `defer()` marker on: a deferred node, or one that lets any value through. */
+  mayPassMarker = false
   private readonly memo = new Map<Node, Project>()
+  private readonly issueFree = new WeakSet<Project>([LEAF, LEAF_ARRAY, DATE])
   private readonly ids = new Map<string, Node>()
   readonly sensitive: string[] = []
 
@@ -263,25 +269,33 @@ class Compiler {
       case "array":
         return this.array(node, where)
       case "leaf":
+        // `not` (or an object `const`) without a `type` can accept an object.
+        if (node.type === undefined) this.mayPassMarker = true
         return LEAF
       default:
-        return UNKNOWN
+        return this.unknown()
     }
   }
 
+  private unknown(): Project {
+    this.mayPassMarker = true
+    return UNKNOWN
+  }
+
   private extra(schema: unknown, where: string): Project | undefined {
-    if (schema === true || (isNode(schema) && Object.keys(schema).length === 0)) return UNKNOWN
+    if (schema === true || (isNode(schema) && Object.keys(schema).length === 0))
+      return this.unknown()
     return isNode(schema) ? this.compile(schema, `${where}/*`) : undefined
   }
 
   private object(node: Node, where: string): Project {
-    const declared = new Map<string, Project>()
+    const declared: Record<string, Project> = Object.create(null)
     for (const [key, sub] of Object.entries(isNode(node.properties) ? node.properties : {})) {
       if (!isNode(sub)) continue
       if (isSensitiveFieldName(key) && typeof sub[DECLASSIFIED_KEY] !== "string") {
         this.sensitive.push(`${where}/${key}`)
       }
-      declared.set(key, this.compile(sub, `${where}/${key}`))
+      declared[key] = this.compile(sub, `${where}/${key}`)
     }
     const patterns: Array<readonly [RegExp, Project]> = []
     for (const [pattern, sub] of Object.entries(
@@ -302,7 +316,7 @@ class Compiler {
     }
     // A closed object drops a deferred marker's keys unless it declares them, so only an open one, or
     // one declaring the marker key, could pass a marker on.
-    const checksMarker = open || declared.has("__nifra_deferred")
+    const checksMarker = open || declared.__nifra_deferred !== undefined
     const project: Project = (value, state) => {
       if (typeof value !== "object" || value === null || Array.isArray(value)) return value
       if (checksMarker && isDeferred(value)) {
@@ -325,7 +339,7 @@ class Compiler {
       for (const key in input) {
         // An inherited enumerable key (a polluted prototype) is never data.
         if (!Object.hasOwn(input, key)) continue
-        const projector = declared.get(key) ?? (open ? undeclared(key) : undefined)
+        const projector = declared[key] ?? (open ? undeclared(key) : undefined)
         if (projector === undefined) {
           out ??= copyBefore(input, key)
           continue
@@ -346,6 +360,8 @@ class Compiler {
       }
       return out ?? value
     }
+    if (!checksMarker && Object.values(declared).every((child) => this.issueFree.has(child)))
+      this.issueFree.add(project)
     return project
   }
 
@@ -356,13 +372,32 @@ class Compiler {
         ? node.items
         : []
     const head = prefixNodes.map((sub, i) =>
-      isNode(sub) ? this.compile(sub, `${where}/${i}`) : UNKNOWN,
+      isNode(sub) ? this.compile(sub, `${where}/${i}`) : this.unknown(),
     )
     const restSchema = Array.isArray(node.items) ? node.additionalItems : node.items
-    const rest = this.extra(restSchema, where) ?? UNKNOWN
+    const rest = this.extra(restSchema, where) ?? this.unknown()
     // An array of scalars is the validator's alone: no key to drop, and walking it here would cost
     // every `string[]` a loop. A `Date` inside one reaches the validator as it is.
     if (rest === LEAF && head.every((projector) => projector === LEAF)) return LEAF_ARRAY
+    // A uniform subtree that cannot emit deferred-marker issues needs no per-item path bookkeeping.
+    if (head.length === 0 && this.issueFree.has(rest)) {
+      const project: Project = (value, state) => {
+        if (!Array.isArray(value)) return value
+        let out: unknown[] | undefined
+        for (let i = 0; i < value.length; i++) {
+          const before = value[i]
+          const after = rest(before, state)
+          if (out !== undefined) out[i] = after
+          else if (after !== before) {
+            out = value.slice(0, i)
+            out[i] = after
+          }
+        }
+        return out ?? value
+      }
+      this.issueFree.add(project)
+      return project
+    }
     return (value, state) => {
       if (!Array.isArray(value)) return value
       let out: unknown[] | undefined
@@ -424,7 +459,7 @@ class Compiler {
     const branches: Node[] = []
     this.branches(node, where, branches, new Set())
     const kinds = branches.map(shapeOf)
-    if (kinds.includes("unknown")) return UNKNOWN
+    if (kinds.includes("unknown")) return this.unknown()
     const deferreds = branches.filter((_, i) => kinds[i] === "deferred")
     if (deferreds.length > 1) {
       throw new OutputGuardError(
@@ -463,6 +498,7 @@ class Compiler {
   }
 
   private deferred(node: Node, where: string): Project {
+    this.mayPassMarker = true
     const validate = (node as { readonly [DEFERRED_VALIDATE]?: unknown })[DEFERRED_VALIDATE]
     if (!isNode(node.inner) || typeof validate !== "function") {
       throw new OutputGuardError(
@@ -473,6 +509,7 @@ class Compiler {
       project: this.compile(node.inner, where),
       validate: validate as CompiledGuard["validate"],
       warnDropped: inDevelopment(),
+      deferredFree: false,
     }
     return (value, state) => {
       if (!isDeferred(value)) return value
@@ -591,9 +628,11 @@ export function outputGuard(schema: unknown, owner: string, exportName: string):
   const standard = schema as StandardSchemaV1
   const json = jsonSchemaOf(standard)
   let project: Project | undefined
+  let deferredFree = false
   if (json !== undefined) {
     const compiler = new Compiler(json)
     project = compiler.compile(json, "")
+    deferredFree = !compiler.mayPassMarker
     if (compiler.sensitive.length > 0) {
       throw new OutputGuardError(
         `${owner} declares sensitive field(s) ${compiler.sensitive.join(", ")} in ${exportName}. Remove them, or mark a field that must reach the browser with t.declassified("why it may", schema)`,
@@ -605,6 +644,7 @@ export function outputGuard(schema: unknown, owner: string, exportName: string):
     project,
     validate: standard["~standard"].validate,
     warnDropped: inDevelopment(),
+    deferredFree,
   }
   compiled.set(schema, guard)
   return guard
@@ -675,6 +715,8 @@ function settle(
     // No JSON Schema to project by: the schema's own validate stripped what it does not declare.
     if (guard.warnDropped) warnDropped(label, input, result.value)
   }
+  // Only the projected value itself: a validator that returns a new value (a transform) may add a marker.
+  if (guard.deferredFree && result.value === input) markDeferredFree(result.value)
   return result.value
 }
 

package/src/internal/page-execution.ts

@@ -46,6 +46,7 @@ import {
 } from "../router.ts"
 import { searchOf, searchOfChain } from "../search.ts"
 import { mergeHeads, resolveChainMeta } from "./head-merge.ts"
+import { prepareModules } from "./module-preparation.ts"
 import {
   EMPTY_RETAIN,
   type HeadersLike,
@@ -57,6 +58,7 @@ import {
   notFound,
   type RenderAssemblyCache,
   type RenderedPage,
+  type RenderPageOptions,
   type RevalidateResult,
   redirect,
   renderPageResult,
@@ -67,7 +69,7 @@ import {
   tagLayoutError,
   withDuplicateInstanceHint,
 } from "./render-document.ts"
-import { urlPartsFor } from "./request-url.ts"
+import { originFor, urlPartsFor } from "./request-url.ts"
 import {
   ACTION_SCOPE,
   type CoreResponseControls,
@@ -207,6 +209,7 @@ export interface PageExecutionOptions<Env = unknown> {
   ) => Promise<Response>
   readonly adapter: RenderAdapter
   readonly manifest: Manifest
+  readonly cacheRouteModules?: boolean
   readonly clientEntry: string
   readonly title?: string
   readonly api?: unknown
@@ -296,6 +299,12 @@ type LayoutChain = {
  */
 type LayoutChainSource = (page: RouteModule, count: number) => Promise<LayoutChain | undefined>
 
+/** A document's render input, filled in field by field. */
+type DocumentInput = { -readonly [K in keyof RenderPageOptions]: RenderPageOptions[K] } & {
+  readonly clientEntry: string
+  readonly hydrate: boolean
+}
+
 /**
  * Own the page request program behind one private seam.
  *
@@ -309,6 +318,11 @@ export function createPageRequestExecutor<Env = unknown>(
   options: PageExecutionOptions<Env>,
 ): PageRequestExecutor<Env> {
   const { adapter, manifest, clientEntry, api } = options
+  const cacheModules =
+    options.cacheRouteModules ??
+    (typeof process !== "undefined" && process.env?.NODE_ENV === "production")
+  const loadModule = prepareModules(cacheModules)
+  const preparedLayouts = new WeakMap<RouteEntry, LoadedLayoutModules>()
   // The action result is request-local; a browser cannot manufacture this handoff.
   const progressiveActionData = new WeakMap<Request, unknown>()
   // Bound once per render, so every loader, action and boundary in that render shares one view of the
@@ -326,6 +340,7 @@ export function createPageRequestExecutor<Env = unknown>(
       ? { prerenderedPaths: options.prerenderedPaths ?? [] }
       : { prerenderedListUrl: options.prerenderedListUrl }
   const copyOption = options.copyChunks === undefined ? {} : { copyChunks: options.copyChunks }
+  const appDocumentOptions = { ...prerenderedHandover, ...copyOption, ...cspOption, ...titleOption }
   const { i18n } = options
   const pageLocales = new Map(i18n?.locales.locales.map((locale) => [locale.key, locale]))
   /** The request's locale for a document, with the served locales the client names locales from. */
@@ -420,8 +435,10 @@ export function createPageRequestExecutor<Env = unknown>(
   // Load a route's layout modules once for the current execution. The render path needs each whole
   // module for its component + meta, while the data path also needs loader/gate/boundary declarations.
   const loadLayoutModules = async (route: RouteEntry): Promise<LoadedLayoutModules> => {
+    const known = cacheModules ? preparedLayouts.get(route) : undefined
+    if (known !== undefined) return known
     const modules = await Promise.all(
-      route.layoutIds.map((id) => (manifest.layouts[id] as LayoutEntry).load()),
+      route.layoutIds.map((id) => loadModule(manifest.layouts[id] as LayoutEntry)),
     )
     for (let i = 0; i < modules.length; i++) {
       if ((modules[i] as { action?: unknown }).action === undefined) continue
@@ -430,6 +447,7 @@ export function createPageRequestExecutor<Env = unknown>(
         `[nifra/web] "${(manifest.layouts[id] as LayoutEntry).file}" exports an \`action\`, but layouts do not run one - only route files do. Move the mutation into the route that submits to it.`,
       )
     }
+    if (cacheModules) preparedLayouts.set(route, modules)
     return modules
   }
 
@@ -616,7 +634,7 @@ export function createPageRequestExecutor<Env = unknown>(
       const dirTag = `${id.slice(0, id.length - "_middleware".length)}_layout`
       let outcome: unknown
       try {
-        const middleware = (await entry.load()).default
+        const middleware = (await loadModule(entry)).default
         // A `_layout.backend.ts` that exports no middleware is a layout data module, nothing more.
         if (middleware === undefined) continue
         if (typeof middleware !== "function") {
@@ -774,14 +792,6 @@ export function createPageRequestExecutor<Env = unknown>(
     return undefined
   }
 
-  const originOf = (req: Request): string => {
-    try {
-      return new URL(req.url).origin
-    } catch {
-      return ""
-    }
-  }
-
   const pathOf = (req: Request): string => {
     try {
       const parts = urlPartsFor(req)
@@ -794,8 +804,8 @@ export function createPageRequestExecutor<Env = unknown>(
   /** What a status or error page's `meta` receives: no route params, and its own data. */
   const statusMetaArgs = (req: Request, data: unknown, nonce: string | undefined): MetaArgs =>
     nonce === undefined
-      ? { data, pageData: data, params: {}, origin: originOf(req) }
-      : { data, pageData: data, params: {}, origin: originOf(req), nonce }
+      ? { data, pageData: data, params: {}, origin: originFor(req) }
+      : { data, pageData: data, params: {}, origin: originFor(req), nonce }
 
   const renderError = async (
     req: Request,
@@ -1121,13 +1131,15 @@ export function createPageRequestExecutor<Env = unknown>(
         data,
         pageData: data,
         params,
-        origin: originOf(req),
+        origin: originFor(req),
         ...(nonce === undefined ? {} : { nonce }),
       },
       serverLeafOf(route, mod),
     )
     try {
-      return await renderPageResult({
+      // Optional fields are assigned, not spread in: a conditional spread per field cost every
+      // document request about 1us on Bun.
+      const page: DocumentInput = {
         adapter,
         chain,
         data,
@@ -1138,38 +1150,32 @@ export function createPageRequestExecutor<Env = unknown>(
         path: pathOf(req),
         search: searchChainOf(layoutModules, mod, req),
         matchChain: matchChainOf(route.layoutIds, layoutModules, route.id, mod),
-        ...(serverComponents === undefined ? {} : { serverComponents }),
-        ...(progressiveActionData.has(req) ? { actionData: progressiveActionData.get(req) } : {}),
         hydrate: mod.hydrate !== false,
-        ...(layoutData !== undefined ? { layoutData } : {}),
-        ...(boundaryStates !== undefined ? { boundaries: boundaryStates } : {}),
         ...preloadOf(route.id),
         ...stylesOf(route.id),
-        ...prerenderedHandover,
-        ...copyOption,
+        ...appDocumentOptions,
         ...localeOption(req),
-        ...(responseHeaders === undefined ? {} : { headers: responseHeaders }),
-        // A response that sets a cookie is one visitor's: it never advertises ISR freshness.
-        ...(mod.revalidate !== undefined && !personalized && options.cacheChannel?.enabled === true
-          ? { revalidate: mod.revalidate }
-          : {}),
-        ...(mod.revalidateTags !== undefined &&
-        !personalized &&
-        options.cacheChannel?.enabled === true
-          ? {
-              revalidateTags: routeTags(
-                mod.revalidateTags,
-                { params, url: new URL(req.url) },
-                route.id,
-              ),
-            }
-          : {}),
-        ...(mod.islandScripts !== undefined ? { islandScripts: mod.islandScripts } : {}),
-        ...(nonce === undefined ? {} : { nonce }),
-        ...cspOption,
-        ...titleOption,
-        ...(assemblyCache === undefined ? {} : { assemblyCache }),
-      })
+      }
+      if (serverComponents !== undefined) page.serverComponents = serverComponents
+      if (progressiveActionData.has(req)) page.actionData = progressiveActionData.get(req)
+      if (layoutData !== undefined) page.layoutData = layoutData
+      if (boundaryStates !== undefined) page.boundaries = boundaryStates
+      if (responseHeaders !== undefined) page.headers = responseHeaders
+      // A response that sets a cookie is one visitor's: it never advertises ISR freshness.
+      if (!personalized && options.cacheChannel?.enabled === true) {
+        if (mod.revalidate !== undefined) page.revalidate = mod.revalidate
+        if (mod.revalidateTags !== undefined) {
+          page.revalidateTags = routeTags(
+            mod.revalidateTags,
+            { params, url: new URL(req.url) },
+            route.id,
+          )
+        }
+      }
+      if (mod.islandScripts !== undefined) page.islandScripts = mod.islandScripts
+      if (nonce !== undefined) page.nonce = nonce
+      if (assemblyCache !== undefined) page.assemblyCache = assemblyCache
+      return await renderPageResult(page)
     } catch (err) {
       if (isStatusSignal(err)) return renderStatusSignal(req, env, err, personalized, settled)
       if (isControlFlow(err)) throw err
@@ -1252,7 +1258,7 @@ export function createPageRequestExecutor<Env = unknown>(
       data: null,
       pageData: null,
       params,
-      origin: originOf(req),
+      origin: originFor(req),
       ...(nonce === undefined ? {} : { nonce }),
     })
     let headers: Headers | undefined
@@ -1410,7 +1416,8 @@ export function createPageRequestExecutor<Env = unknown>(
         if (!componentOwner && is404Fallback && !prerenderedSet.has(urlPartsFor(c.req).pathname)) {
           return renderNotFound(c, controls)
         }
-        const mod = await route.load()
+        const loaded = loadModule(route)
+        const mod = cacheModules && !(loaded instanceof Promise) ? loaded : await loaded
         const draft = await draftFlag(c.req)
         // Unpublished content is the editor's alone: whatever cache-control a loader sets, no cache keeps it.
         if (draft) controls.personalize()
@@ -1592,7 +1599,8 @@ export function createPageRequestExecutor<Env = unknown>(
 
     post: (route) =>
       withResponseControls(async (c, controls) => {
-        const mod = await route.load()
+        const loaded = loadModule(route)
+        const mod = cacheModules && !(loaded instanceof Promise) ? loaded : await loaded
         const draft = await draftFlag(c.req)
         if (draft) controls.personalize()
         if (mod.action === undefined) {
@@ -1810,7 +1818,7 @@ export function createPageRequestExecutor<Env = unknown>(
             data,
             pageData: data,
             params: c.params,
-            origin: originOf(c.req),
+            origin: originFor(c.req),
             ...(nonce === undefined ? {} : { nonce }),
           },
           serverLeafOf(route, mod),

package/src/internal/parity.ts

@@ -16,6 +16,7 @@ import {
   SINGLE_COPY_REGISTER_SPECIFIER,
   type SingleCopyRegistration,
 } from "@nifrajs/core/single-copy"
+import { isHiddenPath } from "@nifrajs/core/static-file"
 import { discoverRoutes } from "../fs.ts"
 import { codeUnitOrder } from "./code-unit-order.ts"
 import { withoutComments } from "./html-spans.ts"
@@ -1077,6 +1078,7 @@ const publicFilesUnder = (publicDir: string | false | undefined): readonly strin
   const files: string[] = []
   const walk = (current: string): void => {
     for (const entry of readdirSync(current, { withFileTypes: true })) {
+      if (isHiddenPath(entry.name)) continue // the build skips it too
       const path = join(current, entry.name)
       if (entry.isDirectory()) walk(path)
       else if (entry.isFile()) files.push(publicUrlPath(relative(root, path)))

package/src/internal/prerendered-pages.ts

@@ -0,0 +1,124 @@
+import { pathnameOf } from "@nifrajs/core/server"
+import { isDraftEnabled } from "../draft.ts"
+import { DATA_HEADER } from "../router.ts"
+
+/**
+ * Pages a self-hosted build prerendered, which `createWebApp` answers from their file instead of
+ * rendering them. The file is served from inside the app, after `use` middleware, so a gate in front of
+ * the pages still runs.
+ */
+export interface PrerenderedPages {
+  /** Each servable path, spelled as a request URL spells it, mapped to the document headers its
+   * build-time render answered with (a prerender entry's `serveHeaders`). */
+  readonly pages: Readonly<Record<string, Readonly<Record<string, string>>>>
+  /** The page's HTML, or `undefined` to render it on demand instead. */
+  read(pathname: string): Promise<string | undefined>
+}
+
+// The document headers a render produces from the route alone, so the build-time value is the value
+// every request would get. Loader headers are left out: a prerendered page is a static file.
+const REPLAYED = [
+  "content-language",
+  "content-security-policy",
+  "content-security-policy-report-only",
+]
+// Vary values a file still answers correctly: compression is negotiated by the host, and a data request
+// never reaches the file.
+const STATIC_VARY = new Set(["accept-encoding", DATA_HEADER])
+
+/**
+ * The headers a self-hosted server replays with a prerendered page, or `undefined` when its build-time
+ * render was specific to that request and the page must keep rendering on demand: it set a cookie, was
+ * marked private or no-store (a nonce page always is), or varied on a request header.
+ */
+export function prerenderedDocumentHeaders(
+  status: number,
+  headers: Headers,
+): Record<string, string> | undefined {
+  if (status !== 200 || headers.has("set-cookie")) return undefined
+  const cacheControl = (headers.get("cache-control") ?? "").toLowerCase()
+  if (/\b(?:private|no-store)\b/.test(cacheControl)) return undefined
+  for (const name of (headers.get("vary") ?? "").split(",")) {
+    const trimmed = name.trim().toLowerCase()
+    if (trimmed !== "" && !STATIC_VARY.has(trimmed)) return undefined
+  }
+  const replayed: Record<string, string> = {}
+  for (const name of REPLAYED) {
+    const value = headers.get(name)
+    if (value !== null) replayed[name] = value
+  }
+  return replayed
+}
+
+/** One page a self-hosting build prerendered: its file and the headers it is served with. */
+export interface ServerPrerenderedPage {
+  readonly file: string
+  readonly headers: Readonly<Record<string, string>>
+}
+
+/**
+ * The prerendered pages a server may answer from their file, keyed by the pathname of the request that
+ * rendered them. Left out: a render specific to its request, and two paths written to one file (`/x`
+ * and `//x`, or `/A` and `/a` on a case-insensitive disk), where only the last render is on disk.
+ */
+export function servablePrerenderedPages(
+  entries: readonly {
+    readonly path: string
+    readonly file: string
+    readonly serveHeaders?: Readonly<Record<string, string>>
+  }[],
+): Record<string, ServerPrerenderedPage> {
+  const writes = new Map<string, number>()
+  for (const { file } of entries) {
+    writes.set(file.toLowerCase(), (writes.get(file.toLowerCase()) ?? 0) + 1)
+  }
+  const pages: Record<string, ServerPrerenderedPage> = {}
+  for (const { path, file, serveHeaders } of entries) {
+    if (serveHeaders === undefined || writes.get(file.toLowerCase()) !== 1) continue
+    // Concatenated as prerenderRoutes requested it: `new URL("//x", base)` would read a host.
+    pages[new URL(`http://localhost${path}`).pathname] = { file, headers: serveHeaders }
+  }
+  return pages
+}
+
+/**
+ * Wrap a page route's GET handler so a plain document request for a prerendered path is answered from
+ * its file. Anything a file cannot answer the way a render would renders on demand: a query string, a
+ * navigation data or component request, a draft-mode visitor, or a file the reader cannot return.
+ */
+export function servePrerenderedPages(
+  prerendered: PrerenderedPages,
+  draftSecret: string | undefined,
+): <C extends { readonly req: Request }, R>(
+  render: (c: C) => Promise<R>,
+) => (c: C) => Promise<R | Response> {
+  const pages = new Map(Object.entries(prerendered.pages))
+  return (render) => async (c) => {
+    const req = c.req
+    const pathname = pathnameOf(req.url)
+    const headers = pages.get(pathname)
+    if (
+      headers === undefined ||
+      req.url.includes("?") ||
+      req.headers.has(DATA_HEADER) ||
+      req.headers.has("x-nifra-component") ||
+      (draftSecret !== undefined && (await isDraftEnabled(req, draftSecret)))
+    ) {
+      return render(c)
+    }
+    const html = await prerendered.read(pathname)
+    if (html === undefined) return render(c)
+    if (req.method !== "HEAD") {
+      return new Response(html, {
+        headers: { ...headers, "content-type": "text/html; charset=utf-8" },
+      })
+    }
+    return new Response(null, {
+      headers: {
+        ...headers,
+        "content-type": "text/html; charset=utf-8",
+        "content-length": String(new TextEncoder().encode(html).byteLength),
+      },
+    })
+  }
+}