@nifrajs/web 5.5.0 → 5.6.0

package/src/internal/ppr/compile-shell.ts

@@ -0,0 +1,379 @@
+import { createRequire } from "node:module"
+import { basename, join, resolve } from "node:path"
+import type * as TS from "typescript"
+import type { Manifest, RouteEntry } from "../../manifest.ts"
+import { type BunMetafileLike, fromBunMetafile } from "../../module-graph.ts"
+import { isTypeScriptCompiler } from "../typescript-api.ts"
+
+/**
+ * Which routes passed the shell check for one deployment. The server shares a shell only for a route
+ * listed here under its own deployment; anything else renders blocking (fail closed).
+ */
+export interface ShellCheckRecord {
+  readonly v: 1
+  readonly deployment: string
+  /** Route id to the sha256 of the checked shell bundle. */
+  readonly routes: Readonly<Record<string, string>>
+  /** Route id to the shared holes whose loaders were checked in that bundle: only these are stored. */
+  readonly sharedHoles?: Readonly<Record<string, readonly string[]>>
+}
+
+export class ShellCheckError extends Error {
+  override readonly name = "ShellCheckError"
+  constructor(
+    readonly routeId: string,
+    readonly chain: readonly string[],
+  ) {
+    super(
+      `[nifra/web] ppr: the shell of route "${routeId}" reaches request-scoped module "${chain.at(-1)}" through ${chain.join(" -> ")}. Move that read into a dynamic boundary's loader: a shared boundary's loader is part of the shell`,
+    )
+  }
+}
+
+export interface CompileShellsOptions {
+  readonly routesDir: string
+  readonly manifest: Manifest
+  /** The deployment the record is for: the server refuses a record made for another one. */
+  readonly deployment: string
+  /** True for a module (absolute path, `/` separators) whose code reads the visitor's request. */
+  readonly requestScoped: (moduleId: string) => boolean
+  /** Called for each route that fails; the route is left out of the record. Default: rethrow. */
+  readonly onFailure?: (routeId: string, error: unknown) => void
+  /** Bun plugins the server build uses for route files, such as `svelteBunPlugin("ssr")`. */
+  readonly plugins?: readonly import("bun").BunPlugin[]
+}
+
+const NAMESPACE = "nifra-ppr-shell"
+
+const toPosix = (path: string): string => path.replaceAll("\\", "/")
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+/**
+ * nifra's own modules that read the visitor's request from async context. Packages stay external in
+ * the shell bundle, so these are bundled in instead: the output graph then shows whether shell code
+ * calls them, not merely whether a module beside it imports them.
+ */
+const NIFRA_REQUEST_SCOPED: readonly string[] = ["@nifrajs/middleware/context-storage"]
+const NIFRA_REQUEST_SCOPED_FILTER = new RegExp(
+  `^(?:${NIFRA_REQUEST_SCOPED.map(escapeRegExp).join("|")})$`,
+)
+
+/** Hands any module the Worker's `env`, its secrets included, with no request in sight. */
+const PLATFORM_ENV = /^cloudflare:workers$/
+
+/** The import chain from `root` to the first request-scoped module it reaches, breadth first. */
+function requestScopedChain(
+  root: string,
+  next: ReadonlyMap<string, readonly string[]>,
+  scoped: ReadonlySet<string>,
+): string[] | undefined {
+  const parent = new Map<string, string | undefined>([[root, undefined]])
+  const queue = [root]
+  for (let cursor = 0; cursor < queue.length; cursor++) {
+    const module = queue[cursor]
+    if (module === undefined) break
+    if (scoped.has(module)) {
+      const chain: string[] = []
+      for (let at: string | undefined = module; at !== undefined; at = parent.get(at))
+        chain.push(at)
+      return chain.reverse()
+    }
+    for (const child of next.get(module) ?? []) {
+      if (!parent.has(child)) {
+        parent.set(child, module)
+        queue.push(child)
+      }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Bundle each route's shell (its page and layout modules, its backend `shellLoader`, and nothing else)
+ * and refuse it when the emitted code reaches a request-scoped module. A module counts only
+ * when its code reached the output, so an import only a hole loader uses is not a leak. Routes whose
+ * backend half has no `shellLoader` are skipped. Bun only.
+ */
+export async function compileShells(options: CompileShellsOptions): Promise<ShellCheckRecord> {
+  const dir = resolve(options.routesDir)
+  const routes: Record<string, string> = {}
+  const sharedHoles: Record<string, readonly string[]> = {}
+  const parser = typeScriptFor(dir)
+  for (const route of options.manifest.routes) {
+    if (route.backend === undefined) continue
+    try {
+      const checked = await compileShell(
+        dir,
+        options.manifest,
+        route,
+        route.backend,
+        options.requestScoped,
+        options.plugins ?? [],
+        parser,
+      )
+      if (checked === undefined) continue
+      routes[route.id] = checked.hash
+      if (checked.sharedHoles.length > 0) sharedHoles[route.id] = checked.sharedHoles
+    } catch (error) {
+      if (options.onFailure === undefined) throw error
+      options.onFailure(route.id, error)
+    }
+  }
+  return Object.keys(sharedHoles).length === 0
+    ? { v: 1, deployment: options.deployment, routes }
+    : { v: 1, deployment: options.deployment, routes, sharedHoles }
+}
+
+/** The app's TypeScript compiler, read only when a backend half has boundary loaders to sort. */
+function typeScriptFor(dir: string): () => typeof TS | undefined {
+  let loaded: typeof TS | undefined
+  let tried = false
+  return () => {
+    if (tried) return loaded
+    tried = true
+    let ts: unknown
+    try {
+      ts = createRequire(join(dir, "package.json"))("typescript")
+    } catch {
+      ts = undefined
+    }
+    if (isTypeScriptCompiler(ts)) loaded = ts
+    else {
+      console.warn(
+        "[nifra/web] ppr: no shared hole's loader is checked, so each loads for every visitor: finding them reads boundaryLoaders with the TypeScript compiler API, which the app's TypeScript does not have (TypeScript 7 ships none; install typescript@^6 as a dev dependency)",
+      )
+    }
+    return loaded
+  }
+}
+
+/** `node` without the `satisfies`, `as` and parentheses around it. */
+function unwrapped(ts: typeof TS, node: TS.Expression): TS.Expression {
+  let at = node
+  while (ts.isSatisfiesExpression(at) || ts.isAsExpression(at) || ts.isParenthesizedExpression(at))
+    at = at.expression
+  return at
+}
+
+/**
+ * The backend half with `boundaryLoaders` cut down to its shared entries, and their names. A shared
+ * entry is one written inline with `revalidate`, which only a shared boundary's entry may have; one the
+ * source does not spell out that way is left out, so its hole is not stored (fail closed). A per-visitor
+ * entry's loader may read the request, so it never joins the shell bundle.
+ */
+function sharedLoaders(
+  ts: typeof TS,
+  module: SourceModule,
+): { readonly source: string; readonly names: readonly string[] } | undefined {
+  const file = ts.createSourceFile(
+    module.path,
+    module.source,
+    ts.ScriptTarget.Latest,
+    true,
+    module.loader === "tsx" ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  )
+  for (const statement of file.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "boundaryLoaders")
+        continue
+      const initializer = declaration.initializer && unwrapped(ts, declaration.initializer)
+      if (initializer === undefined || !ts.isObjectLiteralExpression(initializer)) return undefined
+      const names: string[] = []
+      const kept: string[] = []
+      for (const property of initializer.properties) {
+        if (!ts.isPropertyAssignment(property)) continue
+        const { name } = property
+        if (!ts.isIdentifier(name) && !ts.isStringLiteral(name)) continue
+        const entry = unwrapped(ts, property.initializer)
+        if (!ts.isObjectLiteralExpression(entry)) continue
+        const shared = entry.properties.some(
+          (field) =>
+            field.name !== undefined &&
+            (ts.isIdentifier(field.name) || ts.isStringLiteral(field.name)) &&
+            field.name.text === "revalidate",
+        )
+        if (!shared) continue
+        names.push(name.text)
+        kept.push(module.source.slice(property.getStart(file), property.getEnd()))
+      }
+      if (names.length === 0) return undefined
+      const source = `${module.source.slice(0, initializer.getStart(file))}{ ${kept.join(", ")} }${module.source.slice(initializer.getEnd())}`
+      return { source, names }
+    }
+  }
+  return undefined
+}
+
+interface SourceModule {
+  readonly path: string
+  readonly loader: "ts" | "tsx"
+  readonly source: string
+  /** The names it exports, read from its source without running it. */
+  readonly exports: readonly string[]
+}
+
+async function readModule(dir: string, file: string): Promise<SourceModule> {
+  const path = toPosix(resolve(dir, file))
+  const loader = /\.[cm]?tsx$|\.jsx$/.test(path) ? "tsx" : "ts"
+  const source = await Bun.file(path).text()
+  return { path, loader, source, exports: new Bun.Transpiler({ loader }).scan(source).exports }
+}
+
+async function compileShell(
+  dir: string,
+  manifest: Manifest,
+  route: RouteEntry,
+  backend: string,
+  requestScoped: (moduleId: string) => boolean,
+  plugins: readonly import("bun").BunPlugin[],
+  parser: () => typeof TS | undefined,
+): Promise<{ readonly hash: string; readonly sharedHoles: readonly string[] } | undefined> {
+  const backendModule = await readModule(dir, backend)
+  if (!backendModule.exports.includes("shellLoader")) return undefined
+  const ts = backendModule.exports.includes("boundaryLoaders") ? parser() : undefined
+  const shared = ts === undefined ? undefined : sharedLoaders(ts, backendModule)
+  const kept = shared === undefined ? ["shellLoader"] : ["shellLoader", "boundaryLoaders"]
+  // A gate's loader runs for its redirect or refusal and its data never reaches the shell; any other
+  // layout loader reads the request for data the shell would show every visitor.
+  for (const id of route.layoutIds) {
+    const layoutBackend = manifest.layouts[id]?.backend
+    if (layoutBackend === undefined) continue
+    const names = (await readModule(dir, layoutBackend)).exports
+    if (names.includes("loader") && !names.includes("gate")) {
+      throw new Error(
+        `[nifra/web] ppr: route "${route.id}" has a shellLoader, but its layout "${id}" has a loader that is not a gate. Its output would be in a shell shared by every visitor; move that data into a dynamic boundary, or mark the layout \`gate\` if it loads only to redirect or refuse`,
+      )
+    }
+  }
+  const at = (file: string): string => JSON.stringify(toPosix(resolve(dir, file)))
+  // A page's and each layout's module whole: the shell runs `meta`, `handle` and `searchSchema` as
+  // well as the component, and an import only one of them uses must not escape the check.
+  const lines = [
+    `export { ${kept.join(", ")} } from ${at(backend)}`,
+    `export * as page from ${at(route.file)}`,
+  ]
+  route.layoutIds.forEach((id, index) => {
+    const layout = manifest.layouts[id]
+    if (layout !== undefined) lines.push(`export * as layout${index} from ${at(layout.file)}`)
+  })
+  const nifraScoped = new Set<string>()
+  const envImporters = new Set<string>()
+  const result = await Bun.build({
+    // Bun reads a `/` in an entry name as a directory, and route ids have them.
+    entrypoints: [`${NAMESPACE}:${encodeURIComponent(route.id)}`],
+    target: "bun",
+    packages: "external",
+    metafile: true,
+    throw: false,
+    plugins: [
+      // Ours first: its resolve and load hooks claim the entry and the backend half before theirs.
+      {
+        name: NAMESPACE,
+        setup(build) {
+          build.onResolve({ filter: new RegExp(`^${NAMESPACE}:`) }, (args) => ({
+            path: args.path,
+            namespace: NAMESPACE,
+          }))
+          build.onLoad({ filter: /.*/, namespace: NAMESPACE }, () => ({
+            loader: "ts",
+            contents: lines.join("\n"),
+          }))
+          build.onResolve({ filter: NIFRA_REQUEST_SCOPED_FILTER }, (args) => {
+            let path: string
+            try {
+              path = toPosix(Bun.resolveSync(args.path, args.resolveDir))
+            } catch {
+              // Not installed, so no shell code can call it.
+              return undefined
+            }
+            nifraScoped.add(path)
+            return { path }
+          })
+          build.onResolve({ filter: PLATFORM_ENV }, (args) => {
+            envImporters.add(toPosix(resolve(args.importer)))
+            return { path: args.path, external: true }
+          })
+          // The backend half's other exports are not shell code. A hole loader's `output: t.object()`
+          // is a call into a package, which the bundler must keep, and with it every import the
+          // hole uses. Eliminating them first scopes the check to `shellLoader` and the shared
+          // holes' loaders; their imports stay as bare imports, so a module with top-level effects
+          // still counts. The file is matched by its `/` form: Bun hands a plugin `\` on Windows.
+          build.onLoad(
+            { filter: new RegExp(`${escapeRegExp(basename(backendModule.path))}$`) },
+            (args) =>
+              toPosix(args.path) !== backendModule.path
+                ? undefined
+                : {
+                    loader: "js",
+                    contents: new Bun.Transpiler({
+                      loader: backendModule.loader,
+                      trimUnusedImports: true,
+                      exports: {
+                        eliminate: backendModule.exports.filter((name) => !kept.includes(name)),
+                      },
+                    }).transformSync(shared?.source ?? backendModule.source),
+                  },
+          )
+        },
+      },
+      ...plugins,
+    ],
+  })
+  if (!result.success) {
+    throw new AggregateError(
+      result.logs,
+      `[nifra/web] ppr: the shell of "${route.id}" failed to build`,
+    )
+  }
+  // biome-ignore lint/plugin/noChainedTypeAssertions: Bun returns the metafile when `metafile: true`; @types/bun does not name it yet, and fromBunMetafile fails closed on a missing one.
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Bun returns the metafile when `metafile: true`; @types/bun does not name it yet, and fromBunMetafile fails closed on a missing one.
+  const meta = (result as unknown as { readonly metafile?: BunMetafileLike }).metafile
+  const graph = fromBunMetafile(meta)
+  const entry = Object.values(meta?.outputs ?? {}).find((output) =>
+    output.entryPoint?.startsWith(`${NAMESPACE}:`),
+  )
+  if (entry === undefined)
+    throw new Error(`[nifra/web] ppr: no output for the shell of "${route.id}"`)
+  // Re-exports and the virtual entry have zero bytes too, so every edge stays and only the
+  // request-scoped test reads bytes.
+  const emitted = (id: string): boolean => {
+    const input = entry.inputs?.[id]
+    return (
+      typeof input === "object" &&
+      input !== null &&
+      "bytesInOutput" in input &&
+      typeof input.bytesInOutput === "number" &&
+      input.bytesInOutput > 0
+    )
+  }
+  const absolute = (id: string): string =>
+    id.startsWith(`${NAMESPACE}:`) ? id : toPosix(resolve(id))
+  const next = new Map<string, string[]>()
+  const scoped = new Set<string>()
+  let root: string | undefined
+  for (const [id, module] of Object.entries(graph.modules)) {
+    const from = absolute(id)
+    if (id.startsWith(`${NAMESPACE}:`)) root = from
+    if (emitted(id) && (nifraScoped.has(from) || envImporters.has(from) || requestScoped(from)))
+      scoped.add(from)
+    next.set(
+      from,
+      module.imports.flatMap((edge) => (edge.path === undefined ? [] : [absolute(edge.path)])),
+    )
+  }
+  if (root === undefined) throw new Error(`[nifra/web] ppr: no entry module for "${route.id}"`)
+  const chain = requestScopedChain(root, next, scoped)
+  if (chain !== undefined) throw new ShellCheckError(route.id, chain.slice(1))
+  const output = result.outputs.find((artifact) => artifact.kind === "entry-point")
+  if (output === undefined)
+    throw new Error(`[nifra/web] ppr: no bundle for the shell of "${route.id}"`)
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(await output.text())),
+  )
+  return {
+    hash: Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join(""),
+    sharedHoles: shared?.names ?? [],
+  }
+}

