@nifrajs/web 3.5.0 → 4.0.0

package/src/bun-dev-entry.ts

@@ -3,7 +3,7 @@
  *
  * ## Why this file exists at all
  *
- * Bun's dev server bundles an HTML route and rewrites its `<script src="./entry.tsx">` into a
+ * Bun's dev server bundles an HTML route and rewrites its `<script src="./nifra-dev-entry.tsx">` into a
  * content-hashed URL under `/_bun/client/`. That rewrite is the whole point: the hash changes per build,
  * so the URL cannot be predicted or hard-coded.
  *

package/src/cdn.ts

@@ -0,0 +1,216 @@
+/**
+ * `@nifrajs/web/cdn` - put a CDN in front of nifra pages and purge it by tag.
+ *
+ * `withCdn` wraps the app (or a `withISR` handler) and, on every page a shared cache may store, sets
+ * the CDN's tag and TTL headers: the route's `revalidateTags` plus a tag for the page's own path, and
+ * the route's `revalidate` as the CDN's freshness. Browsers get `max-age=0, must-revalidate`, because
+ * a purge reaches the CDN, never a browser. Every other HTML response is marked no-store for the CDN.
+ * `revalidateEndpoint({ cdn })` and `createInvalidator` purge the origin store first, then the CDN.
+ *
+ * Providers: Cloudflare (a proxied zone, or Workers Cache), Vercel and Fastly; `defineCdnProvider`
+ * for any other. Backend-only: a browser build that reaches this module fails.
+ */
+import "@nifrajs/web/backend-only"
+import { isDraftEnabled } from "./draft.ts"
+import type { CdnProvider } from "./internal/cdn/core.ts"
+import { pathTag } from "./internal/cdn/core.ts"
+import {
+  type CacheStore,
+  type CdnPurgeOutcome,
+  type CdnPurgeTarget,
+  ISR_REVALIDATE_HEADER,
+  ISR_REVALIDATE_TAGS_HEADER,
+  type ISRApp,
+  type ISRPlatform,
+  type ISRQuery,
+  isCacheablePage,
+  MAX_REVALIDATE_PATHS,
+  MAX_REVALIDATE_TAGS,
+  normalizeTags,
+  openCacheChannel,
+  tagsFromHeader,
+  urlKeyOf,
+  withoutCacheChannel,
+} from "./isr.ts"
+
+export {
+  type CloudflareWorkersCacheOptions,
+  type CloudflareZoneOptions,
+  cloudflareWorkersCache,
+  cloudflareZone,
+  type WorkersCacheLike,
+} from "./internal/cdn/cloudflare.ts"
+export {
+  type CdnCacheInput,
+  type CdnProvider,
+  type CdnProviderDefinition,
+  type CdnPurgeError,
+  defineCdnProvider,
+  type PurgeAttempt,
+  type PurgeQueueOptions,
+  pathTag,
+} from "./internal/cdn/core.ts"
+export { type FastlyOptions, fastly } from "./internal/cdn/fastly.ts"
+export { type VercelOptions, vercel } from "./internal/cdn/vercel.ts"
+export type { CdnPurgeOutcome, CdnPurgeTarget }
+
+/** What browsers are told about a page the CDN may store: revalidate every time. */
+export const CDN_BROWSER_CACHE_CONTROL = "public, max-age=0, must-revalidate"
+
+type Handler = (req: Request, platform?: ISRPlatform) => Response | Promise<Response>
+
+export interface WithCdnOptions {
+  readonly provider: CdnProvider
+  /**
+   * Seconds the CDN may keep serving a page past its freshness while it refetches. Default: the page's
+   * own freshness window. With `withISR` underneath, a page can be this much older than ISR's own.
+   */
+  readonly staleWhileRevalidate?: number
+  /** Seconds the CDN may serve a page past its freshness while the origin errors. Default: unset. */
+  readonly staleIfError?: number
+  /** The draft secret given to `createWebApp`: a draft render is never stored by the CDN. */
+  readonly draftSecret?: string
+}
+
+const nonNegative = (value: number | undefined, name: string): number | undefined => {
+  if (value === undefined) return undefined
+  if (!Number.isInteger(value) || value < 0) {
+    throw new RangeError(`[nifra/web/cdn] ${name} must be a non-negative integer number of seconds`)
+  }
+  return value
+}
+
+const isHtml = (res: Response): boolean =>
+  (res.headers.get("content-type") ?? "").toLowerCase().includes("text/html")
+
+function withHeaders(res: Response, set: Readonly<Record<string, string>>): Response {
+  try {
+    for (const [name, value] of Object.entries(set)) res.headers.set(name, value)
+    return res
+  } catch {
+    // A `fetch()` response has immutable headers: rebuild it around the same body instead.
+    const headers = new Headers(res.headers)
+    for (const [name, value] of Object.entries(set)) headers.set(name, value)
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+  }
+}
+
+/**
+ * Wrap `app` (a `createWebApp` app or a `withISR` handler) so a CDN stores exactly the pages a shared
+ * cache may serve to anyone, tagged for purging, for as long as the route's `revalidate` allows.
+ * Non-HTML responses (assets, JSON, navigation data) pass through with the app's own headers.
+ */
+export function withCdn(
+  app: ISRApp | Handler,
+  options: WithCdnOptions,
+): (req: Request, platform?: ISRPlatform) => Promise<Response> {
+  const { provider, draftSecret } = options
+  const swr = nonNegative(options.staleWhileRevalidate, "staleWhileRevalidate")
+  const staleIfError = nonNegative(options.staleIfError, "staleIfError")
+  openCacheChannel(app)
+  const fetchOf: Handler =
+    typeof app === "function" ? app : (req, platform) => app.fetch(req, platform)
+  return async (req, platform) => {
+    const res = await fetchOf(req, platform)
+    const advertised = res.headers.get(ISR_REVALIDATE_HEADER)
+    const tags = tagsFromHeader(res.headers.get(ISR_REVALIDATE_TAGS_HEADER))
+    const out = withoutCacheChannel(res)
+    if (!isHtml(out)) return out
+    const seconds = advertised === null ? Number.NaN : Math.floor(Number(advertised))
+    const storable =
+      Number.isFinite(seconds) &&
+      seconds > 0 &&
+      isCacheablePage(req, out) &&
+      !(draftSecret !== undefined && (await isDraftEnabled(req, draftSecret)))
+    if (!storable) return withHeaders(out, provider.noStoreHeaders())
+    const pageTags = [...tags, await pathTag(new URL(req.url).pathname)]
+    return withHeaders(out, {
+      ...provider.cacheHeaders({
+        tags: pageTags.slice(-provider.maxResponseTags),
+        maxAge: seconds,
+        staleWhileRevalidate: swr ?? seconds,
+        staleIfError,
+      }),
+      "cache-control": CDN_BROWSER_CACHE_CONTROL,
+    })
+  }
+}
+
+export interface InvalidatorOptions {
+  /** The ISR store to purge first. */
+  readonly store?: CacheStore
+  /** The CDN to purge after the store. */
+  readonly cdn?: CdnPurgeTarget
+  /**
+   * The site's public origin (`https://example.com`), for the store keys of purged paths under
+   * `withISR`'s default key. Not needed with `key`, or without a store.
+   */
+  readonly origin?: string
+  /** A store key for a path; must match the `withISR` `key`. Return `null` for a path never cached. */
+  readonly key?: (path: string) => string | null
+  /** The `query` policy given to `withISR`. Default `"bypass"`. Ignored with `key`. */
+  readonly query?: ISRQuery
+}
+
+export interface InvalidateResult {
+  readonly origin: "done" | "skipped"
+  readonly cdn: CdnPurgeOutcome["cdn"] | "skipped"
+  readonly retryable: boolean
+  readonly error?: string
+}
+
+/**
+ * Purge pages after a mutation, from app code: `await invalidate({ tags: ["product:42"] })`. The
+ * origin store goes first, so a CDN refetch cannot repopulate from a stale origin entry. At most 32
+ * tags and 100 paths a call.
+ */
+export function createInvalidator(options: InvalidatorOptions): {
+  invalidate(
+    target: { readonly tags?: readonly string[]; readonly paths?: readonly string[] },
+    platform?: ISRPlatform,
+  ): Promise<InvalidateResult>
+} {
+  const { store, cdn } = options
+  let keyOf: ((path: string) => string | null) | undefined = options.key
+  if (keyOf === undefined && store !== undefined) {
+    if (options.origin === undefined) {
+      throw new TypeError(
+        "[nifra/web/cdn] createInvalidator: a store needs `origin` (or `key`) to find a path's entry",
+      )
+    }
+    const origin = new URL(options.origin).origin
+    const urlKey = urlKeyOf(options.query)
+    keyOf = (path) => urlKey(new URL(origin + path))
+  }
+  return {
+    async invalidate(target, platform) {
+      const tags = normalizeTags(target.tags ?? [])
+      const paths = [...new Set(target.paths ?? [])]
+      if (tags.length > MAX_REVALIDATE_TAGS || paths.length > MAX_REVALIDATE_PATHS) {
+        throw new RangeError(
+          "[nifra/web/cdn] invalidate takes at most 32 tags and 100 paths a call",
+        )
+      }
+      for (const path of paths) {
+        if (typeof path !== "string" || !path.startsWith("/")) {
+          throw new TypeError("[nifra/web/cdn] invalidate paths must start with /")
+        }
+      }
+      let origin: InvalidateResult["origin"] = "skipped"
+      if (store !== undefined) {
+        if (tags.length > 0 && store.invalidateTag === undefined) {
+          throw new TypeError("[nifra/web/cdn] this store cannot invalidate by tag")
+        }
+        for (const path of paths) {
+          const key = keyOf?.(path)
+          if (key !== null && key !== undefined) await store.delete(key)
+        }
+        for (const tag of tags) await store.invalidateTag?.(tag)
+        origin = "done"
+      }
+      if (cdn === undefined) return { origin, cdn: "skipped", retryable: false }
+      const outcome = await cdn.purge({ tags, paths }, platform)
+      return { origin, ...outcome }
+    },
+  }
+}

