@nifrajs/web 3.3.0 → 4.0.0

package/src/internal/web-app.ts

@@ -1,58 +1,26 @@
 import {
+  type BackendEvidenceProvider,
   type BackendMount,
-  type BackendMountHandler,
+  type BackendWebSocketMountHandler,
+  NIFRA_BACKEND_EVIDENCE,
   NIFRA_BACKEND_MOUNT,
+  NIFRA_BACKEND_WS_MOUNT,
+  NIFRA_BACKEND_WS_RUNTIME,
+  preRouteMountPaths,
 } from "@nifrajs/core/mount"
-import { type ServerOptions, server, type UrlParts, urlPartsOf } from "@nifrajs/core/server"
-import {
-  type BoundaryRequestCtx,
-  type BoundaryStates,
-  boundaryDescriptors,
-  resolveStaticBoundaries,
-  startDynamicBoundaries,
-} from "../boundary.ts"
-import { defer, ndjsonStream, prepareDeferred } from "../deferred.ts"
-import { isDraftEnabled } from "../draft.ts"
+import type { MountableApp, MountOptions } from "@nifrajs/core/server"
+import { type ServerOptions, server } from "@nifrajs/core/server"
+import { type CspPolicy, cspNonceResolver, DOCUMENT_POLICY, isCspPolicy } from "../csp.ts"
+import type { CssLoadingMode } from "../css-contract.ts"
+import { CACHE_CHANNEL } from "../isr.ts"
 import { generateLlmsTxt } from "../llms-txt.ts"
-import type {
-  LayoutEntry,
-  LoaderContext,
-  Manifest,
-  Meta,
-  MetaArgs,
-  RouteEntry,
-  RouteModule,
-} from "../manifest.ts"
+import type { Manifest } from "../manifest.ts"
 import type { RenderAdapter } from "../render-seam.ts"
-import {
-  createMatcher,
-  DATA_HEADER,
-  NAV_FROM_HEADER,
-  RETAIN_HEADER,
-  REVALIDATE_HEADER,
-  STATUS_HEADER,
-} from "../router.ts"
-import { searchOf, searchOfChain } from "../search.ts"
-import { mergeHeads, resolveMeta } from "./head-merge.ts"
-import {
-  actionResponse,
-  EMPTY_RETAIN,
-  type HeadersLike,
-  isControlFlow,
-  isStatusSignal,
-  type LoadedLayoutModules,
-  layoutErrorId,
-  type RenderAssemblyCache,
-  type RenderedPage,
-  type RevalidateResult,
-  renderPageResult,
-  STATUS_SIGNAL,
-  STATUS_TEXT,
-  type StatusSignal,
-  scopeParams,
-  tagLayoutError,
-  withDuplicateInstanceHint,
-} from "./render-document.ts"
+import { PRERENDERED_LIST_PATH } from "../router.ts"
+import { formatShadowedPages, shadowedPages } from "./mount-shadow.ts"
+import { createPageRequestExecutor, type NonceResolver } from "./page-execution.ts"
+
+export type { NonceResolver } from "./page-execution.ts"
 export interface CreateWebAppOptions<Env = unknown> {
   readonly adapter: RenderAdapter
   readonly manifest: Manifest
@@ -60,6 +28,21 @@ export interface CreateWebAppOptions<Env = unknown> {
   readonly clientEntry: string
   /** Default document title for all pages. */
   readonly title?: string
+  /**
+   * Resolve a fresh CSP nonce for each document request. The value is applied to every
+   * framework-owned executable script; return `undefined` to keep the default nonce-free output.
+   * Nonce-bearing documents are marked `private, no-store` so the request-specific value is not
+   * replayed by browser, CDN, or ISR caches. The resolver does not declare a CSP header because the
+   * policy's allowed sources are app-specific.
+   */
+  readonly nonce?: NonceResolver<Env>
+  /**
+   * A hash-based Content-Security-Policy from `createCspPolicy`, instead of `nonce`. A document then
+   * carries a nonce only when it needs one (it `defer()`s a value, or `meta` names the nonce in
+   * `unsafeInlineScript`); every other page is nonce-free, gets the same CSP header on every request,
+   * and stays cacheable by `withISR` or a CDN. `meta` still receives a nonce to name.
+   */
+  readonly csp?: CspPolicy
   /**
    * Options for the underlying `server()` - `requestTimeoutMs`, `admission`, `gracefulSignals`, and
    * the rest of {@link ServerOptions}.
@@ -121,14 +104,26 @@ export interface CreateWebAppOptions<Env = unknown> {
    * mount interface from `@nifrajs/core/mount`; `createWebApp` also serves that backend over HTTP at
    * {@link apiPrefix} (default `/api`): a request whose pathname starts with the prefix is dispatched
    * before page routing with the same `env`/`waitUntil` platform context, and the backend's `Response`
-   * is returned untouched. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it. */
+   * is returned untouched. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it.
+   *
+   * **Request-scoped loader calls.** While a page renders, its loaders, actions and boundaries get a
+   * `ctx.api` bound to that request's platform identity: a backend handler reached through it sees the
+   * visitor's `c.clientIp` (derived under this app's `server.clientIp` trust declaration), `c.env` and
+   * `c.waitUntil`, so a per-caller rate limit or audit field keys on the real visitor. `c.clientIp` is
+   * the supported way to read the caller - identity travels in the platform, so rebuilding a `Request`
+   * does not lose it. Headers do NOT travel: the page request's `cookie` and `authorization` are never
+   * copied, so a loader call is anonymous unless the loader passes headers on the call itself. */
   readonly api?: unknown
   /** HTTP path prefix the {@link api} backend is auto-mounted at (default `"/api"`). A request whose
    * pathname is exactly the prefix or starts with `prefix + "/"` is dispatched to the backend before
    * page routing; the backend therefore defines its routes at the **full** path (`server().post("/api/
    * sync", …)`), matching the in-process `inProcessClient` call sites. Set to `""` to disable the
    * auto-mount entirely (the app serves pages only and `api` stays a loader-only `ctx.api`). Mounting
-   * is also a no-op when `api` does not expose the symbol mount. */
+   * is also a no-op when `api` does not expose the symbol mount.
+   *
+   * A page file under the prefix (`routes/api/report.tsx`) could never render - the backend answers
+   * first and its 404 is final - so `createWebApp` throws, naming the file. The same holds for every
+   * other pre-route mount. */
   readonly apiPrefix?: string
   /**
    * Strip {@link apiPrefix} from the pathname before dispatching to `api` (default `false`).
@@ -150,12 +145,16 @@ export interface CreateWebAppOptions<Env = unknown> {
    *
    * Tried longest-path-first and BEFORE the `api` mount, so a mount at `/api/auth` wins over a backend
    * at `/api` no matter which was declared first. `stripPrefix` is the per-mount form of {@link apiStrip}:
-   * leave it off to pass the full path through.
+   * leave it off to pass the full path through. `opaque` states why a mount whose routes nifra cannot
+   * read (better-auth's handler) is outside assurance; it is then listed as a known gap.
    */
   readonly mounts?: ReadonlyArray<{
     readonly path: string
-    readonly app: { fetch(request: Request): Response | Promise<Response> }
+    readonly app: MountableApp<Env>
     readonly stripPrefix?: boolean
+    readonly priority?: number
+    readonly fallbackOn?: 404
+    readonly opaque?: string
   }>
   /** Secret for **draft / preview mode** (see `enableDraft`). When set, a request carrying a valid
    * signed `__nifra_draft` cookie gets `ctx.draft === true` in loaders/actions (else always `false`).
@@ -174,15 +173,27 @@ export interface CreateWebAppOptions<Env = unknown> {
    * of the aggregate `styles`, so a page ships only the CSS it uses. An empty array ⇒ no `<link>` (the
    * page imports no CSS). Routes absent here fall back to `styles`. Omit ⇒ always use `styles`. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>>
+  /**
+   * Activation policy for framework-owned stylesheet links (default `"blocking"`). `"deferred"`
+   * emits `media="print"` links; the generated client waits for them and switches them to `all` before
+   * mounting. Pair with an aggregate Vite stylesheet (`cssCodeSplit: false`) to prevent lazy-prefetch
+   * CSS insertion. Non-hydrated pages always keep their stylesheet links blocking.
+   */
+  readonly cssLoading?: CssLoadingMode
   /** SSG: the prerendered-path set (e.g. `enumerateStaticRoutes(routes).paths` or the build's
-   * `prerendered.json`). Injected as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
-   * into a prerendered route fetches its static `_data.json` instead of hitting the worker. */
+   * `prerendered.json`). Handed over as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
+   * into a prerendered route fetches its static `_data.json` instead of hitting the worker. A set over
+   * 4 KB of JSON is served once from `/__nifra/prerendered.json?v=<version>`, cacheable for good, and
+   * pages hand over only that URL; `prerenderRoutes` writes the file into a static output. */
   readonly prerenderedPaths?: readonly string[]
   /** Publish the project's `AGENTS.md` inside `/llms.txt` and `/llms-full.txt`. **Off by default**:
    * those endpoints are public and unauthenticated, while `AGENTS.md` is a repo file written for the
    * team - unreleased feature names, internal hostnames, and "don't touch X yet" notes live there
    * routinely. Turn it on only for a repo whose guidelines you would publish as a page. */
   readonly publishLocalGuidelines?: boolean
