@nifrajs/web 5.5.1 → 5.6.0

package/src/internal/ppr/frames.ts

@@ -0,0 +1,170 @@
+import { validateComponentHTML } from "../../server-components/html.ts"
+import { serializeData } from "../render-document.ts"
+import { holeInvoker } from "./runtime.ts"
+
+/**
+ * A hole name: it becomes a DOM id, an attribute value, a hashed script and part of a renderer's id
+ * prefix, so it stays this narrow. No `--` and no trailing `-`: Svelte refuses an id prefix with `--`.
+ */
+export const HOLE_NAME: RegExp = /^(?=[a-z0-9-]{1,32}$)[a-z](?:-?[a-z0-9])*$/
+
+/** What one hole sends: its server HTML, plus props when it hydrates, or the record of the server
+ * component it shows, without that HTML. An error carries the error slot's HTML only, never the
+ * thrown message. */
+export type HoleOutcome =
+  | {
+      readonly html: string
+      readonly props?: unknown
+      readonly component?: unknown
+      readonly error?: undefined
+    }
+  | { readonly html: string; readonly error: true }
+
+/** A frame's JSON, as the runtime reads it to fill a host. */
+export type HoleFrameBody =
+  | {
+      readonly v: 1
+      readonly html: string
+      readonly props?: unknown
+      readonly component?: unknown
+      readonly error?: undefined
+    }
+  | { readonly v: 1; readonly html: string; readonly error: true }
+
+export const assertHoleName = (name: string): void => {
+  if (!HOLE_NAME.test(name)) {
+    throw new TypeError(
+      `[nifra/web] ppr: hole name "${name}" must match ${HOLE_NAME.source} (it becomes a DOM id and a hashed script)`,
+    )
+  }
+}
+
+/** Refuse hole HTML that could run script or escape its host, with the policy server
+ * components already enforce. Throws; the caller sends that hole's error frame instead. */
+export const validateHoleHtml = (html: string): void => validateComponentHTML(html)
+
+/**
+ * JSON safe inside a `<script>` element. Script data ends only at `</script`, and only `<!--` can
+ * move the tokenizer into its escaped states, so escaping `</` and `<!--` is enough; both escapes are
+ * plain JSON. Escaping every `<` and `>` instead, as `serializeData` does, made a 100 KB hole's frame
+ * 53% larger than its HTML; this makes it about 10% larger.
+ */
+const scriptJson = (value: unknown): string =>
+  JSON.stringify(value).replaceAll("</", "<\\/").replaceAll("<!--", "<\\u0021--")
+
+/**
+ * The bytes that fill hole `name`: an inert JSON frame and the constant invoker. No `</script>` or
+ * comment opener in the HTML or props survives into the element. Throws a `RangeError` when the
+ * encoded frame exceeds `maxBytes`.
+ */
+export function encodeHoleFrame(name: string, outcome: HoleOutcome, maxBytes: number): string {
+  const body: HoleFrameBody =
+    outcome.error === true
+      ? { v: 1, error: true, html: outcome.html }
+      : outcome.component !== undefined
+        ? { v: 1, html: outcome.html, component: outcome.component }
+        : outcome.props === undefined
+          ? { v: 1, html: outcome.html }
+          : { v: 1, html: outcome.html, props: outcome.props }
+  const frame = `<script type="application/json" id="nifra-ppr:${name}">${scriptJson(body)}</script><script>${holeInvoker(name)}</script>`
+  // UTF-8 needs at least one and at most three bytes per UTF-16 unit, so only a frame between the two
+  // bounds is encoded to measure it.
+  if (
+    frame.length > maxBytes ||
+    (frame.length * 3 > maxBytes && new TextEncoder().encode(frame).length > maxBytes)
+  ) {
+    throw new RangeError(`[nifra/web] ppr: hole "${name}" frame exceeds ${maxBytes} bytes`)
+  }
+  return frame
+}
+
+/**
+ * The JSON of a frame {@link encodeHoleFrame} wrote: what a data request sends to refill a host. The
+ * opening tag holds no `>` before its end, and the escaped JSON no `</script>`.
+ */
+export function frameBodyOf(frame: string): HoleFrameBody {
+  const start = frame.indexOf(">") + 1
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: encodeHoleFrame wrote this JSON from a HoleFrameBody.
+  return JSON.parse(frame.slice(start, frame.indexOf("</script>", start))) as HoleFrameBody
+}
+
+/**
+ * The per-response facts the runtime needs to send a cancel beacon. Inert JSON: never cached. `shared`
+ * names the holes whose frames serve every visitor, which the canary check scans with the shell.
+ */
+export const encodeRequestScript = (
+  cancelUrl: string,
+  token: string,
+  holes: readonly string[],
+  shared: readonly string[] = [],
+) =>
+  `<script type="application/json" id="nifra-ppr-req">${serializeData(shared.length === 0 ? { cancel: cancelUrl, token, holes } : { cancel: cancelUrl, token, holes, shared })}</script>`
+
+const TOKEN_KEY = '"token":"'
+
+/**
+ * {@link encodeRequestScript} before and after the token, so a route's script is serialized once and
+ * each response adds only its token. Holds for a base64url token, which serializing leaves as it is.
+ * An escaped JSON string never holds `"token":"` (each of its quotes follows a backslash), so the
+ * key found is the token's.
+ */
+export function requestScriptAround(
+  cancelUrl: string,
+  holes: readonly string[],
+  shared: readonly string[] = [],
+): readonly [string, string] {
+  const script = encodeRequestScript(cancelUrl, "", holes, shared)
+  const at = script.indexOf(TOKEN_KEY) + TOKEN_KEY.length
+  return [script.slice(0, at), script.slice(at)]
+}
+
+const HOST = 'data-nifra-hole="'
+
+/**
+ * Where {@link injectHoleFallbacks} puts each fallback, in document order. One pass over the shell
+ * finds every host: a search per hole, and another for its duplicate, read a large shell many times.
+ */
+export function holeFallbackInserts(
+  shell: string,
+  fallbacks: ReadonlyMap<string, string>,
+): Array<{ readonly at: number; readonly html: string }> {
+  // A declared hole's host, as the index after its name's closing quote; -1 once it has two.
+  const hosts = new Map<string, number>()
+  for (let at = shell.indexOf(HOST); at !== -1; at = shell.indexOf(HOST, at + HOST.length)) {
+    const end = shell.indexOf('"', at + HOST.length)
+    if (end === -1) break
+    const name = shell.slice(at + HOST.length, end)
+    if (fallbacks.has(name)) hosts.set(name, hosts.has(name) ? -1 : end + 1)
+  }
+  const inserts: Array<{ at: number; html: string }> = []
+  for (const [name, html] of fallbacks) {
+    const after = hosts.get(name)
+    if (after === undefined)
+      throw new TypeError(`[nifra/web] ppr: hole "${name}" has no host in the shell`)
+    if (after === -1) {
+      throw new TypeError(`[nifra/web] ppr: hole "${name}" has more than one host in the shell`)
+    }
+    const close = shell.indexOf(">", after)
+    if (close === -1 || !shell.startsWith("</", close + 1)) {
+      throw new TypeError(`[nifra/web] ppr: hole "${name}"'s host must render empty`)
+    }
+    inserts.push({ at: close + 1, html })
+  }
+  return inserts.sort((a, b) => a.at - b.at)
+}
+
+/**
+ * Put each hole's fallback HTML into its empty host in a rendered shell, once per shell build. Every
+ * declared hole must have exactly one host and that host must be empty: the adapter renders
+ * it opaque, so anything inside would be framework output the fill would destroy.
+ */
+export function injectHoleFallbacks(shell: string, fallbacks: ReadonlyMap<string, string>): string {
+  const inserts = holeFallbackInserts(shell, fallbacks)
+  let out = ""
+  let from = 0
+  for (const insert of inserts) {
+    out += shell.slice(from, insert.at) + insert.html
+    from = insert.at
+  }
+  return out + shell.slice(from)
+}