package/src/client.ts

@@ -18,7 +18,20 @@ import {
   setBlockerController,
   setBrowserNavigate,
 } from "./navigation.ts"
-import type { ClientRouter } from "./router.ts"
+import { type ClientRouter, redirectOf } from "./router.ts"
+
+/** Read the nonce carried by the current server-rendered document, if any. */
+export function currentDocumentNonce(): string | undefined {
+  if (typeof document === "undefined") return undefined
+  const documentLike = document as unknown as {
+    querySelector?: (selector: string) => Element | null
+  }
+  const script = documentLike.querySelector?.("script[nonce]")
+  if (script === null || script === undefined) return undefined
+  const property = (script as Element & { readonly nonce?: unknown }).nonce
+  if (typeof property === "string" && property !== "") return property
+  return script.getAttribute("nonce") ?? undefined
+}
 
 /**
  * Everything the generated client entry needs, re-exported here so that entry imports ONE module and
@@ -220,6 +233,8 @@ export function installHistory(
   let index = (history.state as { nifraIndex?: number } | null)?.nifraIndex ?? 0
   let here = location.pathname + location.search + (location.hash ?? "")
   let reversing = false
+  // The path the router was last seen loading, so a redirect it follows shows up as a change.
+  let expected: string | undefined
   type Registration = {
     readonly shouldBlock: BlockerFunction
     readonly emit: (blocker: Blocker) => void
@@ -355,11 +370,20 @@ export function installHistory(
       pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
     }
     here = url.pathname + url.search + url.hash
+    expected = routePath
     // The data layer fetches by path+search; the #hash is client-only (never sent to the server).
-    transition(() => router.navigate(routePath).catch(() => fallback(path)))
+    transition(() => router.navigate(routePath).catch((error) => leave(error, path)))
     settle()
   }
 
+  // A redirect out of the app replaces the entry it answered, as the browser's own redirect would; any
+  // other failure loads the page as a document.
+  const leave = (error: unknown, path: string): void => {
+    const to = redirectOf(error)
+    if (to === undefined) fallback(path)
+    else location.replace(to)
+  }
+
   const go = (path: string, mode: "push" | "replace", state?: unknown): void => {
     // Validate before the blocker observes the target. A blocker receives parsed locations, so letting a
     // malformed string reach `locationOf` would make an otherwise no-throw navigate unexpectedly throw.
@@ -384,7 +408,7 @@ export function installHistory(
     }
     go(to, navOptions?.replace === true ? "replace" : "push", navOptions?.state)
   }
-  setBrowserNavigate(navigate)
+  setBrowserNavigate(navigate, router)
 
   // Publish the guard registry through the DOM-free bridge (`@nifrajs/web`'s `registerBlocker`, which an
   // adapter's `useBlocker` calls). One slot, latest registration wins; the unregister clears it only if
@@ -431,12 +455,45 @@ export function installHistory(
     go(href, "push")
   }
 
-  // Hover/focus an in-app link → warm its chunk + data (the store dedupes the spam).
-  const onPrefetch = (event: Event): void => {
-    const href = inAppHref(event.target)
+  // `data-nifra-prefetch` on a link or any ancestor (the nearest wins) says when the link warms its
+  // route's chunk and data: `intent` (the default) on hover or focus, `viewport` once it scrolls into
+  // view, `render` as soon as a page shows it, `none` never.
+  const prefetchModeOf = (el: Element): string | undefined =>
+    (el.closest("[data-nifra-prefetch]") as HTMLElement | null)?.dataset.nifraPrefetch
+
+  // Warm an in-app link's route (the store dedupes the spam). The page on screen has nothing to warm.
+  const warm = (target: EventTarget | null): void => {
+    const href = inAppHref(target)
     if (href === null) return
     const url = new URL(href, location.origin)
-    void router.prefetch(url.pathname + url.search) // warm by path+search; the #hash isn't data
+    const path = url.pathname + url.search // the #hash isn't data
+    if (path !== location.pathname + location.search) void router.prefetch(path)
+  }
+
+  const onPrefetch = (event: Event): void => {
+    const target = event.target
+    if (target instanceof Element && prefetchModeOf(target) !== "none") warm(target)
+  }
+
+  // `viewport` and `render` links are looked for when history is installed (the server-rendered page)
+  // and whenever the router settles (a navigation, a submit's revalidation). A link the page adds in
+  // between warms on intent until the next settle.
+  let inView: IntersectionObserver | undefined
+  const scan = (): void => {
+    inView?.disconnect()
+    for (const anchor of document.querySelectorAll(
+      "a[data-nifra-prefetch],[data-nifra-prefetch] a",
+    )) {
+      const mode = prefetchModeOf(anchor)
+      if (mode === "render") warm(anchor)
+      else if (mode === "viewport") {
+        // Scrolling back into view asks again; the store holds a fresh prefetch, so nothing refetches.
+        inView ??= new IntersectionObserver((entries) => {
+          for (const entry of entries) if (entry.isIntersecting) warm(entry.target)
+        })
+        inView.observe(anchor)
+      }
+    }
   }
 
   // Back/forward: the entry already exists (no push). The URL has ALSO already changed - a popstate can't
@@ -460,9 +517,9 @@ export function installHistory(
     index = newIndex
     here = dest
     pendingScroll = { pos: scrollOf(history.state) }
-    transition(() =>
-      router.navigate(location.pathname + location.search).catch(() => fallback(location.pathname)),
-    )
+    const routePath = location.pathname + location.search
+    expected = routePath
+    transition(() => router.navigate(routePath).catch((error) => leave(error, dest)))
     settle()
   }
 
@@ -484,24 +541,50 @@ export function installHistory(
     event.returnValue = ""
   }
 
+  // The router is loading a page the address bar does not show: a redirect it follows. That replaces the
+  // entry a navigation pushed, or adds one after a form post, as the browser would. A redirect from a
+  // form post back to the page it was on adds nothing.
+  const follow = (path: string): void => {
+    if (path !== location.pathname + location.search) {
+      if (expected === undefined) {
+        history.replaceState({ ...(history.state ?? {}), nifraScroll: [scrollX, scrollY] }, "")
+        index += 1
+        history.pushState({ nifraIndex: index }, "", path)
+      } else {
+        history.replaceState(history.state, "", path + location.hash)
+      }
+      here = location.pathname + location.search + location.hash
+      pendingScroll = location.hash !== "" ? { hash: hashId(location.hash) } : { pos: [0, 0] }
+    }
+    expected = path
+  }
+
   // After a navigation settles (content rendered), apply the pending scroll target on the next frame:
   // a fragment's element for a cross-page `#hash`, the saved position for back/forward, else the top.
-  // Skipped for submits (pending).
-  const restoreScroll = (): void => {
-    if (router.snapshot().pending || pendingScroll === null) return
+  // A settle with no navigation (a submit's revalidation) scrolls nothing. Either way the rendered
+  // page is then scanned for links to warm.
+  const settled = (): void => {
+    const { pending, pendingPath } = router.snapshot()
+    if (pending) {
+      if (pendingPath !== undefined && pendingPath !== expected) follow(pendingPath)
+      return
+    }
+    expected = undefined
     const target = pendingScroll
     pendingScroll = null
     requestAnimationFrame(() => {
-      if ("hash" in target) {
+      if (target !== null && "hash" in target) {
         const el = findAnchor(target.hash)
         if (el !== null) el.scrollIntoView()
         else window.scrollTo(0, 0) // fragment not found → top, like a fresh page load
-      } else {
+      } else if (target !== null) {
         window.scrollTo(target.pos[0], target.pos[1])
       }
+      scan()
     })
   }
-  const unsubscribe = router.subscribe(restoreScroll)
+  const unsubscribe = router.subscribe(settled)
+  scan()
 
   document.addEventListener("click", onClick)
   document.addEventListener("pointerover", onPrefetch)
@@ -510,6 +593,7 @@ export function installHistory(
   window.addEventListener("beforeunload", onBeforeUnload)
   return () => {
     unsubscribe()
+    inView?.disconnect()
     setBrowserNavigate(undefined) // stop routing `useNavigate` to a torn-down router
     setBlockerController(undefined) // stop routing `useBlocker` to a torn-down registry
     document.removeEventListener("click", onClick)
@@ -532,6 +616,7 @@ export function installHistory(
  * the first navigation cleanly takes over from the server-rendered head.
  */
 export function applyHead(head: Meta): void {
+  const documentNonce = currentDocumentNonce()
   if (head.title !== undefined) document.title = head.title
   // `<html lang>`/`<html dir>` - applied AUTHORITATIVELY (unlike `title`, which is left alone when the
   // route omits it), mirroring the SSR shell's defaulting exactly: `lang` falls back to `"en"`, `dir` is
@@ -584,6 +669,11 @@ export function applyHead(head: Meta): void {
         `[nifra/web] unsupported executable script type ${JSON.stringify(s.type)}`,
       )
     }