+  /** Serve `/llms.txt` and `/llms-full.txt` (default `true`): the page routes, and the backend routes
+   * when the backend is mounted over HTTP at {@link apiPrefix}. `false` registers neither path. */
+  readonly llmsTxt?: boolean
   /** SSG: per dynamic route pattern, its `getStaticPaths` `fallback` (from `enumerateStaticRoutes` or
    * the build's `prerendered.json`). A route mapped to `"404"` rejects any path NOT in
    * `prerenderedPaths` with the 404 page - the unlisted path simply doesn't exist. `"ssr"` (the
@@ -207,14 +218,6 @@ export interface CreateWebAppOptions<Env = unknown> {
   ) => void
 }
 
-/** The handler context fields createWebApp uses - a structural subset of nifra's `Context`. */
-interface RouteContext {
-  readonly params: Record<string, string>
-  readonly req: Request
-  /** Platform bindings (Workers env), forwarded to each route's loader/action as `args.env`. */
-  readonly env: unknown
-}
-
 /**
  * Re-issue `request` with `prefix` removed from its pathname.
  *
@@ -228,35 +231,47 @@ interface RouteContext {
  * The `Request` is rebuilt rather than mutated (`url` is read-only), preserving method, headers, body,
  * and duplex streaming - the body is passed through unread, so a large or streamed upload is untouched.
  */
-function stripMountPrefix(request: Request, prefix: string): Request {
-  const url = new URL(request.url)
-  const rest = url.pathname.slice(prefix.length)
-  url.pathname = rest === "" ? "/" : rest
-  // `url.href`, not the `URL`: this type set only declares the string and Request overloads.
-  return new Request(url.href, request)
-}
-
 /**
  * Resolve the explicit symbol-keyed backend mount interface. The symbol seam forwards platform
  * context without making web depend on client.
  */