package/src/internal/ppr/integration.ts

@@ -0,0 +1,137 @@
+import { readBoundedBytes, TransportCodecError } from "@nifrajs/core/transport-codec"
+import type { CacheStore } from "../../isr.ts"
+import type { ShellCheckRecord } from "./compile-shell.ts"
+import {
+  PPR_CANCEL_PATH,
+  type PprEnvironment,
+  type PprIntegration,
+  PprShellCold,
+  PprShellUnavailable,
+  PprShellUnchecked,
+  variationQuery,
+  wantsBlockingRender,
+} from "./contract.ts"
+import type { ResolvedPprOptions } from "./options.ts"
+import { assertPprRoute, variationsOf } from "./route-rules.ts"
+import { createPprServer } from "./server.ts"
+import { digest, sharedShellStore } from "./shell-store.ts"
+
+// The stream sets its own type, caching and CSP; a middleware or gate header joins the rest.
+const OWN_HEADERS: ReadonlySet<string> = new Set([
+  "content-type",
+  "cache-control",
+  "content-security-policy",
+  "content-length",
+])
+
+const MAX_CANCEL_BYTES = 64
+
+/** Where shells are shared beyond the process, as `partialPrerendering` checked them. */
+export interface PprSharing {
+  readonly store: CacheStore | undefined
+  readonly storeSecret: string | undefined
+  readonly deployment: string | undefined
+}
+
+/**
+ * The deployment every shell key names. The client entry changes with each client build; each route's
+ * checked shell hash changes with its shell code, which the client entry does not see; the
+ * platform's own name, when given, covers the rest.
+ */
+export function shellDeployment(
+  clientEntry: string,
+  shellChecks: ShellCheckRecord | "unchecked-development",
+  named: string | undefined,
+): string {
+  if (shellChecks === "unchecked-development" && named === undefined) return clientEntry
+  const routes =
+    shellChecks === "unchecked-development"
+      ? ""
+      : Object.keys(shellChecks.routes)
+          .sort()
+          .map((id) => `${id}=${shellChecks.routes[id]}`)
+          .join(",")
+  return `${clientEntry}~${digest(`${routes}|${named ?? ""}`)}`
+}
+
+/** One app's partial prerendering, made when `createWebApp` reaches its `experimental.ppr`. */
+export function createPprIntegration(
+  options: ResolvedPprOptions,
+  shellChecks: ShellCheckRecord | "unchecked-development",
+  origin: string | undefined,
+  environment: PprEnvironment,
+  sharing: PprSharing = { store: undefined, storeSecret: undefined, deployment: undefined },
+): PprIntegration {
+  const { perRequestNonce, ...app } = environment
+  if (perRequestNonce) {
+    throw new TypeError(
+      "[nifra/web] experimental.ppr needs `csp: createCspPolicy(...)`, not `nonce`: a per-request nonce would make every shell unique",
+    )
+  }
+  const deployment = shellDeployment(app.deployment, shellChecks, sharing.deployment)
+  const server = createPprServer({
+    ...app,
+    deployment,
+    clientEntry: app.deployment,
+    options,
+    cancelUrl: PPR_CANCEL_PATH,
+    shellChecks,
+    shared:
+      sharing.store === undefined || sharing.storeSecret === undefined
+        ? undefined
+        : sharedShellStore(sharing.store, sharing.storeSecret, deployment),
+  })
+  const uncheckedWarned = new Set<string>()
+  return {
+    server,
+    // biome-ignore lint/plugin/noConditionalEmptyObjectSpread: an app with no configured origin has none, which shell meta reads as absent.
+    ...(origin === undefined ? {} : { origin }),
+    cancelPath: PPR_CANCEL_PATH,
+    // A beacon carries one 22-character token; anything longer is not one. The token is unguessable,
+    // so the answer is the same whether it named a live response or not.
+    async cancel(request) {
+      const length = Number(request.headers.get("content-length") ?? "NaN")
+      if (!(length > 0 && length <= MAX_CANCEL_BYTES)) return new Response(null, { status: 400 })
+      let token: Uint8Array
+      try {
+        // The header is a claim; the cap holds on the bytes that arrive.
+        token = await readBoundedBytes(new Response(request.body, { headers: request.headers }), {
+          maxBytes: MAX_CANCEL_BYTES,
+        })
+      } catch (error) {
+        if (error instanceof TransportCodecError) return new Response(null, { status: 400 })
+        throw error
+      }
+      server.cancel(new TextDecoder().decode(token))
+      return new Response(null, { status: 204 })
+    },
+    async stream(request, written) {
+      if (wantsBlockingRender(options, request.request)) return "settled"
+      let response: Response
+      try {
+        response = await server.respond(request)
+      } catch (error) {
+        if (!(error instanceof PprShellUnavailable)) throw error
+        if (error instanceof PprShellCold) return "deferred"
+        if (error instanceof PprShellUnchecked && !uncheckedWarned.has(request.routeId)) {
+          uncheckedWarned.add(request.routeId)
+          console.warn(error.message)
+        }
+        return "settled"
+      }
+      for (const [name, value] of Object.entries(written() ?? {}))
+        if (!OWN_HEADERS.has(name)) response.headers.set(name, value)
+      return response
+    },
+    shellData: (request, signal) =>
+      server
+        .shellData(request)
+        .catch((error: unknown) =>
+          error instanceof PprShellUnavailable ? request.loadShell(signal) : Promise.reject(error),
+        ),
+    variationQuery,
+    assertRoute: (route, layouts, boundaries) =>
+      assertPprRoute(route, layouts, boundaries, options),
+    variationsOf,
+  }
+}