package/src/internal/ppr/contract.ts

@@ -0,0 +1,265 @@
+/**
+ * What the page executor and `createWebApp` know of partial prerendering. Everything here is small and
+ * imports no runtime code: the server, its options and the hole HTML validator load only through
+ * `partialPrerendering` (`@nifrajs/web/ppr`), so an app without it carries none of them.
+ */
+import type {
+  BoundaryRegistration,
+  BoundaryRequestCtx,
+  BoundaryStates,
+  ShellCtx,
+} from "../../boundary.ts"
+import type { CspPolicy } from "../../csp.ts"
+import type { RevalidateTags } from "../../isr.ts"
+import type { RouteEntry, RouteModule } from "../../manifest.ts"
+import type { RenderAdapter } from "../../render-seam.ts"
+import type { LoadedLayoutModules } from "../render-document.ts"
+import type { PprAdmissionStats } from "./admission.ts"
+import type { ResolvedPprOptions } from "./options.ts"
+
+/** An app built with `experimental.ppr` carries its {@link PprServer} under this key. */
+export const PPR_SERVER: unique symbol = Symbol.for("nifra.web.ppr")
+
+/** The key of a {@link PprSetup}'s factory. */
+export const PPR_SETUP: unique symbol = Symbol.for("nifra.web.ppr.setup")
+
+/** Where the runtime's cancel beacon goes, under the app's base path. */
+export const PPR_CANCEL_PATH = "/__nifra/ppr/cancel"
+
+interface HoleFields {
+  readonly interactive?: boolean
+  readonly timeout?: number
+}
+
+/** A hole filled per visitor. */
+export type DynamicHole = Extract<BoundaryRegistration, { readonly mode: "dynamic" }> & HoleFields
+
+/** A hole built once for every visitor, with its loader entry's freshness merged in. */
+export type SharedHole = Extract<BoundaryRegistration, { readonly mode: "shared" }> &
+  HoleFields & {
+    readonly revalidate: number
+    readonly revalidateTags?: RevalidateTags | undefined
+  }
+
+/** The boundary fields partial prerendering reads beyond the neutral registration. */
+export type HoleRegistration = DynamicHole | SharedHole
+
+export const isHole = (boundary: BoundaryRegistration): boundary is HoleRegistration =>
+  boundary.mode === "dynamic" || boundary.mode === "shared"
+
+/** The key `serverHole()` stores a hole's server component under, on the hole's `render`. */
+export const SERVER_HOLE: unique symbol = Symbol.for("nifra.web.server-hole")
+
+/** The server component a hole's `render` names, or `undefined` for an ordinary `render`. */
+export const serverHoleComponent = (render: unknown): object | undefined => {
+  if (typeof render !== "function") return undefined
+  const component: unknown = Reflect.get(render, SERVER_HOLE)
+  return typeof component === "object" && component !== null ? component : undefined
+}
+
+/** What the page executor hands over for one PPR request. */
+export interface PprRequest {
+  readonly routeId: string
+  /** The request's pathname, without search: the shell renders it, so it is part of the key. */
+  readonly path: string
+  readonly locale: string | undefined
+  /** The declared variations this request selected, by name; part of the shell key. */
+  readonly variations: Readonly<Record<string, string>>
+  readonly request: Request
+  /** The route's dynamic and shared boundaries, in declaration order, with their merged (guarded)
+   * loaders. */
+  readonly holes: readonly HoleRegistration[]
+  readonly holeContext: Omit<BoundaryRequestCtx, "signal" | "live">
+  /** What the shell loader and every shared hole loader get, but the build's signal. */
+  readonly shellContext: Omit<ShellCtx, "signal">
+  readonly loadShell: (signal: AbortSignal) => Promise<unknown>
+  /** Render the full document for `shellData` with every hole pending, under no nonce. */
+  readonly renderShellDocument: (shellData: unknown, states: BoundaryStates) => Promise<string>
+  /** The route's `revalidate`, in seconds: an older shell is served while one rebuild runs. */
+  readonly revalidate: number | undefined
+  /** The route's `revalidateTags` for this request, read only when a shell is built. */
+  readonly tags: () => readonly string[]
+  /** A shared hole's `revalidateTags` for this request, read only when its entry is built. */
+  readonly holeTags: (hole: SharedHole) => readonly string[]
+  /** Keeps the platform alive for work that outlives the response, where the platform needs it. */
+  readonly waitUntil?: ((promise: Promise<unknown>) => void) | undefined
+  /** The holes the client holds as hosts: a data request sends each one's fill. A hole that shows a
+   * server component always gets its fill. */
+  readonly fill?: ReadonlySet<string>
+  /** Render a hole's server component for this visitor, when the app's server components list it. */
+  readonly component?: (
+    hole: string,
+    component: object,
+    input: unknown,
+    signal: AbortSignal,
+  ) => Promise<{ readonly html: string }>
+  /** Holes the client keeps: none of them loads, and each state says it was kept. */
+  readonly kept?: ReadonlySet<string>
+  /** A live load: each hole's keys, and which holes loaded. */
+  readonly live?: HoleLive
+}
+
+/** A live load's view of one response's holes. Owners are named by hole. */
+export interface HoleLive {
+  /** `ctx.live` for one hole's loader. */
+  collector(hole: string): (...keys: string[]) => void
+  /** Close one hole's collector once its loader settled. */
+  seal(hole: string): void
+  /** Called once, after every hole that ran settled, with the holes that loaded. */
+  done(loaded: readonly string[]): void
+}
+
+/** The shell cannot be served now; the caller renders the page whole for this request. */
+export class PprShellUnavailable extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "PprShellUnavailable"
+  }
+}
+
+/** Thrown when a route's shell has no passing import-check record. */
+export class PprShellUnchecked extends PprShellUnavailable {
+  constructor(routeId: string) {
+    super(
+      `[nifra/web] ppr: route "${routeId}" has no passing shell import check; rendered blocking`,
+    )
+  }
+}
+
+/** Thrown when a route already runs `shellBuildConcurrency` shell builds: no request waits on one. */
+export class PprShellBusy extends PprShellUnavailable {
+  constructor(routeId: string) {
+    super(`[nifra/web] ppr: route "${routeId}" is at its shell build limit; rendered blocking`)
+  }
+}
+
+/** Thrown for a key seen fewer than `shellAfterRequests` times in a full store: the page streams whole. */
+export class PprShellCold extends PprShellUnavailable {
+  constructor(routeId: string) {
+    super(`[nifra/web] ppr: route "${routeId}" has no shell for this key yet; rendered whole`)
+  }
+}
+
+/**
+ * How a response that is not a streamed document gets its holes. `"deferred"`: each hole runs under
+ * admission and its own deadline, and its state carries the result as a deferred value (a soft
+ * navigation's data request). `"settled"`: the same, awaited (the blocking render). `"omitted"`: no
+ * hole runs and every state is an empty host (a prefetch, which must not start work its navigation
+ * cannot cancel).
+ */
+export type HoleStatesMode = "deferred" | "settled" | "omitted"
+
+export interface PprServerStats extends PprAdmissionStats {
+  /** Responses aborted because unsent bytes went over `maxUnsentBytes` (`ppr.slow_aborted`). */
+  readonly slowAborted: number
+  /** Frame bytes queued for clients across every live PPR stream. */
+  readonly unsentBytes: number
+}
+
+export interface PprServer {
+  /** Stream one PPR document: the shared shell at once, then each hole as it settles. */
+  respond(request: PprRequest): Promise<Response>
+  /** The shell data a soft navigation's data request carries. */
+  shellData(request: PprRequest): Promise<unknown>
+  /** The hole states of a data request or a blocking render; `signal` is the request's. */
+  holeStates(
+    request: PprRequest,
+    mode: HoleStatesMode,
+    signal: AbortSignal,
+  ): Promise<BoundaryStates>
+  /** Abort the response that printed `token`. Unknown tokens do nothing. */
+  cancel(token: string): boolean
+  /**
+   * Drop every shell and shared hole frame carrying `tag`. A build of either that started before the
+   * call is not stored when it finishes, so an entry built from data read before the purge never
+   * outlives it.
+   */
+  invalidateTag(tag: string): Promise<void>
+  stats(): PprServerStats
+}
+
+/** What `createWebApp` gives a {@link PprSetup}: the parts of the app a PPR server depends on. */
+export interface PprEnvironment {
+  readonly adapter: RenderAdapter
+  readonly csp?: CspPolicy
+  /** Part of every shell key, so a shell built by one deployment is never served by another. */
+  readonly deployment: string
+  /** The app authorizes scripts with a per-request nonce, which would make every shell unique. */
+  readonly perRequestNonce: boolean
+}
+
+/** One app's partial prerendering, as the page executor uses it. */
+export interface PprIntegration {
+  readonly server: PprServer
+  /** The configured public origin a shell may use; never a visitor's Host. */
+  readonly origin?: string
+  /** Where the runtime's cancel beacon posts, and its handler. */
+  readonly cancelPath: string
+  cancel(request: Request): Promise<Response>
+  /**
+   * The streamed document, with the headers middleware and gates wrote, or how this request renders
+   * whole instead: `"settled"` for a listed bot or a shell that is unchecked or at its build limit,
+   * `"deferred"`, each hole streamed as it settles, for a key with no shell yet.
+   */
+  stream(
+    request: PprRequest,
+    written: () => Readonly<Record<string, string>> | undefined,
+  ): Promise<Response | "settled" | "deferred">
+  /** The shell data, or the shell loader's own output when the shell cannot be served now. */
+  shellData(request: PprRequest, signal: AbortSignal): Promise<unknown>
+  /** `variations` as the shell's own query string. */
+  variationQuery(variations: Readonly<Record<string, string>>): string
+  /** Throws for a route the PPR rules keep off the PPR path: its layouts, holes and their limits. */
+  assertRoute(
+    route: RouteEntry,
+    layouts: LoadedLayoutModules,
+    boundaries: readonly BoundaryRegistration[],
+  ): void
+  /** The declared variations `search` selects. */
+  variationsOf(
+    declared: RouteModule["shellVariations"],
+    search: string,
+  ): Readonly<Record<string, string>>
+}
+
+/** What `partialPrerendering()` returns for `createWebApp({ experimental: { ppr } })`. */
+export interface PprSetup {
+  readonly [PPR_SETUP]: (environment: PprEnvironment) => PprIntegration
+}
+
+/** `variations` as a query string, sorted by name: the shell key part and the shell's own search. */
+export const variationQuery = (variations: Readonly<Record<string, string>>): string => {
+  let query = ""
+  for (const name of Object.keys(variations).sort()) {
+    query += `${query === "" ? "" : "&"}${encodeURIComponent(name)}=${encodeURIComponent(variations[name] ?? "")}`
+  }
+  return query
+}
+
+// A browser's agent took the default rule about 0.5 us to test, and agents repeat. The bounds keep a
+// client that sends a new agent per request from growing the map.
+const MAX_REMEMBERED_AGENT = 256
+const MAX_REMEMBERED_AGENTS = 1024
+const agentAnswers = new WeakMap<RegExp, Map<string, boolean>>()
+
+/** Whether `request` gets the blocking render under `options`. */
+export function wantsBlockingRender(options: ResolvedPprOptions, request: Request): boolean {
+  const rule = options.blockingFor
+  if (typeof rule === "function") return rule(request)
+  const agent = request.headers.get("user-agent")
+  if (agent === null) return false
+  if (agent.length > MAX_REMEMBERED_AGENT) return rule.test(agent)
+  let answers = agentAnswers.get(rule)
+  if (answers === undefined) {
+    answers = new Map()
+    agentAnswers.set(rule, answers)
+  }
+  let answer = answers.get(agent)
+  if (answer === undefined) {
+    if (answers.size >= MAX_REMEMBERED_AGENTS) answers.clear()
+    // No `g` or `y` flag (options refuse them), so a test reads no state and an answer holds.
+    answer = rule.test(agent)
+    answers.set(agent, answer)
+  }
+  return answer
+}