+    if (documentNonce !== undefined && s.nonce !== documentNonce) {
+      throw new TypeError(
+        "[nifra/web] executable head scripts must use the same CSP nonce as the document",
+      )
+    }
     const el = document.createElement("script")
     el.setAttribute("type", s.type)
     el.setAttribute("nonce", s.nonce)
@@ -606,8 +696,11 @@ export function installForms(router: ClientRouter): () => void {
     // `data-nifra-revalidate="false"` opts out of the post-action loader revalidation (the action's
     // actionData drives the update); absent or any other value keeps the default revalidation.
     const revalidate = form.dataset.nifraRevalidate !== "false"
-    router.submit(url.pathname + url.search, new FormData(form), { revalidate }).catch(() => {
-      form.submit() // data submit failed - fall back to a full-page POST
+    router.submit(url.pathname + url.search, new FormData(form), { revalidate }).catch((error) => {
+      const to = redirectOf(error)
+      // The action ran: load the page that shows its result rather than run it again.
+      if (to !== undefined) location.assign(to)
+      else form.submit() // data submit failed - fall back to a full-page POST
     })
   }
   document.addEventListener("submit", onSubmit)

package/src/conformance.ts

@@ -88,9 +88,10 @@ const readHtml = async (
  * Execute the observable {@link RenderAdapter} interface against a framework-specific fixture.
  *
  * The promise resolves only when the adapter proves all shared invariants: page props reach a
- * page-only render, streams contain byte chunks, layout chains nest outermost-first, optional
- * buffered rendering is byte-for-byte hydration-equivalent to streaming for non-deferred content,
- * and hydration-head output is a stable string. It rejects with
+ * page-only render, streams contain byte chunks, layout chains nest outermost-first, a leaf that
+ * renders nothing leaves its layouts standing, optional buffered rendering is byte-for-byte
+ * hydration-equivalent to streaming for non-deferred content, and hydration-head output is a stable
+ * string. It rejects with
  * {@link RenderAdapterConformanceError} naming the first failed check.
  *
  * Framework semantics outside the interface-Suspense scheduling, compiler plugins, DOM hydration,
@@ -125,6 +126,18 @@ export async function assertRenderAdapterConformance(
     fail("layout order", "expected outer layout → inner layout → page source order")
   }
 
+  // The page slot of an `ssr = false` route with no `HydrateFallback`: a plain function returning
+  // `null`, in every framework. The layouts must render around it and the slot must be empty.
+  const emptyHtml = await readHtml(
+    () => adapter.renderToStream([outerLayout, innerLayout, () => null], props),
+    "empty leaf",
+  )
+  contains(emptyHtml, markers.outer, "empty leaf")
+  contains(emptyHtml, markers.inner, "empty leaf")
+  if (emptyHtml.includes(markers.page)) {
+    fail("empty leaf", "a leaf that renders nothing must leave the page slot empty")
+  }
+
   if (adapter.renderToString !== undefined) {
     let buffered: unknown
     try {

package/src/csp.ts

@@ -0,0 +1,194 @@
+import { PRE_HYDRATION_GUARD } from "./internal/runtime-contract.ts"
+import { createNonceResolver, type NonceResolver } from "./nonce.ts"
+import type { RenderAdapter } from "./render-seam.ts"
+
+/** What {@link CreateCspPolicyOptions.header} receives for one document. */
+export interface CspHeaderContext {
+  /**
+   * The `script-src` sources this document needs, space-separated: a `'sha256-…'` hash for each
+   * constant inline script nifra writes, plus `'nonce-…'` when the document carries a script that is
+   * specific to this request. External scripts (the client entry, route chunks, islands) are not
+   * listed: allow their origin, usually `'self'`.
+   */
+  readonly sources: string
+  /** The nonce, when this document carries one. Such a document is `private, no-store`. */
+  readonly nonce?: string
+}
+
+export interface CreateCspPolicyOptions {
+  /**
+   * Build the complete Content-Security-Policy value for one document, or `undefined` to send none:
+   *
+   * ```ts
+   * header: ({ sources }) => `default-src 'self'; script-src 'self' ${sources}; object-src 'none'`
+   * ```
+   */
+  readonly header: (context: CspHeaderContext) => string | undefined
+  /** Generate the nonce for a document that needs one. Default: 122 random bits, CSP base64-safe. */
+  readonly generate?: () => string
+}
+
+const CSP_POLICY: unique symbol = Symbol.for("nifra.web.cspPolicy")
+
+/** How a `createWebApp` app's documents meet a CSP: `"nonce"` (every document carries one, so none is
+ * cacheable) or `"hash"` (a {@link CspPolicy}). Read by wrappers that cache documents. */
+export const DOCUMENT_POLICY: unique symbol = Symbol.for("nifra.web.documentPolicy")
+
+/** The hash sources for one adapter, and the hydration head they were computed from. */
+interface AdapterSources {
+  readonly head: string
+  readonly sources: string
+}
+
+interface CspPolicyState {
+  readonly header: (context: CspHeaderContext) => string | undefined
+  readonly generate: () => string
+  readonly adapters: WeakMap<RenderAdapter, AdapterSources | Promise<AdapterSources>>
+}
+
+/**
+ * A hash-based Content-Security-Policy for nifra documents - see {@link createCspPolicy}. Opaque: pass
+ * it to `createWebApp({ csp })` or `renderPage({ csp })`.
+ */
+export interface CspPolicy {
+  readonly [CSP_POLICY]: CspPolicyState
+}
+
+/**
+ * Create a hash-based Content-Security-Policy for nifra documents, so a page can carry a strict CSP
+ * and still be cached.
+ *
+ * A per-request nonce makes every document unique: nifra marks a nonce-bearing document
+ * `private, no-store`, so no shared cache (ISR, a CDN) may store it. Under this policy a document
+ * gets a nonce only when it carries a script specific to this request: a page that `defer()`s streams
+ * one per settled value, and `unsafeInlineScript` names the nonce. Every other document is nonce-free.
+ * Its inline scripts are the constant ones nifra writes, listed by hash, so the CSP header is the
+ * same on every request and the page stays cacheable. Page data rides in an inert JSON script, which
+ * a CSP does not govern.
+ *
+ * ```ts
+ * const csp = createCspPolicy({
+ *   header: ({ sources }) => `default-src 'self'; script-src 'self' ${sources}; object-src 'none'`,
+ * })
+ * const app = createWebApp({ adapter, manifest, clientEntry, csp })
+ * ```
+ */
+export function createCspPolicy(options: CreateCspPolicyOptions): CspPolicy {
+  if (typeof options?.header !== "function") {
+    throw new TypeError("[nifra/web] createCspPolicy requires a header function")
+  }
+  return {
+    [CSP_POLICY]: {
+      header: options.header,
+      // A UUID's hyphens are outside the CSP base64-value grammar; the remaining 122 random bits are
+      // plenty for a per-response nonce, on every fetch runtime.
+      generate: options.generate ?? (() => crypto.randomUUID().replaceAll("-", "")),
+      adapters: new WeakMap(),
+    },
+  }
+}
+
+/** True for a value made by {@link createCspPolicy}. */
+export const isCspPolicy = (value: unknown): value is CspPolicy =>
+  typeof value === "object" && value !== null && CSP_POLICY in value
+
+// A closing tag ends at any space, slash or `>` after its name, as a browser reads it.
+const INLINE_SCRIPT = /<script\b([^>]*)>([\s\S]*?)<\/script(?=[\s/>])[^>]*>/gi
+
+/** The bodies of the executable inline scripts in a fragment of markup (no `src`, no inert type). */
+const inlineScriptBodies = (html: string): string[] => {
+  const bodies: string[] = []
+  for (const match of html.matchAll(INLINE_SCRIPT)) {
+    const attrs = match[1] ?? ""
+    if (/\bsrc\s*=/i.test(attrs) || /\btype\s*=\s*["']?application\/(ld\+)?json/i.test(attrs))
+      continue
+    bodies.push(match[2] ?? "")
+  }
+  return bodies
+}
+
+const ENCODER = new TextEncoder()
+
+/** A CSP hash source for one inline script body: `'sha256-<base64 of the UTF-8 bytes>'`. */
+async function hashSource(body: string): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", ENCODER.encode(body)))
+  let binary = ""
+  for (const byte of digest) binary += String.fromCharCode(byte)
+  return `'sha256-${btoa(binary)}'`
+}
+
+/**
+ * The `'sha256-…'` sources for the constant inline scripts nifra writes into a document rendered
+ * with `adapter`: the pre-hydration form guard and the adapter's hydration head. For a CSP set outside
+ * the app (a proxy, a CDN rule); {@link createCspPolicy} computes the same list itself.
+ */
+export async function nifraScriptHashes(adapter: RenderAdapter): Promise<readonly string[]> {
+  const bodies = [PRE_HYDRATION_GUARD, ...inlineScriptBodies(adapter.hydrationHead())]
+  return Promise.all([...new Set(bodies)].map(hashSource))
+}
+
+/**
+ * Compute (once per adapter) the policy's hash sources. Returns `undefined` once they are ready, so
+ * the renderer stays synchronous after the first document.
+ */
+export function prepareCspPolicy(
+  policy: CspPolicy,
+  adapter: RenderAdapter,
+): Promise<void> | undefined {
+  const state = policy[CSP_POLICY]
+  const known = state.adapters.get(adapter)
+  if (known !== undefined) return known instanceof Promise ? known.then(() => undefined) : undefined
+  const head = adapter.hydrationHead()
+  const pending = nifraScriptHashes(adapter).then((hashes) => {
+    const sources = { head, sources: hashes.join(" ") }
+    state.adapters.set(adapter, sources)
+    return sources
+  })
+  state.adapters.set(adapter, pending)
+  // A failed digest must not pin a rejected promise: the next document retries.
+  pending.catch(() => state.adapters.delete(adapter))
+  return pending.then(() => undefined)
+}
+
+const preparedSources = (policy: CspPolicy, adapter: RenderAdapter): AdapterSources => {
+  const known = policy[CSP_POLICY].adapters.get(adapter)
+  if (known === undefined || known instanceof Promise) {
+    throw new Error("[nifra/web] CSP policy used before prepareCspPolicy resolved")
+  }
+  return known
+}
+
+/**
+ * The nonce one document carries under `policy`: `undefined` unless the document needs one -
+ * `needsNonce` (a deferred value or a head tag naming the nonce), or an adapter whose hydration head
+ * no longer matches the one the policy hashed. A needed nonce reuses the caller's, else is generated.
+ */
+export function cspDocumentNonce(
+  policy: CspPolicy,
+  adapter: RenderAdapter,
+  hydrate: boolean,
+  needsNonce: boolean,
+  requested: string | undefined,
+): string | undefined {
+  const varies = hydrate && adapter.hydrationHead() !== preparedSources(policy, adapter).head
+  if (!needsNonce && !varies) return undefined
+  return requested ?? policy[CSP_POLICY].generate()
+}
+
+/** The Content-Security-Policy value for one document, or `undefined` when the policy sends none. */
+export function cspHeaderValue(
+  policy: CspPolicy,
+  adapter: RenderAdapter,
+  nonce: string | undefined,
+): string | undefined {
+  const { sources } = preparedSources(policy, adapter)
+  const state = policy[CSP_POLICY]
+  return nonce === undefined
+    ? state.header({ sources })
+    : state.header({ sources: `${sources} 'nonce-${nonce}'`, nonce })
+}
+
+/** The per-request nonce source for a page executor under `policy`: generated eagerly so `meta` can
+ * name it in `unsafeInlineScript`, and dropped by the renderer from documents that do not need it. */
+export const cspNonceResolver = (policy: CspPolicy): NonceResolver =>
+  createNonceResolver({ generate: () => policy[CSP_POLICY].generate() })