package/src/internal/ppr/options.ts

@@ -0,0 +1,221 @@
+/**
+ * Partial prerendering limits and defaults. Internal while the feature is experimental: every
+ * number the plan names lives here once, so a deployment overrides it in one object and the request
+ * path reads the resolved copy rather than a scattered constant.
+ */
+
+/** Overrides for {@link PPR_DEFAULTS}. Every field is optional; an omitted one keeps its default. */
+export interface PprOptions {
+  /** A hole's deadline when its boundary sets no `timeout`. */
+  readonly holeTimeoutMs?: number
+  /** The largest `timeout` a boundary may set, and the cap on a route's total deadline. */
+  readonly maxHoleTimeoutMs?: number
+  /** Added to the largest hole timeout to give the route's total deadline. */
+  readonly totalDeadlineSlackMs?: number
+  /** Dynamic plus shared boundaries one PPR route may declare. */
+  readonly maxHolesPerRoute?: number
+  /** Shell entries one route may keep in the memory store. */
+  readonly shellEntriesPerRoute?: number
+  /**
+   * Bytes every shell entry in the memory store may hold together: its document, an estimate of the
+   * heap its loader data holds, and its key. An entry over the whole budget is served but not kept.
+   */
+  readonly shellStoreBytes?: number
+  /** How long a `notFound()` shell is cached. */
+  readonly notFoundTtlSeconds?: number
+  /** Shell builds one route may run at once; requests over it get the blocking render. */
+  readonly shellBuildConcurrency?: number
+  /**
+   * Once the store is full, requests one shell key must see before its shell is built and may push
+   * an older one out. The ones before stream the page whole, each hole as it settles, so a path
+   * visited once cannot evict a popular one. While the store has room, every key builds at once.
+   */
+  readonly shellAfterRequests?: number
+  /** A failing rebuild keeps serving the stale shell for `revalidate` times this... */
+  readonly staleOnErrorFactor?: number
+  /** ...but never longer than this. */
+  readonly maxStaleOnErrorSeconds?: number
+  /** Requests that get the blocking render instead of a stream: a user-agent pattern or a predicate. */
+  readonly blockingFor?: RegExp | ((request: Request) => boolean)
+  /** Abandoned invocations at which one boundary stops being admitted. */
+  readonly boundaryAbandonedTrip?: number
+  /** Abandoned invocations per process at which boundaries holding any stop being admitted. */
+  readonly processAbandonedTrip?: number
+  /** Abandoned invocations per process at which no hole is admitted. */
+  readonly admissionStop?: number
+  /** How long after its abort a still-pending invocation counts as abandoned. */
+  readonly abandonGraceMs?: number
+  /** PPR responses per process with hole loaders still running. */
+  readonly maxHoleWork?: number
+  /** How long after the total deadline an undrained stream is kept before it is aborted. */
+  readonly writeGraceMs?: number
+  /** Unsent bytes one response may queue. */
+  readonly maxUnsentBytesPerResponse?: number
+  /** Unsent bytes every PPR response in the process may queue together. */
+  readonly maxUnsentBytes?: number
+  /** Serialized size of one hole frame. */
+  readonly frameBytes?: number
+  /** The shell is padded to at least this many bytes; Safari holds back smaller first chunks. */
+  readonly minShellBytes?: number
+  /**
+   * When hole HTML is checked for script, handlers and other escapes before it is framed:
+   * `"always"`, or `"development"` only. The check costs about 20 us per KB of hole HTML; turn it off
+   * in production only when a strict CSP already blocks inline script.
+   */
+  readonly holeHtmlValidation?: "always" | "development"
+  /**
+   * Whether a page left with holes pending posts a cancel beacon, so their loaders stop before their
+   * deadline. Off by default on Cloudflare Workers, where the beacon reaches another isolate.
+   */
+  readonly cancelBeacon?: boolean
+  /**
+   * How long a process serves a shell or shared hole it wrote to or read from the shared store before
+   * reading it there again, so a purge another process made reaches this one. 0 reads it every time.
+   */
+  readonly sharedRecheckMs?: number
+}
+
+export type ResolvedPprOptions = {
+  readonly [K in keyof PprOptions]-?: Exclude<PprOptions[K], undefined>
+}
+
+/**
+ * Crawlers that read the document without running streamed scripts, so they get the blocking render.
+ * The same set Next.js treats as HTML-limited bots. Googlebot itself is absent on purpose: it renders
+ * JavaScript. `[\w-]-Google` matches what `[\w-]+-Google` does without backtracking at every position.
+ */
+export const HTML_LIMITED_BOTS: RegExp =
+  /[\w-]-Google|Google-[\w-]|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight/i
+
+const MB = 1024 * 1024
+
+export const PPR_DEFAULTS: ResolvedPprOptions = Object.freeze({
+  holeTimeoutMs: 5_000,
+  maxHoleTimeoutMs: 30_000,
+  totalDeadlineSlackMs: 1_000,
+  maxHolesPerRoute: 32,
+  shellEntriesPerRoute: 10_000,
+  shellStoreBytes: 64 * MB,
+  notFoundTtlSeconds: 60,
+  shellBuildConcurrency: 4,
+  shellAfterRequests: 2,
+  staleOnErrorFactor: 10,
+  maxStaleOnErrorSeconds: 86_400,
+  blockingFor: HTML_LIMITED_BOTS,
+  boundaryAbandonedTrip: 64,
+  processAbandonedTrip: 1_024,
+  admissionStop: 4_096,
+  abandonGraceMs: 100,
+  maxHoleWork: 1_024,
+  writeGraceMs: 5_000,
+  maxUnsentBytesPerResponse: MB,
+  maxUnsentBytes: 64 * MB,
+  frameBytes: 256 * 1024,
+  minShellBytes: 1_024,
+  holeHtmlValidation: "always",
+  cancelBeacon: true,
+  sharedRecheckMs: 1_000,
+})
+
+/**
+ * On Cloudflare Workers an isolate's memory is shared by everything it runs, and a beacon almost
+ * always reaches another isolate than the one running the holes.
+ */
+const WORKERS_DEFAULTS: Partial<ResolvedPprOptions> = Object.freeze({
+  shellStoreBytes: 8 * MB,
+  cancelBeacon: false,
+})
+
+const onWorkers = (): boolean => globalThis.navigator?.userAgent === "Cloudflare-Workers"
+
+type NumericKey = {
+  [K in keyof ResolvedPprOptions]: ResolvedPprOptions[K] extends number ? K : never
+}[keyof ResolvedPprOptions]
+
+const optionError = (message: string): TypeError => new TypeError(`[nifra/web] ppr: ${message}`)
+
+function assertOrdered(options: ResolvedPprOptions, smaller: NumericKey, larger: NumericKey): void {
+  if (options[smaller] > options[larger]) {
+    throw optionError(
+      `${smaller} (${options[smaller]}) must not exceed ${larger} (${options[larger]})`,
+    )
+  }
+}
+
+/** The latest request a shell may wait for; the canary check requests a path this many times. */
+export const MAX_SHELL_AFTER_REQUESTS = 8
+
+/**
+ * Merge `overrides` over {@link PPR_DEFAULTS} and check the result. Unknown keys, non-integers and
+ * limits that contradict each other throw at startup, never on a request.
+ */
+export function resolvePprOptions(overrides: PprOptions = {}): ResolvedPprOptions {
+  for (const key of Object.keys(overrides)) {
+    if (!Object.hasOwn(PPR_DEFAULTS, key)) throw optionError(`unknown option "${key}"`)
+  }
+  const defined = Object.fromEntries(
+    Object.entries(overrides).filter(([, value]) => value !== undefined),
+  )
+  const resolved: ResolvedPprOptions = {
+    ...PPR_DEFAULTS,
+    ...(onWorkers() ? WORKERS_DEFAULTS : undefined),
+    ...defined,
+  }
+  for (const [key, value] of Object.entries(resolved)) {
+    if (key === "blockingFor" || key === "holeHtmlValidation" || key === "cancelBeacon") continue
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+      throw optionError(`${key} must be a non-negative integer, got ${String(value)}`)
+    }
+  }
+  for (const key of [
+    "holeTimeoutMs",
+    "maxHolesPerRoute",
+    "shellBuildConcurrency",
+    "shellAfterRequests",
+    "boundaryAbandonedTrip",
+    "maxHoleWork",
+    "maxUnsentBytesPerResponse",
+    "frameBytes",
+  ] as const) {
+    if (resolved[key] === 0) throw optionError(`${key} must be at least 1`)
+  }
+  if (resolved.shellAfterRequests > MAX_SHELL_AFTER_REQUESTS) {
+    throw optionError(
+      `shellAfterRequests must be at most ${MAX_SHELL_AFTER_REQUESTS}, got ${resolved.shellAfterRequests}`,
+    )
+  }
+  const blockingFor = resolved.blockingFor
+  if (!(blockingFor instanceof RegExp) && typeof blockingFor !== "function") {
+    throw optionError("blockingFor must be a RegExp or a function of the request")
+  }
+  if (resolved.holeHtmlValidation !== "always" && resolved.holeHtmlValidation !== "development") {
+    throw optionError(
+      `holeHtmlValidation must be "always" or "development", got ${String(resolved.holeHtmlValidation)}`,
+    )
+  }
+  if (typeof resolved.cancelBeacon !== "boolean") {
+    throw optionError(`cancelBeacon must be a boolean, got ${String(resolved.cancelBeacon)}`)
+  }
+  // A global or sticky pattern keeps `lastIndex` between `test` calls, so one bot would alternate.
+  if (blockingFor instanceof RegExp && (blockingFor.global || blockingFor.sticky)) {
+    throw optionError("blockingFor must not use the g or y flag")
+  }
+  assertOrdered(resolved, "holeTimeoutMs", "maxHoleTimeoutMs")
+  assertOrdered(resolved, "boundaryAbandonedTrip", "processAbandonedTrip")
+  assertOrdered(resolved, "processAbandonedTrip", "admissionStop")
+  assertOrdered(resolved, "frameBytes", "maxUnsentBytesPerResponse")
+  assertOrdered(resolved, "maxUnsentBytesPerResponse", "maxUnsentBytes")
+  return Object.freeze(resolved)
+}
+
+/** A route's total deadline: its largest hole timeout plus the slack, capped. */
+export function totalDeadlineMs(
+  options: ResolvedPprOptions,
+  holeTimeouts: readonly number[],
+): number {
+  let largest = 0
+  for (const timeout of holeTimeouts) if (timeout > largest) largest = timeout
+  return Math.min(largest + options.totalDeadlineSlackMs, options.maxHoleTimeoutMs)
+}
+
+export { wantsBlockingRender } from "./contract.ts"

