@nifrajs/web 3.3.0 → 4.0.0

package/src/internal/codegen.ts

@@ -1,14 +1,27 @@
+import { type CssLoadingMode, DEFAULT_CSS_LOADING, normalizeCssLoading } from "../css-contract.ts"
 import { MAP_DEFERRED_SOURCE } from "../deferred.ts"
 import type { LayoutEntry, Manifest } from "../manifest.ts"
 import {
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
   DATA_GLOBAL,
+  HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
   ROOT_ATTRIBUTE,
   ROUTE_GLOBAL,
 } from "../render-seam.ts"
+import { PRERENDERED_GLOBAL } from "../router.ts"
 import { jsStringLiteral } from "./js-string.ts"
+
+/** The globals the page-state handover may set - nothing else in it reaches `window`. */
+const HANDOVER_GLOBALS = [
+  DATA_GLOBAL,
+  LAYOUT_DATA_GLOBAL,
+  ROUTE_GLOBAL,
+  ACTION_GLOBAL,
+  BOUNDARY_GLOBAL,
+  PRERENDERED_GLOBAL,
+]
 export interface GenerateClientEntryOptions {
   /**
    * Module specifier for the adapter's client runtime, e.g. `"@nifrajs/web-solid/client"`.
@@ -47,6 +60,8 @@ export function generateClientEntry(
   // Routes whose loader appends a nearest `_error` module (LAST) - the client wraps the page in the
   // adapter's `errorBoundary(fallback)` for these, so a client render error shows the `_error` UI.
   const errorRouteIds: string[] = []
+  // Route id → its layout ids, for the chain `useMatches` reports. Routes without layouts are omitted.
+  const layoutIdsOf: Record<string, readonly string[]> = {}
   // Lazy loader returns the raw modules (for both the component chain + the page's `meta` export).
   const lazyLoader = (files: readonly string[]): string => {
     const imports = files.map((f) => `import(${jsStringLiteral(resolve(f))})`).join(", ")
@@ -67,6 +82,7 @@ export function generateClientEntry(
       errorRouteIds.push(route.id)
     }
     loaderRows.push(`  ${JSON.stringify(route.id)}: ${lazyLoader(files)},`)
+    if (route.layoutIds.length > 0) layoutIdsOf[route.id] = route.layoutIds
     patternRows.push(
       `  { routeId: ${JSON.stringify(route.id)}, pattern: ${JSON.stringify(route.pattern)} },`,
     )
@@ -80,14 +96,46 @@ export function generateClientEntry(
     loaderRows.push(`  ${JSON.stringify(routeId)}: ${lazyLoader([entry.file])},`)
     statusRoutes[Number(status)] = routeId
   }
+  // `_loading` pages. Emitted only when the app has one, so an app without them imports nothing extra.
+  // Each is its own lazy chunk; a route row carries its layout ids and the loading pages above it with
+  // the number of those layouts each sits under - all the runtime needs to choose one.
+  const loadings = Object.entries(manifest.loadings ?? {})
+  const loadingLines: string[] = []
+  if (loadings.length > 0) {
+    const routeRows = new Map<string, string>()
+    for (const route of manifest.routes) {
+      const above = (route.loadingIds ?? []).map((id) => [
+        id,
+        manifest.loadings?.[id]?.layoutIds.length ?? 0,
+      ])
+      routeRows.set(
+        route.id,
+        `  ${JSON.stringify(route.id)}: ${JSON.stringify([route.layoutIds, above])},`,
+      )
+    }
+    loadingLines.push(
+      "const loadingModules = {",
+      ...loadings.map(
+        ([id, entry]) =>
+          `  ${JSON.stringify(id)}: () => import(${jsStringLiteral(resolve(entry.file))}),`,
+      ),
+      "}",
+      "const loadingRoutes = {",
+      ...routeRows.values(),
+      "}",
+    )
+  }
 
   return `${[
     // `/client`, never the root: the root's graph carries the server (renderPage, the static-file
     // server), and Vite's dev server evaluates what it is given instead of tree-shaking it.
     'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web/client"',
-    'import { applyHead, installForms, installHistory, signalHydrated } from "@nifrajs/web/client"',
+    'import { applyHead, currentDocumentNonce, installForms, installHistory, signalHydrated, waitForStyles } from "@nifrajs/web/client"',
     // Namespace import: `errorBoundary` is optional (an adapter may not export it). A namespace member
     // access yields `undefined` if absent - unlike a named import, which would be a link error.
+    ...(loadings.length > 0
+      ? ['import { withLoading } from "@nifrajs/web/internal/loading-runtime"']
+      : []),
     `import * as __adapter from ${JSON.stringify(clientModule)}`,
     "const { mountRouter } = __adapter",
     // The assurance hook is optional: ordinary client entries pay only for the namespace lookup, while
@@ -139,6 +187,12 @@ export function generateClientEntry(
     // routeId → the page's optional post-hydration client loader/action hooks. Hooks are populated only
     // after the route chunk loads, so routes that do not declare them remain ordinary route modules.
     "const routeHooks = {}",
+    // routeId → the chain the server rendered for an `ssr = false` page: the same layouts (and
+    // boundary), with the page's `HydrateFallback` - or an empty leaf - where the component goes.
+    "const holds = {}",
+    // routeId → the ids and `handle` exports `useMatches` reports (layouts, then the page).
+    `const layoutIdsOf = ${JSON.stringify(layoutIdsOf)}`,
+    "const matchChains = {}",
     "const loadModule = async (id) => {",
     "  if (chains[id]) return",
     "  const mods = await loaders[id]()",
@@ -160,20 +214,34 @@ export function generateClientEntry(
     // `searchSchema` merges with the page's. Client keys come from the page (second-to-last).
     "    searchSchemas[id] = mods.slice(0, mods.length - 1).map((m) => m.searchSchema)",
     "    searchClientKeys[id] = mods[mods.length - 2].searchClientKeys ?? []",
+    "    matchChains[id] = { ids: [...(layoutIdsOf[id] ?? []), id], handles: mods.slice(0, mods.length - 1).map((m) => m.handle) }",
     "  } else {",
     "    chains[id] = mods.map((m) => m.default)",
     "    metas[id] = mods.map((m) => m.meta)",
     // The chain is every module (layouts + page); client keys come from the page (the last module).
     "    searchSchemas[id] = mods.map((m) => m.searchSchema)",
     "    searchClientKeys[id] = mods[mods.length - 1].searchClientKeys ?? []",
+    "    matchChains[id] = { ids: [...(layoutIdsOf[id] ?? []), id], handles: mods.map((m) => m.handle) }",
     "  }",
     "  const page = errorRouteIds.has(id) ? mods[mods.length - 2] : mods[mods.length - 1]",
-    // Keep interception client-safe: only neutral name/mode metadata crosses into the router. The
-    // server-side boundary load function (which may close over secrets) is never stored in the client
-    // hook table or serialized into a browser bundle by this wiring.
+    // Only neutral name/mode metadata crosses into the router; a boundary's loader lives in the route's
+    // backend half, which no browser bundle contains.
     "  const boundaryMods = errorRouteIds.has(id) ? mods.slice(0, -1) : mods",
-    "  const boundaries = boundaryMods.flatMap((m) => (m.boundaries ?? []).map((b) => ({ name: b.name, mode: b.mode, hasLoad: b.load !== undefined, ...(b.errorId === undefined ? {} : { errorId: b.errorId }) })))",
+    "  const boundaries = boundaryMods.flatMap((m) => (m.boundaries ?? []).map((b) => ({ name: b.name, mode: b.mode, ...(b.errorId === undefined ? {} : { errorId: b.errorId }) })))",
     "  routeHooks[id] = { clientLoader: page.clientLoader, clientAction: page.clientAction, boundaries }",
+    "  if (page.ssr === false) holds[id] = [...chains[id].slice(0, -1), page.HydrateFallback ?? (() => null)]",
+    "}",
+    // The server hands page state over as one inert JSON script; lift it onto the globals the
+    // router, the deferred mapper and the adapters read, before any of them runs. Only the LAST
+    // matching <script> counts, and only known keys: page HTML (sanitized user content) can carry an
+    // element with the same id, and arbitrary keys copied onto `window` include `location`.
+    `const handovers = document.querySelectorAll(${JSON.stringify(`script[type="application/json"][id="${HANDOVER_ID}"]`)})`,
+    "const handover = handovers[handovers.length - 1]",
+    "if (handover !== undefined) {",
+    '  const state = JSON.parse(handover.textContent || "{}")',
+    `  for (const key of ${JSON.stringify(HANDOVER_GLOBALS)}) {`,
+    "    if (Object.prototype.hasOwnProperty.call(state, key)) Reflect.set(window, key, state[key])",
+    "  }",
     "}",
     "const patterns = [",
     ...patternRows,
@@ -181,12 +249,19 @@ export function generateClientEntry(
     // Derive the initial route from the URL (correct on refresh/deep-link); fall back to the
     // server-injected route id for non-pattern routes (e.g. _404, which matches nothing).
     "const matched = createMatcher(patterns)(location.pathname)",
+    `const statusRoutes = ${JSON.stringify(statusRoutes)}`,
+    `const serverRoute = window.${ROUTE_GLOBAL} ?? ""`,
+    // A terminal status page the server rendered (`_404`, `_410`, ...) outranks the URL match: a
+    // loader that throws notFound() on `/learn/bad-slug` leaves a URL that still matches
+    // `learn/[slug]`, and hydrating that route with null data over the 404 markup is wrong. Membership
+    // in the status table, not a `_` prefix: `routes/_admin/index.tsx` is an ordinary routable id.
+    "const terminal = Object.values(statusRoutes).includes(serverRoute)",
     // Map any `{__nifra_deferred: id}` placeholder in the SSR data to the registry's promise, so the
     // component receives real promises to `<Await>` (a no-op when a page has no deferred data).
     MAP_DEFERRED_SOURCE,
     "const initial = {",
-    `  routeId: matched ? matched.routeId : (window.${ROUTE_GLOBAL} ?? ""),`,
-    "  params: matched ? matched.params : {},",
+    "  routeId: matched && !terminal ? matched.routeId : serverRoute,",
+    "  params: matched && !terminal ? matched.params : {},",
     // pathname + search (NOT just pathname): the SSR render threads `pathname+search` into
     // `useLocation`/`useSearchParams`, so the hydrating initial state must carry the query too or a
     // page reading the search string would hydrate-mismatch. The #hash is client-only (never SSR'd).
@@ -201,8 +276,12 @@ export function generateClientEntry(
     `  actionData: mapDeferred(window.${ACTION_GLOBAL}),`,
     "  pending: false,",
     "}",
-    `const statusRoutes = ${JSON.stringify(statusRoutes)}`,
-    "const router = createClientRouter({ patterns, initial, loadModule, statusRoutes, searchClientKeys, routeHooks })",
+    ...loadingLines,
+    // With `_loading` pages the store is wrapped: a slow navigation then names a loading chain (the
+    // shared layouts + the `_loading` component) for the mounted view to render in the meantime.
+    loadings.length > 0
+      ? "const router = withLoading(createClientRouter({ patterns, initial, loadModule, statusRoutes, searchClientKeys, routeHooks }), { routes: loadingRoutes, modules: loadingModules, chains, searchSchemas, matchChains })"
+      : "const router = createClientRouter({ patterns, initial, loadModule, statusRoutes, searchClientKeys, routeHooks })",
     "installHistory(router)",
     "installForms(router)",
     // The container is found in the DOM, not baked in. `rootId` is a per-render option and this entry
@@ -219,10 +298,45 @@ export function generateClientEntry(
         "is set, `#root` otherwise - and this document has neither. If you emit the document yourself, " +
         'keep `<div id="root">` around the SSR markup.',
     )})`,
-    // Load the initial route's chunk, then hydrate the Router (chain is cached). The initial head
-    // is server-rendered; subsequent navigations update it from the matched route's meta + data.
-    "loadModule(initial.routeId).then(() => {",
-    "  mountRouter({ router, routes: chains, searchSchemas, container: root })",
+    // Wait for framework-owned deferred CSS before loading/mounting the initial route. The coordinator
+    // is a no-op for the default blocking links and always has a bounded fail-open terminal state.
+    "waitForStyles().then(() => loadModule(initial.routeId)).then(() => {",
+    // An `ssr = false` page: the server rendered its held chain, so the view hydrates THAT - under a
+    // chain id no route file can produce - and is handed the real route a task later, once every
+    // adapter has hydrated and subscribed. Only the first view is held; a client navigation to such a
+    // page has no server markup to match and renders the component directly.
+    "  let view = router",
+    "  const hold = holds[initial.routeId]",
+    "  if (hold) {",
+    '    const id = "\\0ssr"',
+    "    chains[id] = hold",
+    "    searchSchemas[id] = searchSchemas[initial.routeId]",
+    "    matchChains[id] = matchChains[initial.routeId]",
+    "    const listeners = new Set()",
+    "    let held = true",
+    "    let base",
+    "    let derived",
+    "    view = {",
+    "      ...router,",
+    "      snapshot() {",
+    "        const s = router.snapshot()",
+    "        if (!held) return s",
+    // One derived state per router state: the view's store must hand back a stable reference.
+    "        if (base !== s) derived = { ...(base = s), routeId: id }",
+    "        return derived",
+    "      },",
+    "      subscribe(listener) {",
+    "        listeners.add(listener)",
+    "        const off = router.subscribe(listener)",
+    "        return () => (listeners.delete(listener), off())",
+    "      },",
+    "    }",
+    "    setTimeout(() => {",
+    "      held = false",
+    "      for (const listener of [...listeners]) listener()",
+    "    }, 0)",
+    "  }",
+    "  mountRouter({ router: view, routes: chains, searchSchemas, matchChains, container: root })",
     // Run the optional client loader only after the adapter has mounted the SSR tree. The initial
     // server data is already in `window.__NIFRA_DATA__`, so `serverLoader()` reuses it and cannot
     // duplicate the first request.
@@ -236,11 +350,12 @@ export function generateClientEntry(
     "    if (!s.pending) {",
     // `origin: location.origin` matches the SSR `originOf(req)` (both are `URL.origin` for the same
     // page URL), so a soft-nav re-resolves the SAME absolute canonical/og:url - no head drift.
-    "      const args = { data: s.data, params: s.params, origin: location.origin }",
+    "      const nonce = currentDocumentNonce()",
+    "      const args = { data: s.data, params: s.params, origin: location.origin, ...(nonce === undefined ? {} : { nonce }) }",
     "      applyHead(mergeHeads((metas[s.routeId] ?? [undefined]).map((m) => resolveMeta(m, args))))",
     "    }",
     "  })",
-    "})",
+    "}).catch((error) => console.error('[nifra/web] hydration failed:', error))",
   ].join("\n")}\n`
 }
 
@@ -305,6 +420,8 @@ export interface GenerateServerManifestOptions {
   /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) - baked as
    * `export const routeStyles` so a page links only the CSS its route chain uses. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined
+  /** How framework-owned stylesheet links should activate before the generated client mounts. */
+  readonly cssLoading?: CssLoadingMode
   /** Emit **lazy** per-route loaders (`() => import("./routes/x")`, a static specifier) instead of
    * eager `import * as`, so a bundler with code-splitting emits one chunk per route - loaded on the
    * first request to it, not all at boot (smaller cold-start parse). Default `false` (eager). Both
@@ -316,7 +433,8 @@ export interface GenerateServerManifestOptions {
  * Codegen: emit a **server manifest** module (as source) for disk-less edge runtimes (Cloudflare
  * Workers, …) - and, with a `target`, any portable server bundle. `discoverRoutes` scans `node:fs`
  * and dynamic-imports each route by a *runtime* path - neither exists on workerd. This instead emits
- * **statically-analyzable** imports of every route/layout/`_error`/terminal status page (so the bundler includes them) and
+ * **statically-analyzable** imports of every route/layout/`_error`/terminal status page and each one's
+ * backend half (so the bundler includes them) and
  * rebuilds the manifest with `buildManifest` - the SAME pure logic `discoverRoutes` feeds, so patterns
  * + layout chains are identical. Eager (`import * as`) by default; `lazy` emits `() => import(...)` so
  * a code-splitting bundler chunks per route. The emitted module exports `manifest` (consumed by
@@ -335,20 +453,50 @@ function moduleSpecifier(resolved: string): string {
   return resolved.replace(SOURCE_EXTENSION, "")
 }
 
+// A route's namespace is not assignable to `RouteModule` under a strict `tsc` (a backend half has no
+// `default`, a typed `meta` narrows its data), so the table holds plain objects and the cast happens at
+// `buildManifest`'s boundary - the same cast `discoverRoutes` applies to its dynamic import.
+const LAZY_IMPORTER = "(file) => loaders[file] as () => Promise<RouteModule>"
+const EAGER_IMPORTER = "(file) => () => Promise.resolve(modules[file] as RouteModule)"
+
 export function generateServerManifest(
   manifest: Manifest,
   options: GenerateServerManifestOptions,
 ): string {
-  const { resolve, clientEntry, styles, routeStyles, lazy = false } = options
-  // Every unique source file in the manifest (routes + layouts + error/status pages), sorted for stable output.
+  const {
+    resolve,
+    clientEntry,
+    styles,
+    routeStyles,
+    cssLoading: requestedCssLoading,
+    lazy = false,
+  } = options
+  // A missing entry would bake `clientEntry = undefined` and the build would still succeed, leaving
+  // every hydrating page to fail at request time. `""` stays valid: an app with no client script.
+  if (typeof clientEntry !== "string") {
+    throw new TypeError(
+      `[nifra/web] the server build needs clientEntry (the built client entry URL, buildClient's manifest.entry), got ${clientEntry === null ? "null" : typeof clientEntry}; check the option is spelled clientEntry, or pass "" for an app with no client script`,
+    )
+  }
+  const cssLoading = normalizeCssLoading(requestedCssLoading ?? DEFAULT_CSS_LOADING)
+  // Every unique source file in the manifest, both halves of each, sorted for stable output. This is the
+  // one generated module that imports frontend and backend halves together: it is the server's
+  // composition, and `buildManifest` pairs the halves again from these keys.
+  const sources = [
+    ...manifest.routes,
+    ...Object.values(manifest.layouts),
+    ...Object.values(manifest.errors ?? {}),
+    ...(manifest.notFound ? [manifest.notFound] : []),
+    ...Object.values(manifest.notFounds ?? {}),
+    ...Object.values(manifest.statusPages ?? {}),
+    ...Object.values(manifest.middlewares ?? {}),
+  ]
   const files = [
-    ...new Set([
-      ...manifest.routes.map((r) => r.file),
-      ...Object.values(manifest.layouts).map((l) => l.file),
-      ...Object.values(manifest.errors ?? {}).map((e) => e.file),
-      ...(manifest.notFound ? [manifest.notFound.file] : []),
-      ...Object.values(manifest.statusPages ?? {}).map((page) => page.file),
-    ]),
+    ...new Set(
+      sources.flatMap((entry) =>
+        entry.backend === undefined ? [entry.file] : [entry.file, entry.backend],
+      ),
+    ),
   ].sort()
   const header = [
     "// GENERATED by @nifrajs/web generateServerManifest - route manifest for the disk-less edge",
@@ -361,6 +509,7 @@ export function generateServerManifest(
   // Always emitted (default empty) so consumers can `import { styles, routeStyles }` unconditionally.
   const stylesLine = `export const styles = ${JSON.stringify(styles ?? [])}`
   const routeStylesLine = `export const routeStyles = ${JSON.stringify(routeStyles ?? {})}`
+  const cssLoadingLine = `export const cssLoading = ${JSON.stringify(cssLoading)}`
   if (lazy) {
     // Lazy: `() => import("./routes/x")` per route (static specifier → one chunk per route under a
     // code-splitting bundler, loaded on first request). The map keys are the route-relative paths
@@ -371,13 +520,14 @@ export function generateServerManifest(
     )
     return `${[
       ...header,
-      "const loaders: Record<string, () => Promise<RouteModule>> = {",
+      "const loaders: Record<string, () => Promise<object>> = {",
       ...loaders,
       "}",
       clientEntryLine,
       stylesLine,
       routeStylesLine,
-      "export const manifest = buildManifest(Object.keys(loaders), (file) => () => loaders[file]())",
+      cssLoadingLine,
+      `export const manifest = buildManifest(Object.keys(loaders), ${LAZY_IMPORTER})`,
     ].join("\n")}\n`
   }
   // Eager: `import * as` per route (all bundled into the entry, parsed at boot). Index-based
@@ -389,12 +539,13 @@ export function generateServerManifest(
   return `${[
     ...header,
     ...imports,
-    "const modules: Record<string, RouteModule> = {",
+    "const modules: Record<string, object> = {",
     ...entries,
     "}",
     clientEntryLine,
     stylesLine,
     routeStylesLine,
-    "export const manifest = buildManifest(Object.keys(modules), (file) => () => Promise.resolve(modules[file]))",
+    cssLoadingLine,
+    `export const manifest = buildManifest(Object.keys(modules), ${EAGER_IMPORTER})`,
   ].join("\n")}\n`
 }

package/src/internal/dev-csp.ts

@@ -0,0 +1,176 @@
+/**
+ * Vite dev adds its own tags to each SSR'd page: the HMR client, a framework's refresh preamble (an
+ * inline script), and at runtime a `<style>` per imported stylesheet. A page whose CSP admits scripts
+ * by nonce or hash refuses all of them, so the app would not boot in dev. Dev gives every such tag one
+ * nonce - the page's own, or a fresh one for a hash-only page - and names it in each directive that
+ * governs them.
+ */
+
+const POLICY_HEADERS = ["content-security-policy", "content-security-policy-report-only"] as const
+
+/** Directives that govern each element kind, most specific first: the first present one applies. */
+const GOVERNING = [
+  ["script-src-elem", "script-src", "default-src"],
+  ["style-src-elem", "style-src", "default-src"],
+] as const
+
+const NONCE_SOURCE = /'nonce-([^']+)'/
+
+/** True when a directive admits every inline element: `'unsafe-inline'`, not voided by a nonce or hash. */
+const allowsInline = (sources: readonly string[]): boolean =>
+  sources.includes("'unsafe-inline'") &&
+  !sources.some((source) => /^'(?:nonce|sha256|sha384|sha512)-/.test(source))
+
+/** One header value (comma-separated policies), with `'nonce-<nonce>'` added where it is needed. */
+function admitNonce(value: string, nonce: string): string {
+  const token = `'nonce-${nonce}'`
+  return value
+    .split(",")
+    .map((policy) => {
+      const directives = policy
+        .split(";")
+        .map((directive) => directive.trim())
+        .filter((directive) => directive !== "")
+        .map((directive) => directive.split(/\s+/))
+      for (const names of GOVERNING) {
+        const governing = names
+          .map((name) => directives.find(([directive]) => directive?.toLowerCase() === name))
+          .find((directive) => directive !== undefined)
+        if (governing === undefined) continue
+        const sources = governing.slice(1)
+        if (sources.includes(token) || sources.includes("'none'") || allowsInline(sources)) continue
+        governing.push(token)
+      }
+      return directives.map((directive) => directive.join(" ")).join("; ")
+    })
+    .join(", ")
+}
+
+const RAW_TEXT_START = /<(script|style)\b([^>]*)>/gi
+
+/** `html` with `nonce` on each `<script>` / `<style>` that has none; their bodies are left as written. */
+function nonceTags(html: string, nonce: string): string {
+  let out = ""
+  let at = 0
+  const lower = html.toLowerCase()
+  RAW_TEXT_START.lastIndex = 0
+  for (let match = RAW_TEXT_START.exec(html); match !== null; match = RAW_TEXT_START.exec(html)) {
+    const [tag, name = "", attrs = ""] = match
+    out += html.slice(at, match.index)
+    out += /\snonce\s*=/i.test(attrs) ? tag : `<${name} nonce="${nonce}"${attrs}>`
+    const close = lower.indexOf(`</${name.toLowerCase()}`, RAW_TEXT_START.lastIndex)
+    at = close === -1 ? html.length : close
+    out += html.slice(RAW_TEXT_START.lastIndex, at)
+    RAW_TEXT_START.lastIndex = at
+  }
+  return out + html.slice(at)
+}
+
+/**
+ * Let a dev page's CSP admit what Vite injected. Rewrites the policy headers in `headers` and returns
+ * the page with the nonce on its script and style tags, plus the `csp-nonce` meta Vite's client reads
+ * to nonce the styles it adds at runtime. A page with no CSP is returned as it is.
+ */
+export function admitViteTags(
+  html: string,
+  headers: Headers,
+  generate: () => string = () => crypto.randomUUID().replaceAll("-", ""),
+): string {
+  const policies = POLICY_HEADERS.map((name) => [name, headers.get(name)] as const)
+  if (policies.every(([, value]) => value === null)) return html
+  const nonce =
+    policies.map(([, value]) => NONCE_SOURCE.exec(value ?? "")?.[1]).find((n) => n !== undefined) ??
+    generate()
+  for (const [name, value] of policies) {
+    if (value !== null) headers.set(name, admitNonce(value, nonce))
+  }
+  const tagged = nonceTags(html, nonce)
+  if (tagged.includes(`property="csp-nonce"`)) return tagged
+  const meta = `<meta property="csp-nonce" nonce="${nonce}">`
+  const head = /<head\b[^>]*>/i.exec(tagged)
+  return head === null
+    ? meta + tagged
+    : tagged.slice(0, head.index + head[0].length) +
+        meta +
+        tagged.slice(head.index + head[0].length)
+}
+
+const SCRIPT_DIRECTIVES = GOVERNING[0]
+const CONNECT_DIRECTIVES = ["connect-src", "default-src"] as const
+
+/** Whether `sources` already let the page reach `url` (a same-origin absolute URL). */
+const reaches = (sources: readonly string[], url: URL): boolean =>
+  sources.some((source) => {
+    const lower = source.toLowerCase()
+    return (
+      lower === "'self'" ||
+      lower === "*" ||
+      lower === `${url.protocol}` ||
+      lower === url.origin ||
+      lower === `${url.origin}/` ||
+      lower === url.href
+    )
+  })
+
+/**
+ * Admit nifra's own inline dev script, by `hash`, and its POSTs to `connect`, in each policy header.
+ * Without a `hash` the caller nonces the script itself. Returns false when a policy forbids scripts
+ * outright (`'none'`): such a page runs no code, so there is nothing to capture and the script stays
+ * out. A directive that already admits every inline script is left alone, because adding a hash would
+ * switch its `'unsafe-inline'` off. `module` is the one script the inline one may load; it is admitted
+ * by its exact URL, except under `'strict-dynamic'`, which ignores URLs and trusts what a trusted
+ * script loads anyway.
+ */
+export function admitInlineScript(
+  headers: Headers,
+  hash: string | undefined,
+  connect: URL,
+  module?: URL,
+): boolean {
+  const updates: [string, string][] = []
+  let allowed = true
+  for (const name of POLICY_HEADERS) {
+    const value = headers.get(name)
+    if (value === null) continue
+    const next = value
+      .split(",")
+      .map((policy) => {
+        const directives = policy
+          .split(";")
+          .map((directive) => directive.trim())
+          .filter((directive) => directive !== "")
+          .map((directive) => directive.split(/\s+/))
+        const governing = (names: readonly string[]): string[] | undefined =>
+          names
+            .map((n) => directives.find(([directive]) => directive?.toLowerCase() === n))
+            .find((directive) => directive !== undefined)
+        const script = governing(SCRIPT_DIRECTIVES)
+        if (script !== undefined) {
+          const sources = script.slice(1)
+          if (sources.includes("'none'")) allowed = false
+          else {
+            if (hash !== undefined && !sources.includes(hash) && !allowsInline(sources))
+              script.push(hash)
+            if (
+              module !== undefined &&
+              !sources.includes("'strict-dynamic'") &&
+              !reaches(sources, module)
+            )
+              script.push(module.href)
+          }
+        }
+        const connectDirective = governing(CONNECT_DIRECTIVES)
+        if (connectDirective !== undefined && !reaches(connectDirective.slice(1), connect)) {
+          const none = connectDirective.indexOf("'none'")
+          if (none === -1) connectDirective.push(connect.href)
+          else connectDirective.splice(none, 1, connect.href)
+        }
+        return directives.map((directive) => directive.join(" ")).join("; ")
+      })
+      .join(", ")
+    updates.push([name, next])
+  }
+  if (!allowed) return false
+  for (const [name, value] of updates) headers.set(name, value)
+  return true
+}

package/src/internal/dev-reserved.ts

@@ -0,0 +1,52 @@
+/**
+ * Specifiers no plugin may match on Bun's dev-server bundler.
+ *
+ * When a `[serve.static]` plugin's `onResolve` FILTER matches an import, Bun sends it down its plugin
+ * path, and a handler that declines does not undo that: Bun then resolves the import on a fallback that
+ * breaks a nifra dev page in two ways (Bun 1.3.14 through 1.4.3, oven-sh/bun#19951):
+ *
+ * - an HTML page's `<script src>` keeps its raw specifier in the HMR module table, so the browser throws
+ *   "Failed to load bundled module" and the page never hydrates;
+ * - the fallback skips the dev server's built-in modules, so the React Fast Refresh runtime Bun embeds
+ *   for an app without `react-refresh` installed fails to resolve, and the dev server does not start.
+ *
+ * unplugin's Bun adapter registers `onResolve({ filter: /.*\/ })` for every plugin with a `resolveId`
+ * hook, so an app plugin can hit both without doing anything unusual. Every plugin nifra hands that
+ * bundler registers through {@link reserveDevSpecifiers}.
+ */
+
+import type { PluginBuilder } from "bun"
+
+/** The generated client entry, written beside the probe page that loads it. Named so that no import
+ * an app writes can be the reserved specifier. */
+export const DEV_ENTRY_FILE = "nifra-dev-entry.tsx"
+
+const RESERVED = [`./${DEV_ENTRY_FILE}`, "react-refresh/runtime/index.js"]
+const RESERVED_SOURCE = RESERVED.map((specifier) =>
+  specifier.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&"),
+).join("|")
+
+/** `filter`, except that it never matches a reserved specifier. Any other string matches as before. */
+export function withoutReservedSpecifiers(filter: RegExp): RegExp {
+  // The original runs inside a lookahead from the start, so it still matches anywhere in the string
+  // and its own anchors, lookbehinds and backreferences keep their meaning. `g` and `y` are dropped:
+  // they make `test` depend on `lastIndex`, which a filter has no use for.
+  return new RegExp(
+    `^(?!(?:${RESERVED_SOURCE})$)(?=[\\s\\S]*?(?:${filter.source}))`,
+    filter.flags.replace(/[gy]/g, ""),
+  )
+}
+
+/** A view of `build` whose `onResolve` filters never match a reserved specifier. */
+export function reserveDevSpecifiers(build: PluginBuilder): PluginBuilder {
+  return {
+    ...build,
+    onResolve(constraints, callback) {
+      build.onResolve(
+        { ...constraints, filter: withoutReservedSpecifiers(constraints.filter) },
+        callback,
+      )
+      return this
+    },
+  }
+}

package/src/internal/html-spans.ts

@@ -0,0 +1,50 @@
+// The comment and delimiter readers scan instead of matching one lazy RegExp: a pattern like
+// `<!--[\s\S]*?-->` reads to the end of the source again from every opener that never closes.
+
+/**
+ * `source` without its HTML comments. A browser ends one at `-->`, and also at `--!>`; an opener
+ * with no end after it is kept as text.
+ */
+export function withoutComments(source: string): string {
+  const end = /--!?>/g
+  let kept = ""
+  let from = 0
+  for (let start = source.indexOf("<!--"); start !== -1; start = source.indexOf("<!--", from)) {
+    end.lastIndex = start + 4
+    const close = end.exec(source)
+    // No later opener has an end after it either.
+    if (close === null) break
+    kept += source.slice(from, start)
+    from = close.index + close[0].length
+  }
+  return kept + source.slice(from)
+}
+
+/** The text between each `open` and the first `close` after it, read on from that `close`. */
+export function delimitedSpans(source: string, open: string, close: string): string[] {
+  const spans: string[] = []
+  for (let start = source.indexOf(open); start !== -1; ) {
+    const end = source.indexOf(close, start + open.length)
+    if (end === -1) break
+    spans.push(source.slice(start + open.length, end))
+    start = source.indexOf(open, end + close.length)
+  }
+  return spans
+}
+
+/** `source` without the spans the global `pattern` matches, each handed to `onMatch` first. */
+export function withoutMatches(
+  source: string,
+  pattern: RegExp,
+  onMatch?: (match: RegExpMatchArray) => void,
+): string {
+  let kept = ""
+  let from = 0
+  for (const match of source.matchAll(pattern)) {
+    onMatch?.(match)
+    const start = match.index ?? 0
+    kept += source.slice(from, start)
+    from = start + match[0].length
+  }
+  return kept + source.slice(from)
+}