-function backendMountOf(api: unknown): BackendMountHandler | undefined {
+function backendMountOf<Env>(api: unknown): MountableApp<Env> | undefined {
   if ((typeof api !== "object" && typeof api !== "function") || api === null) return undefined
-  const explicit = (api as Partial<BackendMount>)[NIFRA_BACKEND_MOUNT]
+  const explicit = (api as Partial<BackendMount<Env>>)[NIFRA_BACKEND_MOUNT]
   if (typeof explicit !== "function") return undefined
-  return (request, platform) => explicit.call(api, request, platform)
+  const websocket = (api as Partial<BackendMount<Env>>)[NIFRA_BACKEND_WS_MOUNT]
+  const runtime = (api as Partial<BackendMount<Env>>)[NIFRA_BACKEND_WS_RUNTIME]
+  const evidence = (api as Partial<BackendMount<Env>>)[NIFRA_BACKEND_EVIDENCE]
+  const mount: {
+    fetch: MountableApp<Env>["fetch"]
+    resolveWebSocketUpgrade?: BackendWebSocketMountHandler<Env>
+    [NIFRA_BACKEND_WS_RUNTIME]?: NonNullable<BackendMount<Env>[typeof NIFRA_BACKEND_WS_RUNTIME]>
+    [NIFRA_BACKEND_EVIDENCE]?: BackendEvidenceProvider
+  } = {
+    fetch: (request, platform) => explicit.call(api, request, platform),
+  }
+  if (typeof websocket === "function") {
+    mount.resolveWebSocketUpgrade = (request, platform) => websocket.call(api, request, platform)
+  }
+  if (typeof runtime === "function") mount[NIFRA_BACKEND_WS_RUNTIME] = runtime
+  if (typeof evidence === "function") mount[NIFRA_BACKEND_EVIDENCE] = evidence
+  return mount
+}
+
+function evidenceProviderOf(value: unknown): BackendEvidenceProvider | undefined {
+  if ((typeof value !== "object" && typeof value !== "function") || value === null) return undefined
+  const provider = (value as { [NIFRA_BACKEND_EVIDENCE]?: unknown })[NIFRA_BACKEND_EVIDENCE]
+  return typeof provider === "function" ? (provider as BackendEvidenceProvider) : undefined
 }
 
-// `createWebApp` reaches the same Request object through the mount hook and the page route. Cache the
-// allocation-light core split once so API mounting, path hydration, search parsing, and SSG fallback
-// checks do not each rescan the absolute URL. WeakMap keeps this bounded to requests that are alive.
-const REQUEST_URL_PARTS = new WeakMap<Request, UrlParts>()
-const urlPartsFor = (request: Request): UrlParts => {
-  const cached = REQUEST_URL_PARTS.get(request)
-  if (cached !== undefined) return cached
-  const parts = urlPartsOf(request.url)
-  REQUEST_URL_PARTS.set(request, parts)
-  return parts
+function mountPathPrefix(path: string): string {
+  const withoutWildcard = path.endsWith("/*") ? path.slice(0, -2) : path
+  if (withoutWildcard === "" || withoutWildcard === "/") return ""
+  // Index-scan instead of `/\/+$/`: mount paths can be library input, and the
+  // unanchored-start trailing-run replacement can backtrack quadratically.
+  let end = withoutWildcard.length
+  while (end > 0 && withoutWildcard.charCodeAt(end - 1) === 47 /* '/' */) end--
+  return withoutWildcard.slice(0, end)
 }
 
 /**
@@ -277,25 +292,11 @@ export function createWebApp<Env = unknown>(
   options: CreateWebAppOptions<Env>,
 ): ReturnType<typeof server<Env>> {
   const { adapter, manifest, clientEntry, title, api } = options
-  const titleOption = title === undefined ? {} : { title }
-  // Draft/preview: when a `draftSecret` is configured, each request's signed `__nifra_draft` cookie is
-  // verified once and surfaced to loaders/actions as `ctx.draft`. No secret ⇒ always `false` (sync, free).
-  const draftFlag = (req: Request): Promise<boolean> =>
-    options.draftSecret === undefined
-      ? Promise.resolve(false)
-      : isDraftEnabled(req, options.draftSecret)
-  // Per-route preload chunks (spread into renderPage; omitted when unmapped, for exactOptionalPropertyTypes).
-  const preloadOf = (id: string): { preload?: readonly string[] } => {
-    const chunks = options.routePreload?.[id]
-    return chunks ? { preload: chunks } : {}
+  if (options.csp !== undefined && options.nonce !== undefined) {
+    throw new TypeError("[nifra/web] createWebApp takes `csp` or `nonce`, not both")
   }
-  // The matched route's stylesheet links (spread into renderPage). Per-route when the build mapped it
-  // (`routeStyles[id]` - only the chain's CSS; an empty array ⇒ no `<link>`), else the aggregate
-  // `styles`. Omitted entirely when CSS-free (for exactOptionalPropertyTypes).
-  const stylesOf = (id: string): { styles?: readonly string[] } => {
-    const perRoute = options.routeStyles?.[id]
-    if (perRoute !== undefined) return { styles: perRoute }
-    return options.styles && options.styles.length > 0 ? { styles: options.styles } : {}
+  if (options.csp !== undefined && !isCspPolicy(options.csp)) {
+    throw new TypeError("[nifra/web] createWebApp `csp` must come from createCspPolicy()")
   }
   // Seed the context with the declared `Env` so `app.fetch(req, { env })` / `toFetchHandler(app)` type
   // the platform bindings (see the `createWebApp` doc). The runtime `env` still arrives per-request via
@@ -305,810 +306,220 @@ export function createWebApp<Env = unknown>(
   // `beforeHandle`, assurance evidence) actually bind to them - see the `use` option. A caller
   // cannot do this after the fact: by the time this function returns, the routes are declared.
   options.use?.(app)
+  // A resolver created by `createNonceResolver({ header })` carries a paired response hook. Register it
+  // after caller middleware so its request-specific CSP value is the last default applied to a page.
+  const nonceResponse = options.nonce?.onResponse
+  if (nonceResponse !== undefined) app.onResponse(nonceResponse)
+  // How this app's documents meet a CSP, for wrappers that cache them (`withISR` warns on "nonce").
+  const documentPolicy =
+    options.csp !== undefined ? "hash" : options.nonce !== undefined ? "nonce" : undefined
+  if (documentPolicy !== undefined) {
+    Object.defineProperty(app, DOCUMENT_POLICY, { value: documentPolicy })
+  }
+  const cacheChannel = { enabled: false }
+  Object.defineProperty(app, CACHE_CHANNEL, {
+    value: () => {
+      cacheChannel.enabled = true
+    },
+  })
   // Auto-mount the in-process backend over HTTP at `apiPrefix` (default `/api`), BEFORE page routing.
-  // `onRequest` runs on the raw request ahead of the router, so this wins over the page wildcard `/*`
-  // for every method (POST/GET/PUT/…) - not just the GET page routes - and a backend 404 (`/api/none`)
-  // surfaces as the backend's own response, never the page 404. We dispatch the SAME `Request` object
-  // (its body unread) so streamed/large bodies pass through untouched; the backend defines its routes
-  // at the full prefixed path (`server().post("/api/sync", …)`), matching the `inProcessClient` call
-  // sites. `apiPrefix: ""` opts out; a non-mountable `api` (no symbol mount) is left pages-only. The hook
-  // is registered ONLY when both hold, so a pages-only app keeps core's synchronous no-hook fast path.
+  // Core's pre-route mount seam runs before the page wildcard `/*`; parent request hooks run first,
+  // child request hooks run inside the mount, and parent response hooks still wrap the result.
+  // The mount handles every HTTP method and preserves backend 404 responses instead of letting the
+  // page catch-all render them. We dispatch the same `Request` object (its body unread), so
+  // streamed/large bodies pass through untouched. The backend defines full prefixed paths
+  // (`server().post("/api/sync", …)`) unless `apiStrip` is enabled. `apiPrefix: ""` opts out;
+  // a non-mountable `api` remains loader-only and pages-only apps keep the no-mount fast path.
   const apiPrefix = options.apiPrefix ?? "/api"
   const apiStrip = options.apiStrip === true
-  const mountedApi = backendMountOf(api)
+  const mountedApi = backendMountOf<Env>(api)
   // Longest path first, so a more specific mount (`/api/auth`) is tried before a broader one (`/api`)
   // regardless of the order they were declared in.
-  const mounts = [...(options.mounts ?? [])].sort((a, b) => b.path.length - a.path.length)
-  const underPrefix = (pathname: string, prefix: string): boolean =>
-    pathname === prefix || pathname.startsWith(`${prefix}/`)
-
-  if (mounts.length > 0 || (apiPrefix !== "" && mountedApi !== undefined)) {
-    app.onRequest((req, platform) => {
-      const { pathname } = urlPartsFor(req)
-      // Sub-app mounts win over the backend prefix: they are the more specific declaration, and an
-      // auth handler mounted at `/api/auth` must not be swallowed by the backend mounted at `/api`.
-      for (const mount of mounts) {
-        if (!underPrefix(pathname, mount.path)) continue
-        return mount.app.fetch(mount.stripPrefix === true ? stripMountPrefix(req, mount.path) : req)
-      }
-      // Exactly the prefix (`/api`) or a sub-path (`/api/…`) - NOT a sibling like `/apixyz` that merely
-      // shares the prefix as a string head. Dispatch the original `req` (body intact) to the backend.
-      if (mountedApi !== undefined && apiPrefix !== "" && underPrefix(pathname, apiPrefix)) {
-        return mountedApi(apiStrip ? stripMountPrefix(req, apiPrefix) : req, platform)
-      }
-      return undefined // not an API path → continue to page routing
-    })
-  }
-  // SSG `fallback: "404"`: the set of concrete paths that actually exist for those routes. An unlisted
-  // path under a `"404"` route is rejected (it isn't a static file, and the route declared it shouldn't
-  // SSR on demand). O(1) membership via a Set.
-  const prerenderedSet = new Set(options.prerenderedPaths ?? [])
-  const matchManifestRoute = createMatcher(
-    manifest.routes.map((route) => ({ routeId: route.id, pattern: route.pattern })),
+  const configuredMounts: readonly MountOptions<Env>[] = Object.freeze(
+    (options.mounts ?? []).map(
+      (mount): MountOptions<Env> => ({
+        path: mount.path,
+        app: mount.app,
+        ...(mount.stripPrefix === undefined ? {} : { stripPrefix: mount.stripPrefix }),
+        ...(mount.priority === undefined ? {} : { priority: mount.priority }),
+        ...(mount.fallbackOn === undefined ? {} : { fallbackOn: mount.fallbackOn }),
+        ...(mount.opaque === undefined ? {} : { opaque: mount.opaque }),
+      }),
+    ),
   )
-  const routeById = new Map(manifest.routes.map((route) => [route.id, route]))
-
-  // Load a route's layout modules (outermost layout → innermost), keeping each module whole so the
-  // render path can take both its `default` (the component chain) AND its `meta` (the sitewide head it
-  // contributes). Loaded lazily - the data-only and 405 branches return before any layout is needed.
-  const loadLayoutModules = async (route: RouteEntry): Promise<LoadedLayoutModules> => {
-    const modules = await Promise.all(
-      // layoutIds only reference layouts present in the manifest (buildManifest invariant).
-      route.layoutIds.map((id) => (manifest.layouts[id] as LayoutEntry).load()),
-    )
-    // A layout is not a form target, so an `action` there is a mistake with no meaning to give it.
-    // A `loader`, by contrast, now runs (see `runLayoutChain`).
-    for (let i = 0; i < modules.length; i++) {
-      if ((modules[i] as { action?: unknown }).action === undefined) continue
-      const id = route.layoutIds[i] as string
-      throw new Error(
-        `[nifra/web] "${(manifest.layouts[id] as LayoutEntry).file}" exports an \`action\`, but layouts do not run one - only route files do. Move the mutation into the route that submits to it.`,
-      )
-    }
-    return modules
+  const mounts: Array<MountOptions<Env>> = [...configuredMounts]
+  if (mountedApi !== undefined && apiPrefix !== "") {
+    mounts.push({ path: apiPrefix, app: mountedApi, stripPrefix: apiStrip })
   }
+  for (const mount of mounts) app.mount(mount)
+  // Read back the server's own mount table, so a mount added in `use` counts as well: a page under any
+  // pre-route mount is unreachable, and serving it as a silent 404 hides that.
+  const shadowed = shadowedPages(manifest, preRouteMountPaths(app))
+  if (shadowed.length > 0) throw new Error(`[nifra/web] ${formatShadowedPages(shadowed)}`)
+  const ownPatterns = new Set(manifest.routes.map((route) => route.pattern))
+  const prerenderedList = ownPatterns.has(PRERENDERED_LIST_PATH)
+    ? undefined
+    : servedPrerenderedList(options.prerenderedPaths)
+  const pageExecutor = createPageRequestExecutor<Env>({
+    adapter,
+    manifest,
+    clientEntry,
+    ...(title === undefined ? {} : { title }),
+    ...(api === undefined ? {} : { api }),
+    ...(options.draftSecret === undefined ? {} : { draftSecret: options.draftSecret }),
+    ...(options.routePreload === undefined ? {} : { routePreload: options.routePreload }),
+    ...(options.styles === undefined ? {} : { styles: options.styles }),
+    ...(options.routeStyles === undefined ? {} : { routeStyles: options.routeStyles }),
+    ...(options.cssLoading === undefined ? {} : { cssLoading: options.cssLoading }),
+    ...(options.prerenderedPaths === undefined
+      ? {}
+      : { prerenderedPaths: options.prerenderedPaths }),
+    ...(prerenderedList === undefined ? {} : { prerenderedListUrl: prerenderedList.url }),
+    ...(options.staticFallbacks === undefined ? {} : { staticFallbacks: options.staticFallbacks }),
+    ...(options.staticBoundaryCache === undefined
+      ? {}
+      : { staticBoundaryCache: options.staticBoundaryCache }),
+    ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
+    ...(options.csp === undefined
+      ? {}
+      : { nonce: cspNonceResolver(options.csp) as NonceResolver<Env>, csp: options.csp }),
+    ...(options.onLoaderError === undefined ? {} : { onLoaderError: options.onLoaderError }),
+    cacheChannel,
+  })
 
-  /**
-   * Run a route's layout-chain loaders, honouring declared gates.
-   *
-   * Returns once every **gate** has resolved, with the non-gate loaders still in flight, so the caller
-   * can start the page loader at exactly the right moment: after anything that might reject the
-   * request, alongside anything that merely fetches.
-   *
-   * The ordering is the security-relevant part. Parallel loaders are NOT an authorization boundary -
-   * a page loader running concurrently with a guard has already queried by the time the guard says no.
-   * Remix documents that as a footgun; here it is a declaration instead. `export const gate = true`
-   * makes a layout blocking for everything beneath it, and nothing beneath a rejected gate runs.
-   *
-   * Each layout receives only the params it OWNS ({@link RouteEntry.layoutParams}), not the route's
-   * full set, so a layout at `orgs/[org]/` cannot read a param belonging to a route below it.
-   */
-  /**
-   * Layout indices a client navigation asked to keep, from {@link RETAIN_HEADER}.
-   *
-   * The CLIENT decides retainability: it knows each layout's scoped params (shipped in the bootstrap)
-   * and both the old and new match, so it can tell whether a layout's own prefix changed - without the
-   * server re-matching a path the client already matched.
-   *
-   * It is a HINT, not an instruction. The client is asking to keep data it already holds, which is
-   * harmless for data and unacceptable for a guard, so `runLayoutChain` refuses to skip a gate no
-   * matter what arrives here. Anything unparseable is ignored rather than rejected: the worst case of
-   * a bad hint is a loader that runs when it need not.
-   */
-  const retainedIndices = (header: string | null): ReadonlySet<number> => {
-    if (header === null || header === "") return EMPTY_RETAIN
-    const out = new Set<number>()
-    for (const part of header.split(",")) {
-      // Digits only. `Number("")` is 0 and `Number(" ")` is 0, so a stray comma would otherwise read
-      // as "retain index 0" and silently skip the outermost layout.
-      if (!/^\d+$/.test(part)) continue
-      out.add(Number(part))
-    }
-    return out
-  }
-
-  /**
-   * Validate a data-navigation's retain request against the manifest and its declared source path.
-   * A client may ask to retain every slot it currently has; the server only honours indices whose
-   * layout identity and owned params are unchanged. Hard document GETs never retain anything.
-   */
-  const validatedRetainedIndices = (
-    req: Request,
-    route: RouteEntry,
-    params: Readonly<Record<string, string>>,
-  ): ReadonlySet<number> => {
-    if (req.headers.get(DATA_HEADER) === null) return EMPTY_RETAIN
-    const requested = retainedIndices(req.headers.get(RETAIN_HEADER))
-    const from = req.headers.get(NAV_FROM_HEADER)
-    if (requested.size === 0 || from === null) return EMPTY_RETAIN
-    let fromPath: string
-    try {
-      const current = new URL(req.url)
-      const source = new URL(from, current)
-      if (source.origin !== current.origin) return EMPTY_RETAIN
-      fromPath = source.pathname + source.search
-    } catch {
-      return EMPTY_RETAIN
-    }
-    const previousMatch = matchManifestRoute(fromPath)
-    if (previousMatch === null) return EMPTY_RETAIN
-    const previous = routeById.get(previousMatch.routeId)
-    if (previous === undefined) return EMPTY_RETAIN
-    const valid = new Set<number>()
-    for (const index of requested) {
-      if (route.layoutIds[index] !== previous.layoutIds[index]) continue
-      const owned = route.layoutParams?.[index] ?? []
-      const previouslyOwned = previous.layoutParams?.[index] ?? []
-      if (
-        owned.length !== previouslyOwned.length ||
-        owned.some((name, i) => name !== previouslyOwned[i]) ||
-        owned.some((name) => params[name] !== previousMatch.params[name])
-      ) {
-        continue
-      }
-      valid.add(index)
-    }
-    return valid
-  }
-
-  // The validated (or raw-parsed) search a route's loader context receives; `searchOf` fails closed to
-  // the schema's defaults on hostile input, so this never throws on an attacker-picked query.
-  const loaderSearch = (searchSchema: RouteModule["searchSchema"], request: Request) =>
-    searchOf(searchSchema, urlPartsFor(request).search)
-
-  // The route's EFFECTIVE search once its layout chain is loaded: the layout schemas merged with the
-  // page's (page-wins), the same chain the client mount builds for `useSearch`. Used for the page loader's
-  // `ctx.search` and the render's `RenderProps.search`, so both agree with the client and with each other.
-  const searchChainOf = (
-    layoutMods: LoadedLayoutModules,
-    mod: RouteModule,
-    request: Request,
-  ): Record<string, unknown> =>
-    searchOfChain(
-      [...layoutMods.map((m) => m.searchSchema), mod.searchSchema],
-      urlPartsFor(request).search,
-    )
-
-  const runLayoutChain = async (
-    route: RouteEntry,
-    ctx: LoaderContext,
-    retain: ReadonlySet<number> = new Set(),
-  ): Promise<{
-    readonly modules: LoadedLayoutModules
-    readonly layoutData: readonly unknown[] | undefined
-    readonly retained: readonly number[]
-    readonly pending: Promise<unknown>
-  }> => {
-    const modules = await loadLayoutModules(route)
-    if (!modules.some((m) => m.loader !== undefined)) {
-      // Nothing to run: no array is produced, so a page-only app serializes nothing extra and its
-      // HTML is byte-identical to before this feature.
-      return { modules, layoutData: undefined, retained: [], pending: Promise.resolve() }
-    }
-    const results: unknown[] = new Array(modules.length).fill(null)
-    const retained: number[] = []
-    const pending: Array<Promise<void>> = []
-    for (let i = 0; i < modules.length; i++) {
-      const loader = modules[i]?.loader
-      if (loader === undefined) continue
-      // Unchanged scope: the client keeps what it has. A GATE is never skipped - it is a guard, and a
-      // guard that only runs when the URL prefix changed is not a guard.
-      if (retain.has(i) && modules[i]?.gate !== true) {
-        retained.push(i)
-        continue
-      }
-      const scoped: LoaderContext = {
-        ...ctx,
-        params: scopeParams(ctx.params, route.layoutParams?.[i]),
-      }
-      if (modules[i]?.gate === true) {
-        // Blocking: awaited here, so a throw propagates before anything deeper is started.
-        try {
-          results[i] = await loader(scoped)
-        } catch (err) {
-          throw tagLayoutError(err, route.layoutIds[i] as string)
-        }
-        continue
-      }
-      const layoutId = route.layoutIds[i] as string
-      const index = i
-      // The loader is invoked INSIDE the async function, not before it. `Promise.resolve(loader(x))`
-      // would let a synchronously-throwing loader escape past the rejection handler entirely - the
-      // exception happens while evaluating the argument, before any promise exists to reject.
-      pending.push(
-        (async () => {
-          try {
-            results[index] = await loader(scoped)
-          } catch (err) {
-            throw tagLayoutError(err, layoutId)
-          }
-        })(),
-      )
-    }
-    return { modules, layoutData: results, retained, pending: Promise.all(pending) }
+  for (const route of manifest.routes) {
+    app.register("GET", route.pattern, undefined, pageExecutor.get(route))
+    app.register("POST", route.pattern, undefined, pageExecutor.post(route))
   }
-
-  /** Run only blocking layout gates before a route action. Non-gate loaders fetch render data and
-   * therefore run after the mutation when a native POST needs a fresh document. */
-  const runLayoutGates = async (
-    route: RouteEntry,
-    ctx: LoaderContext,
-  ): Promise<LoadedLayoutModules> => {
-    const modules = await loadLayoutModules(route)
-    for (let i = 0; i < modules.length; i++) {
-      const mod = modules[i]
-      if (mod?.gate !== true || mod.loader === undefined) continue
-      try {
-        await mod.loader({
-          ...ctx,
-          params: scopeParams(ctx.params, route.layoutParams?.[i]),
+  // llms.txt & llms-full.txt describe what a visitor can reach: the pages, and the backend only when it
+  // is served over HTTP - a backend the loaders call in-process has no public surface to describe. An
+  // app route at either path takes precedence, and each text is built once per app.
+  if (options.llmsTxt !== false) {
+    const llmsOptions = { includeLocalGuidelines: options.publishLocalGuidelines === true }
+    const publicApi = mountedApi !== undefined && apiPrefix !== "" ? api : undefined
+    for (const [path, full] of [
+      ["/llms.txt", false],
+      ["/llms-full.txt", true],
+    ] as const) {
+      if (ownPatterns.has(path)) continue
+      let text: Promise<string> | undefined
+      app.register("GET", path, undefined, async () => {
+        text ??= generateLlmsTxt(full, manifest.routes, publicApi, llmsOptions).catch((error) => {
+          text = undefined
+          throw error
         })
-      } catch (err) {
-        throw tagLayoutError(err, route.layoutIds[i] as string)
-      }
-    }
-    return modules
-  }
-
-  // Build a route's render chain + its merged `<head>` from the already-loaded layout modules + the
-  // page module. The chain is `[…layout components, page]`; the head merges each layout's `meta`
-  // export (outermost→innermost) with the page's (last), so a `head`/`meta` on `_layout.tsx`
-  // contributes sitewide tags. `metaArgs` (loader data + params) feed function-form `meta`s.
-  const resolveChainAndHead = (
-    layoutModules: LoadedLayoutModules,
-    page: RouteModule,
-    metaArgs: MetaArgs,
-  ): { chain: unknown[]; head: Meta } => {
-    const chain = [...layoutModules.map((m) => m.default), page.default]
-    const heads = [
-      ...layoutModules.map((m) => resolveMeta(m.meta, metaArgs)),
-      resolveMeta(page.meta, metaArgs),
-    ]
-    return { chain, head: mergeHeads(heads) }
-  }
-
-  // Dir a special-file id lives in: `_error`→"" , `a/b/_error`→"a/b" (and likewise for `_layout`).
-  const dirOfId = (id: string, suffix: string): string =>
-    id === suffix ? "" : id.slice(0, id.length - suffix.length - 1)
-
-  /**
-   * Choose the `_error` boundary for a failure, respecting where a LAYOUT loader failed.
-   *
-   * A route error uses the nearest boundary, as it always has. A layout error must not: the nearest
-   * boundary can sit BELOW the layout that threw, and rendering there would wrap the boundary in that
-   * very layout - the one whose loader just failed and whose data therefore never arrived.
-   */
-  const boundaryFor = (route: RouteEntry, err: unknown): string | undefined => {
-    const ids = route.errorIds ?? []
-    const failing = layoutErrorId(err)
-    if (failing === undefined) return ids.at(-1)
-    const layoutDir = dirOfId(failing, "_layout")
-    // Deepest boundary at or ABOVE the failing layout's directory.
-    for (let i = ids.length - 1; i >= 0; i--) {
-      const errDir = dirOfId(ids[i] as string, "_error")
-      if (errDir === "" || errDir === layoutDir || layoutDir.startsWith(`${errDir}/`)) return ids[i]
-    }
-    return undefined
-  }
-
-  // The request's origin (scheme + host + port, NO trailing slash) - the one server fact `meta()` needs
-  // for absolute `canonical`/`og:url`/`og:image` but can't otherwise see (it also runs on the client).
-  // `URL.origin` is exactly that shape; it matches the browser's `location.origin` for the same URL, so
-  // a soft-nav's `applyHead` resolves an identical `<head>` (no hydration drift). A malformed `req.url`
-  // (shouldn't happen on a real request) degrades to `""` - the documented unknown-origin default -
-  // rather than throwing during render.
-  const originOf = (req: Request): string => {
-    try {
-      return new URL(req.url).origin
-    } catch {
-      return ""
-    }
-  }
-
-  // The request's `pathname + search` - threaded into `renderPage` so an adapter's `useLocation`/
-  // `useSearchParams` render the current URL server-side and hydrate against the client's initial state
-  // (which the client entry seeds from `location.pathname + location.search`). No hash: it never reaches
-  // the server. A malformed `req.url` degrades to "/" rather than throwing during render.
-  const pathOf = (req: Request): string => {
-    try {
-      const parts = urlPartsFor(req)
-      return parts.pathname + parts.search
-    } catch {
-      return "/"
+        return new Response(await text, {
+          headers: { "content-type": "text/plain; charset=utf-8" },
+        })
+      })
     }
   }
 
-  /**
-   * Render the **nearest `_error` boundary** when a route's loader throws (the agnostic, server-side
-   * half of error UI - works on every adapter, no client takeover). The boundary renders in place of
-   * the page, wrapped by the layouts **at or above** its segment (deeper layouts are dropped). It's
-   * served **non-hydrated** at status 500: a terminal page, and rendering a boundary (not the page the
-   * client maps this route to) would otherwise hydrate-mismatch. The component receives `{ name,
-   * message }` - never the stack (no internals leak into HTML).
-   */
-  const renderError = async (
-    route: RouteEntry,
-    errorId: string,
-    err: unknown,
-  ): Promise<Response | RenderedPage> => {
-    const errDir = dirOfId(errorId, "_error")
-    const keptLayoutIds = route.layoutIds.filter((id) => {
-      const ld = dirOfId(id, "_layout")
-      return ld === "" || ld === errDir || errDir.startsWith(`${ld}/`)
-    })
-    const layouts = await Promise.all(
-      keptLayoutIds.map((id) =>
-        (manifest.layouts[id] as LayoutEntry).load().then((m) => m.default),
-      ),
+  if (prerenderedList !== undefined) {
+    const { body, version } = prerenderedList
+    app.register(
+      "GET",
+      PRERENDERED_LIST_PATH,
+      undefined,
+      (c: { readonly req: Request }) =>
+        new Response(body, {
+          headers: {
+            "content-type": "application/json",
+            // Only the versioned URL pages hand over is immutable; a bare request gets today's list.
+            "cache-control":
+              new URL(c.req.url).searchParams.get("v") === version
+                ? "public, max-age=31536000, immutable"
+                : "no-cache",
+          },
+        }),
     )
-    const { default: errComp } = await (manifest.errors?.[errorId] as LayoutEntry).load()
-    const e = err instanceof Error ? err : new Error(String(err))
-    return renderPageResult({
-      adapter,
-      chain: [...layouts, errComp],
-      data: { name: e.name, message: e.message },
-      clientEntry,
-      routeId: errorId,
-      status: 500,
-      hydrate: false,
-      ...titleOption,
-    })
-  }
-
-  // The 404 response - the `_404` page (status 404) or a plain-text fallback. Shared by the wildcard
-  // catch-all (unmatched paths) and the `fallback: "404"` enforcement (unlisted paths under a route
-  // that opted out of on-demand SSR).
-  const renderNotFound = (path?: string): Promise<Response | RenderedPage> =>
-    renderTerminalStatus(404, path)
-
-  /**
-   * Render a terminal-status page: the `_<status>` page if the app authored one, else `_404`, else
-   * plain text. Shared by the wildcard catch-all, `fallback: "404"` enforcement, and a loader's
-   * `notFound()` / `gone()` / `statusPage()`, so all of them resolve the page and set the status
-   * through one path rather than forking.
-   *
-   * Hydrates, following the `_404` precedent rather than `_error`'s non-hydrated 500: these are
-   * ordinary pages the client router can own, and a 404 arrived at by clicking a link should behave
-   * like any other route.
-   */
-  const renderTerminalStatus = async (
-    status: number,
-    path?: string,
-    extraHeaders?: HeadersLike,
-  ): Promise<Response | RenderedPage> => {
-    const page = manifest.statusPages?.[String(status)] ?? manifest.notFound
-    if (page === undefined) {
-      const headers = new Headers(extraHeaders)
-      headers.set("content-type", "text/plain; charset=utf-8")
-      return new Response(STATUS_TEXT[status] ?? "Error", { status, headers })
-    }
-    // The routeId decides which preload/style bundle and which client component this maps to, so it
-    // must name the page actually rendered - `_410` when `_410.tsx` exists, `_404` when it fell back.
-    const routeId = manifest.statusPages?.[String(status)] !== undefined ? `_${status}` : "_404"
-    const loaded = (await page.load()) as {
-      readonly default: unknown
-      readonly searchSchema?: RouteModule["searchSchema"]
-    }
-    const component = loaded.default
-    return renderPageResult({
-      adapter,
-      chain: [component],
-      data: null,
-      clientEntry,
-      routeId,
-      // The page hydrates, so besides `path` its SSR `search` must equal the client mount's derivation for
-      // this routeId (`searchOf(searchSchema, url.search)`), or a status page reading `useSearch` drifts.
-      // Only when `path` is present (a real URL); a schema-less status page then gets the raw parsed query.
-      ...(path !== undefined
-        ? {
-            search: searchOf(
-              loaded.searchSchema,
-              path.includes("?") ? path.slice(path.indexOf("?")) : "",
-            ),
-          }
-        : {}),
-      // The page hydrates, so its SSR `path` must equal the client's initial
-      // `location.pathname+search` (an unmatched path yields no params → `{}`), or a `useLocation`
-      // on it would drift.
-      ...(path !== undefined ? { path } : {}),
-      status,
-      ...(extraHeaders !== undefined ? { headers: extraHeaders } : {}),
-      ...preloadOf(routeId),
-      ...stylesOf(routeId),
-      prerenderedPaths: options.prerenderedPaths ?? [],
-      ...titleOption,
-    })
   }
 
-  /**
-   * Answer a loader's terminal-status signal, in whichever form the caller asked for.
-   *
-   * A hard navigation wants the document, so it gets the rendered boundary. A client-side navigation
-   * fetched DATA, not a document, so it gets an empty body plus the status on `X-Nifra-Status`, and
-   * the client router renders the same boundary from its own manifest. Sending the HTML back to a
-   * soft-nav would be answering a different question than the one asked - and skipping the header
-   * entirely is what leaves a crawler seeing a correct 404 while a user who clicked a link sees a
-   * blank page.
-   */
-  const renderStatusSignal = (
-    req: Request,
-    signal: StatusSignal,
-  ): Promise<Response | RenderedPage> | Response => {
-    const { status, headers } = signal[STATUS_SIGNAL]
-    if (req.headers.get(DATA_HEADER) !== null) {
-      const responseHeaders = new Headers(headers)
-      responseHeaders.set(STATUS_HEADER, String(status))
-      return new Response(null, { status, headers: responseHeaders })
-    }
-    return renderTerminalStatus(status, pathOf(req), headers)
-  }
+  // Wildcard catch-all: unmatched paths render the nearest `_404` (404), or a plain text 404 if
+  // absent.
+  app.register("GET", "/*", undefined, pageExecutor.fallback)
 
-  for (const route of manifest.routes) {
-    // A dynamic route whose `getStaticPaths` declared `fallback: "404"` - only its prerendered paths
-    // exist; anything else 404s (computed once per route, not per request).
-    const is404Fallback = options.staticFallbacks?.[route.pattern] === "404"
-    // Per-route document-assembly cache (see RenderAssemblyCache): filled on the first GET render and
-    // reused while the route + layout MODULE IDENTITIES are unchanged. Attached only when every meta
-    // in the chain is static - a `meta(data)` function makes the head per-request, so those routes
-    // always assemble fresh. A module reload (dev HMR) yields new module objects, dropping the slot.
-    let assemblySlot: RenderAssemblyCache | undefined
-    let assemblySlotMod: unknown
-    let assemblySlotLayouts: LoadedLayoutModules | undefined
-    const assemblyCacheFor = (
-      mod: RouteModule,
-      lms: LoadedLayoutModules,
-    ): { assemblyCache: RenderAssemblyCache } | Record<string, never> => {
-      if (typeof mod.meta === "function") return {}
-      for (const m of lms) if (typeof m.meta === "function") return {}
-      const layoutsUnchanged =
-        assemblySlotLayouts !== undefined &&
-        assemblySlotLayouts.length === lms.length &&
-        assemblySlotLayouts.every((m, i) => m === lms[i])
-      if (assemblySlotMod !== mod || !layoutsUnchanged) {
-        assemblySlot = {}
-        assemblySlotMod = mod
-        assemblySlotLayouts = lms
-      }
-      return { assemblyCache: assemblySlot as RenderAssemblyCache }
+  let evidenceComposing = false
+  const evidenceProvider: BackendEvidenceProvider = async () => {
+    if (evidenceComposing) {
+      throw new Error("[nifra/web] cyclic composed assurance evidence mount")
     }
-    app.register("GET", route.pattern, undefined, async (c: RouteContext) => {
-      // Enforce `fallback: "404"` before any work: an unlisted path under this route doesn't exist.
-      // Covers hard navigation directly; a client soft-nav's data fetch gets the 404, throws, and the
-      // history layer falls back to a full-page navigation (which lands here again, as a document).
-      if (is404Fallback && !prerenderedSet.has(urlPartsFor(c.req).pathname)) {
-        return renderNotFound(pathOf(c.req))
-      }
-      const mod = await route.load()
-      const draft = await draftFlag(c.req)
-      let data: unknown
-      let layoutData: readonly unknown[] | undefined
-      let boundaryStates: BoundaryStates | undefined
-      let layoutModules: LoadedLayoutModules | undefined
-      let layoutRetained: readonly number[] = []
-      try {
-        const ctx = {
-          params: c.params,
-          request: c.req,
-          req: c.req,
-          api,
-          env: c.env,
-          draft,
-          search: loaderSearch(mod.searchSchema, c.req),
-        }
-        // Layout loaders run for BOTH the document and the data-only request. A gate that only ran on
-        // the document path would be bypassed by adding the data header, which is exactly the request
-        // a client navigation makes - a guard has to hold on the path an attacker can pick.
-        //
-        // `runLayoutChain` returns once every GATE has resolved, with the non-gate loaders still in
-        // flight. So the page loader starts as late as correctness requires and as early as speed
-        // allows, and both are awaited together below.
-        const run = await runLayoutChain(
-          route,
-          ctx,
-          validatedRetainedIndices(c.req, route, c.params),
-        )
-        layoutModules = run.modules
-        layoutRetained = run.retained
-        const boundaryDefinitions = [
-          ...run.modules.flatMap((layout) => layout.boundaries ?? []),
-          ...(mod.boundaries ?? []),
-        ]
-        if (boundaryDefinitions.length > 0) boundaryDescriptors(boundaryDefinitions)
-        const effectiveSearch = searchChainOf(run.modules, mod, c.req)
-        const boundaryBatch =
-          boundaryDefinitions.length === 0
-            ? undefined
-            : startDynamicBoundaries(boundaryDefinitions, {
-                request: c.req,
-                params: c.params,
-                api,
-                env: c.env,
-                draft,
-                search: effectiveSearch,
-                signal: c.req.signal,
-              } satisfies BoundaryRequestCtx)
-        const staticBoundaryPromise =
-          boundaryDefinitions.length === 0
-            ? Promise.resolve(undefined)
-            : resolveStaticBoundaries(
-                boundaryDefinitions,
-                { phase: "build", origin: originOf(c.req) },
-                options.staticBoundaryCache,
-              )
-        // Boundary data is attached as one Deferred marker per slot. The shell can render
-        // immediately with each slot pending, while the existing deferred protocol emits the first
-        // completed sibling independently instead of waiting for the slowest boundary.
-        // The page loader gets the EFFECTIVE search (layout chain + page, page-wins), now that the layout
-        // modules are loaded - so `ctx.search` includes a layout's shared keys (`?org`), matching `useSearch`.
-        const [pageData, , staticBoundaries] = await Promise.all([
-          mod.loader ? mod.loader({ ...ctx, search: effectiveSearch }) : null,
-          run.pending, // a non-gate layout loader that rejects must still surface, not go unhandled
-          staticBoundaryPromise,
-        ])
-        data = pageData
-        layoutData = run.layoutData
-        if (boundaryBatch !== undefined) {
-          const streamed = { ...boundaryBatch.initial, ...(staticBoundaries ?? {}) }
-          for (const entry of boundaryBatch.pending) {
-            const initial = streamed[entry.name]
-            if (initial !== undefined)
-              streamed[entry.name] = { ...initial, data: defer(entry.promise) }
-          }
-          boundaryStates = streamed
-        } else if (staticBoundaries !== undefined) {
-          boundaryStates = staticBoundaries
-        }
-      } catch (err) {
-        // A terminal-status signal (`notFound()` / `gone()` / `statusPage(n)`) renders a boundary at
-        // that status. Checked BEFORE the pass-through below: a signal IS a `Response`, so the order
-        // is what keeps a hand-rolled `throw new Response(...)` served verbatim, as it always was.
-        if (isStatusSignal(err)) return renderStatusSignal(c.req, err)
-        // A thrown control-flow signal (a guard's `redirect(...)`, an explicit error response) - let
-        // it propagate to core, which renders it as-is, whether it is a plain render or a
-        // hand-rolled `Response`. Real errors render the nearest `_error` boundary, if any; with
-        // none, rethrow (unchanged 500 behavior).
-        if (isControlFlow(err)) throw err
-        // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
-        if (options.onLoaderError !== undefined) {
-          try {
-            options.onLoaderError(err, { request: c.req, params: c.params, route: route.pattern })
-          } catch {
-            // A faulty reporter must never break error rendering.
-          }
-        }
-        const errorId = boundaryFor(route, err)
-        if (errorId === undefined) throw err
-        // A soft-nav data fetch can't render a boundary - 500 so the client falls back to a full-page
-        // navigation, which lands here as a document and renders the `_error` page.
-        if (c.req.headers.get(DATA_HEADER) !== null) {
-          return new Response("Internal Server Error", {
-            status: 500,
-            headers: { "content-type": "text/plain; charset=utf-8" },
-          })
-        }
-        return renderError(route, errorId, withDuplicateInstanceHint(err))
-      }
-      // A loader may RETURN its control-flow signal instead of throwing it - `return redirect(...)`
-      // reads naturally and must not silently serialize the signal as loader data. Mirror the catch
-      // above exactly: a status signal renders its boundary, any other signal (a redirect, a
-      // hand-rolled response) passes through to core verbatim - so return and throw are
-      // interchangeable.
-      if (isStatusSignal(data)) return renderStatusSignal(c.req, data)
-      if (isControlFlow(data)) return data
-      // Client-side navigation asks (via the X-Nifra-Data header) for just the loader data - no full
-      // document, no layout chain. A route with deferred data streams NDJSON (critical data first,
-      // then each deferred value as it settles); otherwise one JSON (the fast path). Same loader,
-      // same auth - only the transport differs.
-      if (c.req.headers.get(DATA_HEADER) !== null) {
-        const pageSplit = prepareDeferred(data)
-        const layoutSplits: Array<ReturnType<typeof prepareDeferred>> = []
-        let offset = pageSplit.deferred.length
-        for (const entry of layoutData ?? []) {
-          const split = prepareDeferred(entry, offset)
-          layoutSplits.push(split)
-          offset += split.deferred.length
-        }
-        const deferred = [...pageSplit.deferred, ...layoutSplits.flatMap((split) => split.deferred)]
-        const boundarySplit =
-          boundaryStates === undefined
-            ? undefined
-            : prepareDeferred(boundaryStates, deferred.length)
-        const allDeferred = [
-          ...deferred,
-          ...(boundarySplit === undefined ? [] : boundarySplit.deferred),
-        ]
-        const payload =
-          layoutData === undefined && boundarySplit === undefined
-            ? pageSplit.forClient
-            : {
-                v: 1 as const,
-                data: pageSplit.forClient,
-                layoutData: layoutSplits.map((split) => split.forClient),
-                retained: layoutRetained,
-                ...(boundarySplit === undefined ? {} : { boundaries: boundarySplit.forClient }),
-              }
-        // Bare value when there is no layout data - the pre-envelope shape, so a client running older
-        // code against a newer server keeps working.
-        if (allDeferred.length === 0) {
-          return Response.json(payload ?? null)
+    evidenceComposing = true
+    try {
+      const { composeProjectEvidence, snapshotProjectEvidence } = await import(
+        "@nifrajs/core/evidence"
+      )
+      const parts: Array<{
+        readonly evidence: import("@nifrajs/core/evidence").ProjectEvidenceSnapshot
+        readonly pathPrefix?: string
+      }> = [{ evidence: snapshotProjectEvidence(app) }]
+      for (const mount of configuredMounts) {
+        const provider = evidenceProviderOf(mount.app)
+        if (provider === undefined) {
+          // A declared opaque mount reaches the snapshot as a known gap, through this app's own
+          // mount reflection above.
+          if (mount.opaque !== undefined) continue
+          throw new Error(
+            `[nifra/web] cannot compose assurance evidence: mount "${mount.path}" has no token-only evidence provider - declare why it is not analyzed with { opaque: "<reason>" }`,
+          )
         }
-        return new Response(ndjsonStream(payload, allDeferred), {
-          headers: { "content-type": "application/x-ndjson; charset=utf-8" },
+        parts.push({
+          evidence: await provider.call(mount.app),
+          ...(mount.stripPrefix === true ? { pathPrefix: mountPathPrefix(mount.path) } : {}),
         })
       }
-      const chainLayoutModules = layoutModules ?? (await loadLayoutModules(route))
-      const { chain, head } = resolveChainAndHead(chainLayoutModules, mod, {
-        data,
-        params: c.params,
-        origin: originOf(c.req),
-      })
-      const hydrateRoute = mod.hydrate !== false
-      try {
-        // `await` so a shell-render throw (renderToStream rejects before any byte) is caught here and
-        // can render the `_error` page - not just a loader throw. Mid-stream (post-shell) throws can't
-        // be recovered to a full page; the per-adapter client boundary catches client render errors.
-        return await renderPageResult({
-          adapter,
-          chain,
-          data,
-          head,
-          clientEntry,
-          routeId: route.id,
-          params: c.params,
-          path: pathOf(c.req),
-          // The effective (layout chain + page) search, matching the page loader's `ctx.search` above and
-          // the client mount - so `useSearch` renders SSR-correct and hydrates with no drift. `layoutModules`
-          // is loaded by now (the loader try succeeded to reach here).
-          search: searchChainOf(layoutModules ?? [], mod, c.req),
-          hydrate: hydrateRoute,
-          ...(layoutData !== undefined ? { layoutData } : {}),
-          ...(boundaryStates !== undefined ? { boundaries: boundaryStates } : {}),
-          ...preloadOf(route.id),
-          ...stylesOf(route.id),
-          prerenderedPaths: options.prerenderedPaths ?? [],
-          ...(mod.revalidate !== undefined ? { revalidate: mod.revalidate } : {}),
-          ...(mod.revalidateTags !== undefined ? { revalidateTags: mod.revalidateTags } : {}),
-          ...(mod.islandScripts !== undefined ? { islandScripts: mod.islandScripts } : {}),
-          ...titleOption,
-          ...assemblyCacheFor(mod, chainLayoutModules),
-        })
-      } catch (err) {
-        // Same precedence as the loader catch above - a `meta()` may signal too.
-        if (isStatusSignal(err)) return renderStatusSignal(c.req, err)
-        if (isControlFlow(err)) throw err
-        // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
-        if (options.onLoaderError !== undefined) {
-          try {
-            options.onLoaderError(err, { request: c.req, params: c.params, route: route.pattern })
-          } catch {
-            // A faulty reporter must never break error rendering.
-          }
+      if (mountedApi !== undefined && apiPrefix !== "") {
+        const provider = evidenceProviderOf(api)
+        if (provider === undefined) {
+          throw new Error(
+            `[nifra/web] cannot compose assurance evidence: auto-mounted API at "${apiPrefix}" has no token-only evidence provider`,
+          )
         }
-        const errorId = boundaryFor(route, err)
-        if (errorId === undefined) throw err
-        return renderError(route, errorId, withDuplicateInstanceHint(err))
-      }
-    })
-
-    // POST runs the route's `action` (mutation). A control-flow return (e.g. a `redirect(...)`)
-    // passes straight through; a data return re-renders the page (the loader re-runs for fresh
-    // data) with `actionData`. Routes without an action reject POST with 405 - not a stray 404.
-    app.register("POST", route.pattern, undefined, async (c: RouteContext) => {
-      const mod = await route.load()
-      const draft = await draftFlag(c.req)
-      if (mod.action === undefined) {
-        return new Response("Method Not Allowed", {
-          status: 405,
-          headers: { allow: "GET", "content-type": "text/plain; charset=utf-8" },
-        })
-      }
-      const actionContext = {
-        params: c.params,
-        request: c.req,
-        req: c.req,
-        api,
-        env: c.env,
-        draft,
-        search: loaderSearch(mod.searchSchema, c.req),
-      }
-      const isDataRequest = c.req.headers.get(DATA_HEADER) !== null
-      let layoutModules: LoadedLayoutModules
-      let result: unknown
-      try {
-        // A gate is an authorization boundary for everything beneath its layout, mutations included.
-        // Run only gates before the action; ordinary layout data loaders run after a native mutation.
-        layoutModules = await runLayoutGates(route, actionContext)
-        result = await mod.action(actionContext)
-      } catch (err) {
-        // A THROWN signal is the same control flow as a returned one (`throw redirect()` in a gate
-        // or an action) - route it through the same conversion as the returned branch below, so
-        // throw and return are interchangeable on the mutation path too.
-        if (isControlFlow(err)) return actionResponse(err, isDataRequest)
-        throw err
-      }
-      // An action may wrap its data in `revalidate(paths, data)` to declare which routes it changed.
-      // Unwrap to the inner data; the paths ride the `X-Nifra-Revalidate` header on the data-mode
-      // responses (the client acts on them - a full-page POST re-runs loaders inline, so no header).
-      const isRevalidate =
-        result !== null && typeof result === "object" && "__nifraRevalidate" in result
-      const actionResult = isRevalidate ? (result as RevalidateResult<unknown>).data : result
-      const revalidateHeader: Record<string, string> = isRevalidate
-        ? { [REVALIDATE_HEADER]: (result as RevalidateResult<unknown>).__nifraRevalidate.join(",") }
-        : {}
-      if (isControlFlow(actionResult)) return actionResponse(actionResult, isDataRequest)
-      // Client submit wants just the action's data (it revalidates the loader itself); a native
-      // form POST re-renders the full page (loader re-runs) with the action data.
-      if (isDataRequest) {
-        // An action may `defer()` slow parts of its result - stream them (critical data first, then
-        // each deferred as it settles) exactly like a loader; a non-deferred action returns one JSON.
-        const { forClient, deferred } = prepareDeferred(actionResult)
-        if (deferred.length === 0)
-          return Response.json(actionResult ?? null, { headers: revalidateHeader })
-        return new Response(ndjsonStream(forClient, deferred), {
-          headers: { "content-type": "application/x-ndjson; charset=utf-8", ...revalidateHeader },
+        parts.push({
+          evidence: await provider.call(api),
+          ...(apiStrip ? { pathPrefix: mountPathPrefix(apiPrefix) } : {}),
         })
       }
-      // Derived once and shared: the loader's `ctx.search` and the render's `RenderProps.search` are the
-      // SAME effective (layout chain + page) value, and the client mount rebuilds it identically. The
-      // layout modules are already loaded (the action ran through their gates above).
-      const search = searchChainOf(layoutModules, mod, c.req)
-      const data = mod.loader
-        ? await mod.loader({
-            params: c.params,
-            request: c.req,
-            req: c.req,
-            api,
-            env: c.env,
-            draft,
-            search,
-          })
-        : null
-      const { chain, head } = resolveChainAndHead(layoutModules, mod, {
-        data,
-        params: c.params,
-        origin: originOf(c.req),
-      })
-      const hydrateRoute = mod.hydrate !== false
-      // A full-page POST streams the action's `defer()`'d parts mid-document behind `<Await>` too -
-      // `renderPage` splits `actionData` like loader data (works with JS off; hydrates after).
-      return renderPageResult({
-        adapter,
-        chain,
-        data,
-        actionData: actionResult,
-        head,
-        clientEntry,
-        routeId: route.id,
-        params: c.params,
-        path: pathOf(c.req),
-        search,
-        hydrate: hydrateRoute,
-        ...preloadOf(route.id),
-        ...stylesOf(route.id),
-        prerenderedPaths: options.prerenderedPaths ?? [],
-        ...titleOption,
-      })
-    })
+      return composeProjectEvidence(parts)
+    } finally {
+      evidenceComposing = false
+    }
   }
-
-  // Register llms.txt & llms-full.txt
-  const llmsOptions = { includeLocalGuidelines: options.publishLocalGuidelines === true }
-  app.register("GET", "/llms.txt", undefined, async () => {
-    const text = await generateLlmsTxt(false, manifest.routes, api, llmsOptions)
-    return new Response(text, {
-      headers: { "content-type": "text/plain; charset=utf-8" },
-    })
+  Object.defineProperty(app, NIFRA_BACKEND_EVIDENCE, {
+    configurable: false,
+    enumerable: false,
+    value: evidenceProvider,
+    writable: false,
   })
 
-  app.register("GET", "/llms-full.txt", undefined, async () => {
-    const text = await generateLlmsTxt(true, manifest.routes, api, llmsOptions)
-    return new Response(text, {
-      headers: { "content-type": "text/plain; charset=utf-8" },
-    })
-  })
+  return app
+}
 
-  // Wildcard catch-all: unmatched paths render `_404` (404), or a plain text 404 if absent.
-  app.register("GET", "/*", undefined, (c: RouteContext) => renderNotFound(pathOf(c.req)))
+/** Resolve one composed, token-only evidence snapshot for a web app and its mounted surfaces. */
+export async function webProjectEvidence(
+  source: unknown,
+): Promise<import("@nifrajs/core/evidence").ProjectEvidenceSnapshot> {
+  const provider = evidenceProviderOf(source)
+  if (provider === undefined) {
+    throw new TypeError("webProjectEvidence(): expected an app created by createWebApp")
+  }
+  return provider.call(source)
+}
 
-  return app
+// Up to this many characters of JSON, the prerendered set rides inline in each page's handover.
+const INLINE_PRERENDERED_CHARS = 4096
+
+/** The prerendered set as a served, content-versioned list, when it is too large to inline. */
+function servedPrerenderedList(
+  paths: readonly string[] | undefined,
+): { readonly body: string; readonly version: string; readonly url: string } | undefined {
+  if (paths === undefined || paths.length === 0) return undefined
+  const body = JSON.stringify(paths)
+  if (body.length <= INLINE_PRERENDERED_CHARS) return undefined
+  // FNV-1a: a version that changes with the list is all the URL needs; a stale cached list only
+  // costs a fallback to the dynamic data request.
+  let hash = 0x811c9dc5
+  for (let i = 0; i < body.length; i++) hash = Math.imul(hash ^ body.charCodeAt(i), 0x01000193)
+  const version = (hash >>> 0).toString(16).padStart(8, "0")
+  return { body, version, url: `${PRERENDERED_LIST_PATH}?v=${version}` }
 }