package/src/internal/ppr/route-rules.ts

@@ -0,0 +1,77 @@
+import type { BoundaryRegistration } from "../../boundary.ts"
+import type { RouteEntry, RouteModule } from "../../manifest.ts"
+import type { LoadedLayoutModules } from "../render-document.ts"
+import { isHole, serverHoleComponent } from "./contract.ts"
+import type { ResolvedPprOptions } from "./options.ts"
+
+/**
+ * The declared variations `search` selects. A parameter given twice, or a value outside its set,
+ * selects nothing, so every spelling of one choice maps to one shell.
+ */
+export function variationsOf(
+  declared: RouteModule["shellVariations"],
+  search: string,
+): Readonly<Record<string, string>> {
+  const lists = declared?.search
+  if (lists === undefined || search === "") return {}
+  const query = new URLSearchParams(search)
+  const chosen: Record<string, string> = {}
+  for (const [name, allowed] of Object.entries(lists)) {
+    const values = query.getAll(name)
+    const value = values[0]
+    if (values.length === 1 && value !== undefined && allowed.includes(value)) chosen[name] = value
+  }
+  return chosen
+}
+
+/** The PPR eligibility rules a route's own files cannot check: its layouts and boundary modes. */
+export function assertPprRoute(
+  route: RouteEntry,
+  layouts: LoadedLayoutModules,
+  boundaries: readonly BoundaryRegistration[],
+  limits: ResolvedPprOptions,
+): void {
+  // `compileShells` refuses the same chain at startup; this catches a record made from other files.
+  layouts.forEach((layout, index) => {
+    if (layout.loader !== undefined && layout.gate !== true) {
+      throw new Error(
+        `[nifra/web] ppr: route "${route.id}" has a shellLoader, but its layout "${route.layoutIds[index]}" has a loader that is not a gate. A layout loader reads the request, so its output cannot be in a shared shell`,
+      )
+    }
+  })
+  let holes = 0
+  for (const boundary of boundaries) {
+    if (typeof boundary.mode === "object") {
+      throw new Error(
+        `[nifra/web] ppr: route "${route.id}" has a shellLoader and an intercepting boundary "${boundary.name}", which partial prerendering does not support yet`,
+      )
+    }
+    if (!isHole(boundary)) continue
+    holes++
+    if (typeof boundary.load !== "function") {
+      throw new Error(
+        `[nifra/web] ppr: boundary "${boundary.name}" of route "${route.id}" has no boundaryLoaders entry; a hole is filled from its own loader`,
+      )
+    }
+    if (
+      serverHoleComponent(boundary.render) !== undefined &&
+      (boundary.mode !== "dynamic" || boundary.interactive === true)
+    ) {
+      throw new Error(
+        `[nifra/web] ppr: boundary "${boundary.name}" of route "${route.id}" shows a server component, so it must be a dynamic hole that is not interactive: the component runs for each visitor, and its client islands hydrate`,
+      )
+    }
+    const { timeout } = boundary
+    const max = limits.maxHoleTimeoutMs
+    if (timeout !== undefined && !(Number.isInteger(timeout) && timeout >= 1 && timeout <= max)) {
+      throw new RangeError(
+        `[nifra/web] ppr: boundary "${boundary.name}" of route "${route.id}" has timeout ${String(timeout)}; it must be a whole number of milliseconds from 1 to ${max}`,
+      )
+    }
+  }
+  if (holes === 0 || holes > limits.maxHolesPerRoute) {
+    throw new RangeError(
+      `[nifra/web] ppr: route "${route.id}" has a shellLoader and ${holes} dynamic or shared boundaries; it needs 1 to ${limits.maxHolesPerRoute}. A page with no per-visitor or fast-changing part needs no shell: prerender it or give it \`revalidate\``,
+    )
+  }
+}

package/src/internal/ppr/runtime.ts

@@ -0,0 +1,36 @@
+import { hashSource } from "../../csp.ts"
+
+/**
+ * The PPR client runtime: one inline script in the shell, constant per release, listed in the CSP by
+ * hash. It fills each hole host from that hole's inert JSON frame, keeps interactive holes' props for
+ * the adapter, with a server component's record and HTML for the islands inside it, and on leaving
+ * the route sends the response's cancel token. `put` is how an adapter refills a host from a data
+ * request's fill, through the same sink; it writes only into a host of the hole it names, so the
+ * global cannot carry a string into any other element under the policy.
+ *
+ * `__nifraPpr(name)` is the only entry point a frame calls, so every invoker is constant per hole name
+ * and hashable at build. Hole HTML goes in through `innerHTML`, where a `<script>` never runs, under a
+ * Trusted Types policy named `nifra-ppr` when the browser has the API. The server has validated that
+ * HTML before framing it; the policy only names the one sink.
+ */
+export const PPR_RUNTIME =
+  '(()=>{var w=window,d=document,h={},s={},dead=0,p;var pol=function(){if(!p){try{p=w.trustedTypes?w.trustedTypes.createPolicy("nifra-ppr",{createHTML:function(x){return x}}):null}catch(_){}p=p||{createHTML:function(x){return x}}}return p};var ap=function(t,n,v){t.innerHTML=pol().createHTML(typeof v.html==="string"?v.html:"");t.setAttribute("data-nifra-filled","");t.setAttribute("aria-busy","false");if(v.error)t.setAttribute("data-nifra-hole-error","");else t.removeAttribute("data-nifra-hole-error");var o={props:v.props,error:!!v.error};if(v.component){o.component=v.component;o.html=v.html}h[n]=o;return o};var f=function(n){if(dead)return;var e=d.getElementById("nifra-ppr:"+n);if(!e)return;var v;try{v=JSON.parse(e.textContent)}catch(_){return}e.remove();var t=d.querySelector(\'[data-nifra-hole="\'+n+\'"]\');if(!t||t.hasAttribute("data-nifra-filled"))return;var o=ap(t,n,v);(s[n]||[]).slice().forEach(function(c){c(o)})};f.put=function(n,v,t){if(v&&typeof v==="object"&&t&&t.getAttribute&&t.getAttribute("data-nifra-hole")===n)ap(t,n,v)};f.get=function(n){return h[n]};f.subscribe=function(n,c){(s[n]||(s[n]=[])).push(c);return function(){s[n]=(s[n]||[]).filter(function(x){return x!==c})}};f.leave=function(){if(dead)return;dead=1;s={};var r=d.getElementById("nifra-ppr-req");if(!r)return;var q;try{q=JSON.parse(r.textContent)}catch(_){return}if(q.cancel&&q.holes.some(function(n){return!h[n]})&&navigator.sendBeacon)navigator.sendBeacon(q.cancel,q.token)};f.dead=function(){return!!dead};f.boot=function(){var c=d.currentScript,e=c&&c.previousElementSibling;if(e&&e.rel==="modulepreload"&&e.href)import(e.href)};w.__nifraPpr=f})()'
+
+/**
+ * What loads each module script of a shell, after a `<link rel="modulepreload">` naming it. WebKit
+ * evaluates a module script, `async` or not, only once the parser finishes, which on a streamed page
+ * is after the slowest hole, and a dynamic import of the same URL waits with it. A dynamic import
+ * from a classic script with no such element evaluates at once in every engine.
+ */
+export const PPR_BOOT = "__nifraPpr.boot()"
+
+/** The script a frame runs to fill hole `name`. Constant per name, so it is listed by hash. */
+export const holeInvoker = (name: string): string => `__nifraPpr(${JSON.stringify(name)})`
+
+/**
+ * The `script-src` hash sources a PPR route needs: the runtime, the boot call and one invoker per hole. Computed once
+ * per route at startup, never per request.
+ */
+export async function pprScriptHashes(holeNames: readonly string[]): Promise<readonly string[]> {
+  return Promise.all([PPR_RUNTIME, PPR_BOOT, ...holeNames.map(holeInvoker)].map(hashSource))
+}