@nifrajs/web 3.1.0 → 3.2.0

package/src/index.ts

@@ -8,83 +8,6 @@
  * of DOM types: it is pure server orchestration + string building.
  */
 
-import {
-  type BackendMount,
-  type BackendMountHandler,
-  NIFRA_BACKEND_MOUNT,
-} from "@nifrajs/core/mount"
-import {
-  isSameOriginPath,
-  type ResponseResult,
-  type ServerOptions,
-  server,
-  status as statusResult,
-  type UrlParts,
-  urlPartsOf,
-} from "@nifrajs/core/server"
-import type { BoundaryRegistration } from "./boundary.ts"
-import {
-  type BoundaryRequestCtx,
-  type BoundaryStates,
-  boundaryDescriptors,
-  resolveStaticBoundaries,
-  startDynamicBoundaries,
-} from "./boundary.ts"
-import {
-  DEFERRED_ERROR_CODE,
-  DEFERRED_RUNTIME,
-  type Deferred,
-  defer,
-  MAP_DEFERRED_SOURCE,
-  ndjsonStream,
-  prepareDeferred,
-} from "./deferred.ts"
-import { isDraftEnabled } from "./draft.ts"
-import { trustedHeadAttributes } from "./internal/head-attributes.ts"
-// Head resolution/merging. Defined in an internal module so `@nifrajs/web/client` can export the same
-// two functions to the generated client entry without dragging THIS module (and its server code) into
-// the browser graph - see internal/head-merge.ts. Re-exported here so the public API is unchanged.
-import { mergeHeads, resolveMeta } from "./internal/head-merge.ts"
-import { jsStringLiteral } from "./internal/js-string.ts"
-import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.ts"
-import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "./isr.ts"
-import { generateLlmsTxt } from "./llms-txt.ts"
-import type {
-  LayoutEntry,
-  Loader as LayoutLoader,
-  LinkDescriptor,
-  LoaderContext,
-  Manifest,
-  Meta,
-  MetaArgs,
-  MetaDescriptor,
-  MetaInput,
-  RouteEntry,
-  RouteModule,
-  ScriptDescriptor,
-  UnsafeScriptDescriptor,
-} from "./manifest.ts"
-import type { RenderAdapter, RenderProps } from "./render-seam.ts"
-import {
-  ACTION_GLOBAL,
-  BOUNDARY_GLOBAL,
-  DATA_GLOBAL,
-  LAYOUT_DATA_GLOBAL,
-  ROOT_ATTRIBUTE,
-  ROUTE_GLOBAL,
-} from "./render-seam.ts"
-import {
-  createMatcher,
-  DATA_HEADER,
-  NAV_FROM_HEADER,
-  PRERENDERED_GLOBAL,
-  REDIRECT_HEADER,
-  RETAIN_HEADER,
-  REVALIDATE_HEADER,
-  STATUS_HEADER,
-} from "./router.ts"
-import { searchOf, searchOfChain } from "./search.ts"
-
 // Draft / preview mode - a signed cookie that flips `ctx.draft` for loaders + bypasses ISR for editors.
 export {
   assertStaticBoundaryImports,
@@ -113,6 +36,13 @@ export {
   type StaticCtx,
   startDynamicBoundaries,
 } from "./boundary.ts"
+export {
+  assertRenderAdapterConformance,
+  RenderAdapterConformanceError,
+  type RenderAdapterConformanceFixture,
+} from "./conformance.ts"
+// Deferred loader data (`defer()` + the `Deferred<T>` type) - consumed by the adapter's `<Await>`.
+export { type Deferred, defer } from "./deferred.ts"
 export {
   DRAFT_COOKIE,
   type DraftCookieControls,
@@ -132,6 +62,59 @@ export {
   fontFace,
   fontPreload,
 } from "./fonts.ts"
+export {
+  type GenerateClientEntryOptions,
+  type GenerateRouteSearchTypesOptions,
+  type GenerateServerManifestOptions,
+  generateClientEntry,
+  generateRouteSearchTypes,
+  generateServerManifest,
+} from "./internal/codegen.ts"
+// Generated client entries intentionally import the browser router from the client subpath:
+// `import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web/client"`.
+export { mergeHeads, resolveMeta } from "./internal/head-merge.ts"
+export {
+  canonical,
+  gone,
+  jsonLd,
+  notFound,
+  type OpenGraphInput,
+  openGraph,
+  type RedirectOptions,
+  type RenderAssemblyCache,
+  type RenderedPage,
+  type RenderPageInput,
+  type RenderPageOptions,
+  type RevalidateResult,
+  redirect,
+  renderPage,
+  renderPageResult,
+  revalidate,
+  type StatusPageOptions,
+  serializeData,
+  statusPage,
+  unsafeInlineScript,
+} from "./internal/render-document.ts"
+export {
+  DEFAULT_DEV_PORT,
+  PRE_HYDRATION_GUARD,
+  type ServerOnly,
+} from "./internal/runtime-contract.ts"
+/**
+ * The two file-name conventions that decide what never reaches a browser: a `*.server` module is
+ * EMPTIED in the client build, a `*.fn` module is REPLACED with client stubs.
+ *
+ * Exported because more than the bundlers need them. `nifra dev --bun` cannot transform (Bun's dev
+ * bundler takes no plugins) so it must REFUSE instead, and a refusal driven by its own hand-written
+ * glob drifts from the transform - which is how `.fn.mts` came to be stubbed by both build pipelines
+ * and waved through by the guard that exists to stop it leaking. Anything deciding "is this module
+ * server-only" should import the matcher rather than re-encode it.
+ */
+export { SERVER_FN_MODULE, SERVER_ONLY_MODULE } from "./internal/server-boundary.ts"
+export {
+  type CreateWebAppOptions,
+  createWebApp,
+} from "./internal/web-app.ts"
 // ISR (incremental static regeneration): a pluggable cache store + the `withISR` stale-while-revalidate
 // wrapper for rendered SSR responses.
 export {
@@ -234,6 +217,19 @@ export {
   type QueryState,
   type QueryStatus,
 } from "./query.ts"
+export {
+  ACTION_GLOBAL,
+  BOUNDARY_GLOBAL,
+  DATA_GLOBAL,
+  LAYOUT_DATA_GLOBAL,
+  type RenderAdapter,
+  type RenderProps,
+  ROOT_ATTRIBUTE,
+  ROUTE_GLOBAL,
+  type SsrModuleLoader,
+  setSsrModuleLoader,
+  ssrModuleLoader,
+} from "./render-seam.ts"
 // Agnostic client-side router core (pure + DOM-free) - consumed by per-adapter Router bindings.
 // `DATA_HEADER` marks a navigation's data-only GET; `createWebApp` answers it with loader JSON.
 export {
@@ -257,2636 +253,8 @@ export {
   type Submission,
   type SubmitOptions,
 } from "./router.ts"
-// Deferred loader data (`defer()` + the `Deferred<T>` type) - consumed by the adapter's `<Await>`.
-export { type Deferred, defer, mergeHeads, resolveMeta }
-
-/** Phantom brand key for {@link ServerOnly}. A unique symbol so the brand can't be forged by a plain
- * object literal; `unique symbol` keys never appear in the emitted JS, so the brand is purely
- * type-level (zero runtime cost). The property is optional + `never`-typed, so a `ServerOnly<T>`
- * stays assignment-compatible with `T` - it documents intent without obstructing real use. */
-declare const SERVER_ONLY_BRAND: unique symbol
-
-/**
- * Type-level intent marker for a value that must only exist on the server - a secret, a DB handle, a
- * server-only client. `ServerOnly<T>` is structurally `T` (the brand is an optional phantom field, so
- * existing code keeps type-checking), but it advertises to readers + the compiler that the value is
- * not meant to cross to the browser. It is **purely type-level** and erases at build - it does NOT,
- * by itself, keep the value out of the client bundle.
- *
- * The enforcement is two runtime conventions:
- *  - add the side-effect import `import "@nifrajs/web/server-only"` at the top of the module - the
- *    client build ({@link buildClient}) fails loud, with the import chain, if it reaches a browser
- *    chunk (the poison-import marker);
- *  - or name the file `*.server.ts` - the `.server` convention empties it in the client build.
- *
- * Use this brand to express the intent in the types; pair it with one of those runtime markers so a
- * leak is caught at build time rather than shipping a secret to the client.
- *
- * @example
- * import "@nifrajs/web/server-only"
- * import type { ServerOnly } from "@nifrajs/web"
- * export const apiKey: ServerOnly<string> = process.env.SECRET_API_KEY!
- */
-export type ServerOnly<T> = T & { readonly [SERVER_ONLY_BRAND]?: never }
-
-export {
-  assertRenderAdapterConformance,
-  RenderAdapterConformanceError,
-  type RenderAdapterConformanceFixture,
-} from "./conformance.ts"
-export {
-  ACTION_GLOBAL,
-  BOUNDARY_GLOBAL,
-  DATA_GLOBAL,
-  LAYOUT_DATA_GLOBAL,
-  type RenderAdapter,
-  type RenderProps,
-  ROOT_ATTRIBUTE,
-  ROUTE_GLOBAL,
-  type SsrModuleLoader,
-  setSsrModuleLoader,
-  ssrModuleLoader,
-} from "./render-seam.ts"
-
 // The search-derivation primitive: parse a URL query, validate it against a route's `searchSchema`
 // (fail-closed to defaults), or return the raw parsed query when there is none. Both the server (loader
 // ctx + `renderPage`) and a client adapter mount call this with the same URL + schema, so the two sides
 // produce the identical value by construction. An adapter's `useSearch` binding reads its result.
 export { type SearchOf, searchOf, searchOfChain, serializeSearch } from "./search.ts"
-
-/**
- * Pre-hydration form guard - a tiny inline script flushed in `<head>` (it runs in the window between
- * first paint and the island bundle taking over). It neutralizes the one real hydration footgun: a
- * JS-only form (a hand-wired `onSubmit` with no native fallback) submitting *natively* before its
- * handler is attached, which navigates the browser to a broken `?field=…` GET of the current page.
- *
- * It blocks ONLY that shape - an effective-GET form whose action targets the current document - and
- * only until hydration commits (`data-nifra-hydrated`, set by the client entry). Method-`post` forms
- * (progressive enhancement: the native POST hits the route `action`) and GET forms with a real action
- * (a search box → `/search`) pass through untouched. Opt out per-form with `data-native`. Static text
- * (no interpolation), so it can't carry injected markup. See the Hydration guide.
- */
-export const PRE_HYDRATION_GUARD =
-  "(function(){addEventListener('submit',function(e){var f=e.target;" +
-  "if(!f||f.tagName!=='FORM'||f.hasAttribute('data-native'))return;" +
-  "if(document.documentElement.hasAttribute('data-nifra-hydrated'))return;" +
-  "var m=(f.getAttribute('method')||'get').toLowerCase();if(m==='post')return;" +
-  "var a=f.getAttribute('action');" +
-  "if(!a||a===''||a==='#'||a===location.pathname||a===location.href)e.preventDefault()" +
-  "},true)})()"
-
-/**
- * The single default port for the dev server (`@nifrajs/web/dev`, `@nifrajs/web/vite`) **and**
- * `nifra start`. Deliberately uncommon: `3000`/`5173`/`8080` collide with whatever else is running
- * (Next, Vite, a stray Node API). `4321` rarely is - and being the *same* constant across `nifra dev`
- * and `nifra start` means a project's URL doesn't change between commands. Override per-run with
- * `--port <n>` or the `PORT` env var. */
-export const DEFAULT_DEV_PORT = 4321
-
-// Shared, stateless - allocated once at module load, not per render/stream.
-const TEXT_ENCODER = new TextEncoder()
-
-type MaybePromise<T> = T | Promise<T>
-
-// XSS-safe `<script>` JSON escaping in a SINGLE pass: `<`/`>` would break out of the
-// script element; U+2028/U+2029 are valid JSON but historically break JS string literals. Built via
-// fromCharCode so no raw separator chars live in this source. One regex + one output string replaces
-// the prior four sequential `replaceAll` full-string passes.
-const LINE_SEP = String.fromCharCode(0x2028)
-const PARA_SEP = String.fromCharCode(0x2029)
-const SCRIPT_ESCAPE = new RegExp(`[<>${LINE_SEP}${PARA_SEP}]`, "g")
-const SCRIPT_ESCAPE_MAP: Readonly<Record<string, string>> = {
-  "<": "\\u003c",
-  ">": "\\u003e",
-  [LINE_SEP]: "\\u2028",
-  [PARA_SEP]: "\\u2029",
-}
-const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body")
-const RESPONSE_RESULT = Symbol.for("nifra.response.result")
-
-/**
- * A control-flow value that renders as plain data - what `redirect()` returns, and what core's
- * `status(...)` returns. Recognized here rather than imported: core keeps its own predicate internal,
- * and the registry symbol is the contract between them (two copies of core must still agree).
- */
-const isResponseResult = (value: unknown): value is ResponseResult =>
-  typeof value === "object" &&
-  value !== null &&
-  (value as { readonly [RESPONSE_RESULT]?: unknown })[RESPONSE_RESULT] === true &&
-  typeof (value as { readonly toResponse?: unknown }).toResponse === "function"
-
-/** A returned/thrown value that ends the request as-is: either shape of control-flow signal. */
-const isControlFlow = (value: unknown): value is Response | ResponseResult =>
-  value instanceof Response || isResponseResult(value)
-
-export interface RenderedPage {
-  readonly [RESPONSE_RESULT]: true
-  toResponse(): Response
-  toNodeBody?(): {
-    readonly status: number
-    readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
-    readonly body: string | Uint8Array
-  }
-}
-
-export interface RenderPageOptions {
-  readonly adapter: RenderAdapter
-  /** The layout chain to render - outermost layout → page (opaque; the adapter renders it). */
-  readonly chain: readonly unknown[]
-  /** The loader output for this request. */
-  readonly data: unknown
-  /** An action's data return (POST only) - surfaced to the page as `actionData` + serialized
-   * for the client so post-POST hydration matches. Omit on GETs. */
-  readonly actionData?: unknown
-  /**
-   * URL of the built client entry (loaded as a module script).
-   *
-   * Optional ONLY on a `hydrate: false` page, where there is no client takeover to feed and this value
-   * reaches no output at all. The union below is what enforces that: omitting it on a hydrating page
-   * stays a compile error rather than rendering `src=""`.
-   */
-  readonly clientEntry?: string
-  /** Chunk URLs for the **matched** route (its layout chain + own chunk) to `modulepreload` in the
-   * shell - so the route code downloads in parallel with the entry instead of after it
-   * (`buildClient`'s per-route map). Empty/omitted ⇒ only the entry is preloaded (unchanged). */
-  readonly preload?: readonly string[]
-  /** Stylesheet URLs for the **matched** route (its layout chain + own CSS, from `buildClient`'s
-   * `BuildManifest.css`) - injected as `<link rel="stylesheet">` in `<head>` so styles arrive with the
-   * first paint (no FOUC). Rendered even on non-hydrated pages. Empty/omitted ⇒ none (unchanged). */
-  readonly styles?: readonly string[]
-  /** SSG: the prerendered-path set, serialized to `window.__NIFRA_PRERENDERED__` so the client fetches
-   * a static `_data.json` on soft-nav into a prerendered route. Empty/omitted ⇒ not injected. */
-  readonly prerenderedPaths?: readonly string[]
-  /** ISR: route freshness in seconds, emitted as the `x-nifra-isr-revalidate` header for a `withISR`
-   * wrapper to read. Omit ⇒ no header (the wrapper's default TTL applies). */
-  readonly revalidate?: number
-  /** ISR invalidation tags emitted as a bounded `x-nifra-isr-tags` header. */
-  readonly revalidateTags?: readonly string[]
-  /** Matched route id; written to `window.__NIFRA_ROUTE__` so the client hydrates this chain. */
-  readonly routeId?: string
-  /** The matched route's decoded path params - surfaced to the page as `params` (via {@link RenderProps})
-   * so an adapter's `useParams` is SSR-correct. Omit ⇒ `{}` (a route with no dynamic segments, or an
-   * error/404 render). */
-  readonly params?: Readonly<Record<string, string>>
-  /** The request's `pathname + search` - surfaced as `path` (via {@link RenderProps}) so an adapter's
-   * `useLocation`/`useSearchParams` render the right URL server-side and hydrate without drift. Omit ⇒
-   * `""`. */
-  readonly path?: string
-  /** The route's validated search (`searchOf(mod.searchSchema, url.search)`, the same value handed to
-   * the loader as `ctx.search`), surfaced as `search` (via {@link RenderProps}) so an adapter's
-   * `useSearch` is SSR-correct. Omit ⇒ `{}` (a render with no search context). */
-  readonly search?: Record<string, unknown>
-  /** Per-layout loader data, forwarded to the adapter as `RenderProps.layoutData`. Aligned with the
-   * chain's layout prefix; omitted when no layout in the chain has a loader. */
-  readonly layoutData?: readonly unknown[]
-  /** Dynamic-boundary states, forwarded to the adapter and serialized for hydration when present. */
-  readonly boundaries?: BoundaryStates
-  /** HTTP status for the response (default 200; e.g. 404 for a not-found page). */
-  readonly status?: number
-  /** Extra response headers - e.g. the `cache-control` a terminal status page wants. `content-type`
-   * is ignored (the document is always HTML) and the ISR freshness header is applied after these,
-   * so neither can be overridden from here. */
-  readonly headers?: HeadersLike
-  /** Document title (fallback when `head.title` is unset). */
-  readonly title?: string
-  /** Resolved route head - `title` overrides `title` above; `meta`/`link` render as managed
-   * (`data-nifra`) tags the client updates on navigation.
-   *
-   * **Head contract (the layout chain contributes).** `createWebApp` resolves this via
-   * {@link mergeHeads}: a route's head is its **layout chain's** `meta`/`head` exports merged with the
-   * page's. A `_layout.tsx` may `export const meta` (or `export function meta(args)`) - its tags land
-   * on every page below it (the home for `hreflang`, `preconnect`, a section-default `<title>`). The
-   * merge is **nearest-wins for scalars** (the page's `title` overrides an inner layout's, which
-   * overrides an outer one; an undefined page title keeps the layout's) and **concatenated for the
-   * `meta`/`link` arrays** (outermost layout first, page last). `<meta>`/`<link>` attributes pass a
-   * shared tag-specific allowlist (including inert `data-*` metadata) and values are escaped. */
-  readonly head?: Meta
-  /** Id of the container wrapping the app markup (default `"root"`). A non-default id also gets
-   * {@link ROOT_ATTRIBUTE}, which is how the generated client entry finds the container to hydrate -
-   * the entry is built once and cannot know what a given render chose. */
-  readonly rootId?: string
-  /** When `false`, emit a complete but **non-hydrated** document - no client entry script, data
-   * globals, or modulepreloads. Used for server-rendered `_error` pages: a terminal state that needs no
-   * client takeover, and it sidesteps an SSR/hydrate mismatch (the server rendered the boundary, not
-   * the page the client manifest maps this route id to). Default `true`. */
-  readonly hydrate?: boolean
-  /** Island client bundles (`@nifrajs/web/islands`) to load as `<script type="module">` in the document
-   * tail - emitted **regardless of `hydrate`**, so a static (`hydrate: false`) page can still mount
-   * no-framework islands. URLs are attribute-escaped. Empty/omitted ⇒ none (unchanged output). */
-  readonly islandScripts?: readonly string[]
-  /** CSP nonce applied to every framework-owned executable script in this document. */
-  readonly nonce?: string
-  /**
-   * Advanced: a per-route slot the renderer fills with the request-invariant document pieces (shell
-   * prefix/suffix, tail statics) on the first render and reuses afterwards, skipping their re-assembly.
-   *
-   * Only pass a cache when every shell-shaping input is IDENTICAL across the requests sharing it:
-   * same `head` content (a static meta chain - never a `meta(data)` function), `title`, `styles`,
-   * `preload`, `islandScripts`, `clientEntry`, `rootId`, `hydrate`, and `prerenderedPaths`. Per-request
-   * values (`data`, `params`, `search`, `actionData`, `layoutData`, deferred state) are always assembled
-   * fresh and safe. A per-request `nonce` disables the cache automatically. `createWebApp` wires this
-   * per route, gated on the route + layout metas being static.
-   */
-  readonly assemblyCache?: RenderAssemblyCache
-}
-
-/** The mutable per-route slot {@link RenderPageOptions.assemblyCache} fills. Opaque - create as `{}`. */
-export interface RenderAssemblyCache {
-  /** Shell up to (not including) the deferred-runtime insertion point. */
-  shellPre?: string
-  /** Shell from after the deferred-runtime insertion point through the open `#root` container. */
-  shellPost?: string
-  /** Tail opener: the inline script open tag + the route-id global (before the action global). */
-  tailPre?: string
-  /** Tail mid: the prerendered-paths global (between the action and layout-data globals). */
-  tailMid?: string
-  /** Tail data prefix: the `window.<data global>=` assignment head. */
-  tailData?: string
-  /** Tail from after the serialized data through `</html>`. */
-  tailPost?: string
-}
-
-/**
- * `renderPage` input. A hydrating page (the default) must supply `clientEntry`, because the document
- * loads it as a module script; a `hydrate: false` page may omit it, because nothing in the emitted
- * document references it. Expressed as a union so the compiler enforces the pairing rather than the
- * renderer discovering an empty `src` at runtime.
- */
-export type RenderPageInput = RenderPageOptions &
-  ({ readonly hydrate?: true; readonly clientEntry: string } | { readonly hydrate: false })
-
-/**
- * Server: render a full HTML document for a page - the adapter's hydration head + the SSR
- * markup (**streamed**) + the serialized loader data + the client module - as a `Response`.
- * The shell (`<head>` + the open container) flushes first, the adapter's app stream follows,
- * then the tail (data globals + client entry). Pure Web Standards, so it returns straight from
- * a nifra route handler and streams on any fetch runtime (Bun/Node/Deno/Workers).
- */
-export function renderPage(options: RenderPageInput): MaybePromise<Response> {
-  const page = renderPageResult(options)
-  return page instanceof Promise ? page.then((p) => p.toResponse()) : page.toResponse()
-}
-
-export function renderPageResult(options: RenderPageInput): MaybePromise<RenderedPage> {
-  const {
-    adapter,
-    chain,
-    data,
-    actionData,
-    clientEntry,
-    preload = [],
-    styles = [],
-    prerenderedPaths = [],
-    revalidate,
-    revalidateTags = [],
-    routeId,
-    status = 200,
-    title = "nifra",
-    head,
-    rootId = "root",
-    hydrate = true,
-    islandScripts = [],
-    nonce,
-    boundaries,
-    headers: extraHeaders,
-  } = options
-  if (nonce !== undefined && nonce.trim() === "") {
-    throw new TypeError("[nifra/web] renderPage nonce must be non-empty when provided")
-  }
-  const nonceAttr = nonce === undefined ? "" : ` nonce="${escapeAttr(nonce)}"`
-  const route = routeId === undefined ? "" : `window.${ROUTE_GLOBAL}=${serializeData(routeId)};`
-  // The SSG prerendered-path set (when an app declares it) - the client reads it to fetch a static
-  // `_data.json` on soft-nav into a prerendered route instead of hitting the worker. Empty ⇒ omitted.
-  const prerendered =
-    prerenderedPaths.length === 0
-      ? ""
-      : `window.${PRERENDERED_GLOBAL}=${serializeData(prerenderedPaths)};`
-  // Split deferred values: the component sees markers (id + promise) to `<Await>`; the serialized
-  // data carries `{__nifra_deferred: id}` placeholders (promises don't serialize). `actionData` may
-  // also `defer()` - split it too, continuing the id space so a single registry settles both. The
-  // inline registry runtime is emitted only when something defers, so non-deferred output is unchanged.
-  const { forComponent, forClient, deferred } = prepareDeferred(data)
-  // Each layout's data is split in turn, each continuing the id space, so a `defer()` in a layout
-  // settles through the SAME registry as the page's rather than colliding on ids.
-  const layoutSplits: Array<ReturnType<typeof prepareDeferred>> = []
-  if (options.layoutData !== undefined) {
-    let offset = deferred.length
-    for (const entry of options.layoutData) {
-      const split = prepareDeferred(entry, offset)
-      offset += split.deferred.length
-      layoutSplits.push(split)
-    }
-  }
-  const layoutDeferred = layoutSplits.flatMap((split) => split.deferred)
-  const actionSplit =
-    actionData === undefined
-      ? undefined
-      : prepareDeferred(actionData, deferred.length + layoutDeferred.length)
-  const boundarySplit =
-    boundaries === undefined
-      ? undefined
-      : prepareDeferred(
-          boundaries,
-          deferred.length + layoutDeferred.length + (actionSplit?.deferred.length ?? 0),
-        )
-  // On the common page-only path (no layout loader, no action) reuse `deferred` directly instead of
-  // allocating a fresh spread array every request.
-  const allDeferred =
-    layoutDeferred.length === 0 && actionSplit === undefined && boundarySplit === undefined
-      ? deferred
-      : [
-          ...deferred,
-          ...layoutDeferred,
-          ...(actionSplit ? actionSplit.deferred : []),
-          ...(boundarySplit ? boundarySplit.deferred : []),
-        ]
-  // Omitted entirely when no layout has a loader - a page-only app emits exactly what it did before.
-  const layoutTail =
-    options.layoutData === undefined
-      ? ""
-      : `window.${LAYOUT_DATA_GLOBAL}=${serializeData(layoutSplits.map((split) => split.forClient))};`
-
-  // Only emit the action global when an action actually ran, so plain GET output is unchanged.
-  const action =
-    actionSplit === undefined
-      ? ""
-      : `window.${ACTION_GLOBAL}=${serializeData(actionSplit.forClient)};`
-  const boundaryTail =
-    boundarySplit === undefined
-      ? ""
-      : `window.${BOUNDARY_GLOBAL}=${serializeData(boundarySplit.forClient)};`
-  const deferredRuntime =
-    allDeferred.length > 0 ? `<script${nonceAttr}>${DEFERRED_RUNTIME}</script>` : ""
-  // The regex only injects the CSP nonce into the (constant) hydration head; with no nonce it's a
-  // no-op that still scans the whole script every request. Skip it on the common no-nonce path.
-  // The request-invariant document pieces. With a caller-supplied per-route cache (and no per-request
-  // nonce, which would bake into them) they're built once and reused; the per-request seams - the
-  // deferred runtime in the shell, the action/layout-data globals and the serialized loader data in
-  // the tail - are always assembled fresh. Byte-identical to building the whole document inline.
-  const slot: RenderAssemblyCache =
-    nonce === undefined && options.assemblyCache !== undefined ? options.assemblyCache : {}
-  if (slot.shellPre === undefined) {
-    // Matched-route chunk preloads, concatenated directly. De-duped against the entry, which is
-    // preloaded separately below.
-    let preloadLinks = ""
-    for (const url of preload) {
-      if (url !== clientEntry)
-        preloadLinks += `<link rel="modulepreload" href="${escapeAttr(url)}">`
-    }
-    // The matched route's stylesheets - `<link rel="stylesheet">` in `<head>` so CSS arrives with the
-    // first paint (no FOUC). Render-blocking by design, and emitted regardless of `hydrate` (a static
-    // or `_error` page still wants its styles). In dev (Vite) CSS is injected client-side instead.
-    let styleLinks = ""
-    for (const url of styles) styleLinks += `<link rel="stylesheet" href="${escapeAttr(url)}">`
-    // Island bundles are referenced only by a `<script type="module">` at the END of `<body>`, so the
-    // browser doesn't discover them until the whole page is parsed. `modulepreload` them in `<head>`
-    // so the fetch starts immediately, in parallel with parsing - regardless of `hydrate`.
-    let islandPreloads = ""
-    for (const src of islandScripts)
-      islandPreloads += `<link rel="modulepreload" href="${escapeAttr(src)}">`
-    // Runs in the first-paint→hydration window to swallow a JS-only form's broken native submit. Only
-    // on a hydrating page (a static/_error page has no client handlers, so no footgun).
-    const hydrationGuard = hydrate ? `<script${nonceAttr}>${PRE_HYDRATION_GUARD}</script>` : ""
-    // `<html>` attributes. `lang` defaults to `"en"`; `dir` is omitted entirely when unset, which IS
-    // HTML's `ltr` default. Both attribute-escaped. `client.ts`'s `applyHead` mirrors this exact
-    // defaulting on soft-nav, so a hard load and a client navigation produce the same `<html>`.
-    const htmlAttrs = ` lang="${escapeAttr(head?.lang ?? "en")}"${head?.dir === undefined ? "" : ` dir="${escapeAttr(head.dir)}"`}`
-    // Marks the container for the client entry when the id is not the one the entry falls back to.
-    const rootMarker = rootId === "root" ? "" : ` ${ROOT_ATTRIBUTE}`
-    // A non-hydrated page omits the adapter's hydration bootstrap entirely (Solid's `_$HY` registry
-    // script, etc.) - there is no client takeover to feed, so it's dead bytes on a static document.
-    // The nonce rewrite only runs when a nonce is set; with none it was a whole-string no-op scan.
-    const rawHydrationHead = hydrate ? adapter.hydrationHead(nonce) : ""
-    const hydrationHead =
-      nonce === undefined
-        ? rawHydrationHead
-        : rawHydrationHead.replace(/<script(?![^>]*\bnonce=)(?=[\s>])/g, `<script${nonceAttr}`)
-    // Shell up to the deferred-runtime seam: on a hydrating page that seam sits after the entry +
-    // route-chunk preloads; a non-hydrating page has no runtime insertion at all.
-    const entryPreloads = hydrate
-      ? `<link rel="modulepreload" href="${escapeAttr(clientEntry ?? "")}">${preloadLinks}`
-      : ""
-    slot.shellPre = `<!doctype html><html${htmlAttrs}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${hydrationGuard}<title>${escapeHtml(head?.title ?? title)}</title>${headTags(head)}${styleLinks}${entryPreloads}`
-    slot.shellPost = `${islandPreloads}${hydrationHead}</head><body><div id="${escapeAttr(rootId)}"${rootMarker}>`
-    // Island bundles load regardless of `hydrate` - a static page (hydrate:false) ships no framework
-    // client but can still mount no-framework islands (`@nifrajs/web/islands`).
-    let islandTags = ""
-    for (const src of islandScripts)
-      islandTags += `<script type="module" src="${escapeAttr(src)}"${nonceAttr}></script>`
-    if (hydrate) {
-      slot.tailPre = `<script${nonceAttr}>${route}`
-      slot.tailMid = prerendered
-      slot.tailData = `window.${DATA_GLOBAL}=`
-      slot.tailPost = `</script><script type="module" src="${escapeAttr(clientEntry ?? "")}"${nonceAttr}></script>${islandTags}</body></html>`
-    } else {
-      slot.tailPre = ""
-      slot.tailMid = ""
-      slot.tailData = ""
-      slot.tailPost = `${islandTags}</body></html>`
-    }
-  }
-  // The deferred runtime rides only on a hydrating page (a static page has no client takeover), and
-  // only when something actually deferred - matching the pre-cache emission exactly.
-  const runtimeSeam = hydrate && allDeferred.length > 0 ? deferredRuntime : ""
-  const shellHtml = `${slot.shellPre}${runtimeSeam}${slot.shellPost}`
-  // Closes the hydration container; deferred resolve scripts go AFTER it (outside `#root`) so they
-  // aren't part of the adapter's hydrated tree (an inline script inside it breaks hydration).
-  const closeRootHtml = "</div>"
-  // Tail - the loader-data globals + the client module. Module scripts defer (run after parse), so
-  // the data global + every streamed deferred resolution are set before the entry hydrates.
-  const tailHtml = hydrate
-    ? `${slot.tailPre}${action}${slot.tailMid}${layoutTail}${boundaryTail}${slot.tailData}${serializeData(forClient)}${slot.tailPost}`
-    : (slot.tailPost as string)
-  const headers: Record<string, string> = { "content-type": "text/html; charset=utf-8" }
-  // Caller-supplied headers (a terminal status page's `cache-control`, say). Applied before the
-  // framework's own below, so `content-type` and the ISR channel stay authoritative - a caller must
-  // not be able to mislabel the document or forge the freshness header by passing them here.
-  if (extraHeaders !== undefined) {
-    for (const [name, value] of new Headers(extraHeaders)) {
-      if (name !== "content-type") headers[name] = value
-    }
-  }
-  // ISR: advertise the route's freshness so a `withISR` wrapper can set this page's cache TTL. A
-  // dedicated header (not the action-revalidation `x-nifra-revalidate`) so the TTL channel never aliases
-  // the client's path-list channel.
-  if (revalidate !== undefined) headers[ISR_REVALIDATE_HEADER] = String(revalidate)
-  const serializedTags = serializeISRTags(revalidateTags)
-  if (serializedTags !== undefined) headers[ISR_REVALIDATE_TAGS_HEADER] = serializedTags
-  const renderProps: RenderProps = {
-    data: forComponent,
-    actionData: actionSplit?.forComponent,
-    // `params`/`path` thread the matched route + URL to the adapter's `useParams`/`useLocation` so they
-    // render SSR-correct. Spread only when supplied (exactOptionalPropertyTypes) - an adapter with no
-    // router bindings simply never reads them.
-    ...(options.params !== undefined ? { params: options.params } : {}),
-    ...(options.path !== undefined ? { path: options.path } : {}),
-    // Same rule for `search`: the validated query the adapter's `useSearch` reads, spread only when the
-    // caller supplied it (a non-router render never has it).
-    ...(options.search !== undefined ? { search: options.search } : {}),
-    // Spread only when present, so a page-only render produces exactly the props it did before.
-    ...(options.layoutData !== undefined
-      ? { layoutData: layoutSplits.map((split) => split.forComponent) }
-      : {}),
-    ...(boundarySplit !== undefined
-      ? { boundaries: boundarySplit.forComponent as BoundaryStates }
-      : {}),
-  }
-
-  // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
-  // whole document in one pass. Progressive streaming only benefits pages with deferred boundaries
-  // (those take the streaming path below); for a plain page the streaming pipeline + the framework's
-  // streaming renderer are pure overhead vs a single sync render + concat. A buffered string body also
-  // gets an automatic Content-Length. A render throw surfaces here exactly as the streaming path's
-  // shell-readiness `await` does, so the `_error` boundary still maps it to a status.
-  if (allDeferred.length === 0 && adapter.renderToString !== undefined) {
-    const out = adapter.renderToString(chain, renderProps)
-    return typeof out === "string"
-      ? new BufferedRenderedPage(shellHtml + out + closeRootHtml + tailHtml, status, headers)
-      : out.then(
-          (bodyHtml) =>
-            new BufferedRenderedPage(
-              shellHtml + bodyHtml + closeRootHtml + tailHtml,
-              status,
-              headers,
-            ),
-        )
-  }
-
-  return renderStreamedPage(
-    adapter,
-    chain,
-    renderProps,
-    shellHtml,
-    closeRootHtml,
-    allDeferred,
-    tailHtml,
-    status,
-    headers,
-    nonceAttr,
-  ).then((response) => new ResponseRenderedPage(response))
-}
-
-async function renderStreamedPage(
-  adapter: RenderAdapter,
-  chain: readonly unknown[],
-  renderProps: RenderProps,
-  shellHtml: string,
-  closeRootHtml: string,
-  allDeferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
-  tailHtml: string,
-  status: number,
-  headers: Record<string, string>,
-  nonceAttr: string,
-): Promise<Response> {
-  // Streaming path - required for `defer()` (progressive `<Await>` resolution) and used by any adapter
-  // that doesn't implement `renderToString`. Awaiting `renderToStream` resolves on shell-readiness
-  // (React: on-shell-ready; Solid: synchronously), so a shell-render throw surfaces before any byte is
-  // sent. A *mid*-stream failure errors the body instead.
-  const enc = TEXT_ENCODER
-  const shell = enc.encode(shellHtml)
-  const closeRoot = enc.encode(closeRootHtml)
-  const tail = enc.encode(tailHtml)
-  const appStream = await adapter.renderToStream(chain, renderProps)
-  const body = streamDocument(shell, appStream, closeRoot, allDeferred, tail, enc, nonceAttr)
-  return new Response(body, { status, headers })
-}
-
-class BufferedRenderedPage implements RenderedPage {
-  readonly [RESPONSE_RESULT] = true
-  private readonly body: string
-  private readonly status: number
-  private readonly headers: Readonly<Record<string, string>>
-
-  constructor(body: string, status: number, headers: Readonly<Record<string, string>>) {
-    this.body = body
-    this.status = status
-    this.headers = headers
-  }
-
-  toResponse(): Response {
-    return htmlResponse(this.body, { status: this.status, headers: this.headers })
-  }
-
-  toNodeBody(): {
-    readonly status: number
-    readonly headers: Readonly<Record<string, string | readonly string[]>>
-    readonly body: string
-  } {
-    return { status: this.status, headers: this.headers, body: this.body }
-  }
-}
-
-class ResponseRenderedPage implements RenderedPage {
-  readonly [RESPONSE_RESULT] = true
-  private readonly response: Response
-
-  constructor(response: Response) {
-    this.response = response
-  }
-
-  toResponse(): Response {
-    return this.response
-  }
-}
-
-function htmlResponse(body: string, init: ResponseInit): Response {
-  const response = new Response(body, init)
-  // @nifrajs/node can write buffered HTML straight to ServerResponse with `end(body)`, avoiding a Web
-  // Response stream drain on Node. Non-enumerable + Symbol.for keeps this invisible to Web runtimes and
-  // cross-package without adding a runtime dependency from @nifrajs/node to @nifrajs/web.
-  Object.defineProperty(response, NODE_RESPONSE_BODY, { value: body })
-  return response
-}
-
-/**
- * Assemble the document stream: `shell` → the app `stream` (forwarded chunk-by-chunk, so a streaming
- * renderer's progressive flushing is preserved) → `closeRoot` → one `__nifraResolve`/`__nifraReject`
- * script per deferred value (emitted once its promise settles - by now the app stream has awaited
- * the same Suspense boundaries - and placed OUTSIDE `#root`) → `tail`. A mid-stream app error errors
- * the result (the body breaks) rather than silently truncating a 200.
- */
-function streamDocument(
-  shell: Uint8Array,
-  stream: ReadableStream<Uint8Array>,
-  closeRoot: Uint8Array,
-  deferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
-  tail: Uint8Array,
-  enc: TextEncoder,
-  nonceAttr: string,
-): ReadableStream<Uint8Array> {
-  return new ReadableStream({
-    async start(controller) {
-      const reader = stream.getReader()
-      try {
-        controller.enqueue(shell)
-        for (;;) {
-          const { done, value } = await reader.read()
-          if (done) break
-          controller.enqueue(value)
-        }
-        controller.enqueue(closeRoot)
-        // Stream each resolution as ITS OWN promise settles - NOT in array order. A slow
-        // defer() must not block a faster one; each script self-addresses by id, so order is irrelevant.
-        await Promise.all(
-          deferred.map(async (d) => {
-            try {
-              const value = serializeData(await d.promise)
-              controller.enqueue(
-                enc.encode(`<script${nonceAttr}>window.__nifraResolve(${d.id},${value})</script>`),
-              )
-            } catch (err) {
-              // A rejected deferred streams __nifraReject (the client `<Await>` surfaces it) - it must
-              // not break the whole body. Redact: stream a stable opaque code, never the raw error
-              // text; log the real reason server-side.
-              console.error("[nifra/web] deferred value rejected:", err)
-              controller.enqueue(
-                enc.encode(
-                  `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`,
-                ),
-              )
-            }
-          }),
-        )
-        controller.enqueue(tail)
-        controller.close()
-      } catch (err) {
-        controller.error(err)
-      } finally {
-        reader.releaseLock()
-      }
-    },
-  })
-}
-
-/** Options for {@link redirect}. */
-export interface RedirectOptions {
-  /** HTTP status (default 303 See Other; pass 307/308 to preserve the method). */
-  readonly status?: number
-  /** Allow an off-origin / absolute destination. Off by default: only a same-origin path (a single
-   * leading `/`) is permitted, so an action can't be turned into an open redirect by passing
-   * attacker-controlled input straight through. Set `true` for a deliberate external redirect. */
-  readonly external?: boolean
-  /** Extra response headers. A redirect is no longer a `Response`, so there is no `.headers` to
-   * mutate after the fact - name them here. Cookies still ride `c.set`, as on any other response. */
-  readonly headers?: Readonly<Record<string, string>>
-}
-
-/** A same-origin destination is an absolute path: one leading `/`, but NOT `//` (protocol-relative →
- * another origin), and nothing a URL parser resolves off-origin. Everything else (absolute URL with
- * a scheme, `//host`, `javascript:`, a bare relative `foo`) requires `external: true`. The predicate
- * lives in the kernel - see `isSameOriginPath` - so this gate and the auth guards' `redirectTo`
- * cannot drift apart. */
-
-/**
- * Build a redirect - return it from a route `action` for the Post/Redirect/Get pattern (POST
- * mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit). Defaults to 303
- * (See Other); pass `{ status: 307 }` or `{ status: 308 }` to preserve the method.
- *
- * **Secure by default:** `location` must be a same-origin path (begins with `/`, not `//`). An
- * off-origin/absolute destination throws unless you pass `{ external: true }` - this closes the
- * open-redirect footgun of `return redirect(formData.get("next"))` on the no-JS (native-form) path,
- * which serves the action's control-flow value verbatim.
- *
- * Returns a plain render, not a `Response`. A redirect is a status line and one header - the most
- * body-less response there is - and building a `Response` for it costs the whole Web object plus, on
- * Node, a stream drained back out. As data it renders on the same lane a handler's return takes.
- * `redirect(...)` is still returned or thrown from exactly the same places; only `.status` /
- * `.headers` are gone from the value, replaced by `options.headers` and the request's `c.set`.
- *
- * @param options redirect status, extra headers, and whether an off-origin destination is intentional.
- */
-export function redirect(location: string, options: RedirectOptions = {}): ResponseResult {
-  if (options.external !== true && !isSameOriginPath(location)) {
-    throw new Error(
-      `[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//", no backslash or control character), or redirect(location, { external: true }) for a deliberate off-origin redirect. This guards against open redirects from unvalidated input.`,
-    )
-  }
-  // Reject CR/LF in the Location explicitly - defense-in-depth (response splitting / header
-  // injection). Spec-correct runtimes' Headers setter throws on CR/LF, but `external: true` lets
-  // unvalidated input reach this sink, so we don't rely on the runtime. Same posture as
-  // serializeCookie / the SSE frame formatter, which strip CRLF at their sinks.
-  if (/[\r\n]/.test(location)) {
-    throw new Error(
-      `[nifra/web] redirect location contains a CR/LF character - refusing to emit a header-injecting redirect.`,
-    )
-  }
-  return statusResult(options.status ?? 303, undefined, {
-    headers: options.headers === undefined ? { location } : { ...options.headers, location },
-  })
-}
-
-/**
- * Brand marking a `Response` as a **terminal-status signal** rather than a response to serve verbatim.
- *
- * A loader that throws a bare `Response` has always been passed straight through - that is how
- * `throw redirect(...)` works, and apps rely on it. So "render the `_404` boundary at 404" cannot be
- * expressed by throwing a plain `Response`: the framework would have no way to tell it apart from a
- * hand-rolled body the app wants served exactly as written. The brand is that distinction, and
- * checking it *before* the pass-through is what keeps every existing throw working unchanged.
- *
- * `Symbol.for` matches `RESPONSE_RESULT` above: a registry symbol survives two copies of this module,
- * which a `unique symbol` would not - and a duplicate-install turning a 404 into a raw 404 body would
- * be a maddening bug to trace.
- */
-/** Derived from the `Headers` constructor rather than the DOM lib's `HeadersInit`: `@nifrajs/web`
- * is consumed from DOM-free programs (the root tsconfig runs `types: ["bun"]`), and naming the DOM
- * type here would break their build. Same workaround as `SSEInit.headers` in core. */
-type HeadersLike = ConstructorParameters<typeof Headers>[0]
-
-/**
- * The signatures a **duplicate module instance** produces during SSR, across engines.
- *
- * Two copies of React (or of `@nifrajs/core`) at the SAME version still fail, because module identity
- * is path-based: hooks read a dispatcher off the copy that rendered, and the component imported the
- * other one. The error that surfaces names a React internal, so it reads as a React bug and the actual
- * cause - two directories - is a long inference away. Naming the cause at the point of failure is the
- * difference between that and a five-second read.
- */
-const DUPLICATE_INSTANCE_SIGNATURES: readonly RegExp[] = [
-  /resolveDispatcher\(\)/,
-  /Invalid hook call/,
-  /Cannot read propert(?:y|ies) of null \(reading '(?:use[A-Z]\w*)'\)/,
-  /null is not an object \(evaluating '.*\.use[A-Z]\w*'\)/,
-]
-
-/**
- * Append the likely cause to an SSR error that carries a duplicate-instance signature.
- *
- * Deliberately does NOT claim the resolved paths: `@nifrajs/web` is framework-agnostic and does not
- * depend on React, so it cannot resolve the copies without guessing. It names the condition and the
- * command that reports the paths, which is the actionable part. Returns the error untouched when the
- * signature does not match, so an ordinary render error reads exactly as before.
- */
-function withDuplicateInstanceHint(err: unknown): unknown {
-  if (!(err instanceof Error)) return err
-  if (!DUPLICATE_INSTANCE_SIGNATURES.some((rx) => rx.test(err.message))) return err
-  const augmented = new Error(
-    `${err.message}\n\n[nifra/web] This signature usually means TWO COPIES of an identity-sensitive package (react, react-dom, or @nifrajs/core) are installed at different paths. Module identity is path-based, so matching versions do NOT fix it - the copies must resolve to the same directory. Run \`nifra check\` to list the paths.`,
-    { cause: err },
-  )
-  augmented.name = err.name
-  // `stack` is optional under exactOptionalPropertyTypes; assigning `undefined` would replace a real
-  // stack with nothing on engines that always populate it.
-  if (err.stack !== undefined) augmented.stack = err.stack
-  return augmented
-}
-
-/**
- * An action's control-flow value passes straight through - except a redirect on a client-submit data
- * request: fetch would follow the 3xx into HTML the client can't use, so the redirect rides the
- * X-Nifra-Redirect header on a 204 and the client navigates. One conversion shared by the returned-
- * and thrown- paths, so `return redirect()` and `throw redirect()` agree.
- *
- * Takes either shape: `redirect()` is a plain render, while a hand-rolled `new Response(...)` from an
- * action still arrives as a `Response`. The rewrite stays on the lane its input was on - a plain
- * redirect converts to a plain 204, and never materializes the `Response` it is replacing.
- */
-function actionResponse(
-  result: Response | ResponseResult,
-  isDataRequest: boolean,
-): Response | ResponseResult {
-  if (!isDataRequest) return result
-  if (isResponseResult(result)) {
-    const plain = result.plain
-    // No `plain` means a carrier that only knows how to build a `Response` (not one of ours) - fall
-    // back rather than guess at its status.
-    if (plain === undefined) return actionResponse(result.toResponse(), isDataRequest)
-    if (plain.status < 300 || plain.status >= 400) return result
-    const location = plain.headers?.location ?? "/"
-    return statusResult(204, undefined, { headers: { [REDIRECT_HEADER]: location } })
-  }
-  if (result.status >= 300 && result.status < 400) {
-    const location = result.headers.get("location") ?? "/"
-    return statusResult(204, undefined, { headers: { [REDIRECT_HEADER]: location } })
-  }
-  return result
-}
-
-/** A loaded layout module. `loader`/`gate` are the layout-loader surface; `meta` predates it. */
-type LoadedLayoutModules = ReadonlyArray<{
-  default: unknown
-  meta?: MetaInput
-  loader?: LayoutLoader
-  action?: unknown
-  gate?: boolean
-  // A layout may declare its own `searchSchema`; the route's effective search merges the layout chain's
-  // schemas with the page's (page-wins). Present on the raw module already - typed here so it is readable.
-  searchSchema?: RouteModule["searchSchema"]
-  boundaries?: readonly BoundaryRegistration[]
-}>
-
-/**
- * Narrow the route's params to the ones a layout owns.
- *
- * A layout wraps a URL prefix, so anything deeper belongs to a route beneath it. Handing it the full
- * set would let a layout read a param it does not own - which reads fine until the layout is reused
- * under a route that has no such param and the value silently becomes `undefined`.
- */
-function scopeParams(
-  params: Record<string, string>,
-  owned: readonly string[] | undefined,
-): Record<string, string> {
-  if (owned === undefined) return params // hand-built manifest with no scope info: unchanged behaviour
-  if (owned.length === 0) return EMPTY_LAYOUT_PARAMS
-  const scoped: Record<string, string> = {}
-  for (const name of owned) {
-    const value = params[name]
-    if (value !== undefined) scoped[name] = value
-  }
-  return scoped
-}
-
-const EMPTY_LAYOUT_PARAMS: Record<string, string> = Object.freeze({})
-
-const EMPTY_RETAIN: ReadonlySet<number> = new Set<number>()
-
-/**
- * Marks an error as coming from a LAYOUT loader, carrying that layout's id.
- *
- * The boundary that catches it must be at or above the failing layout's own segment. The route's
- * innermost `_error` may live BELOW the layout that failed, and rendering there would wrap the
- * boundary in a layout whose data never arrived - so the page would render inside a component that
- * threw. A registry symbol, matching the other cross-module brands here.
- */
-const LAYOUT_ERROR_ID = Symbol.for("nifra.web.layout-error-id")
-
-const tagLayoutError = (err: unknown, layoutId: string): unknown => {
-  if (typeof err === "object" && err !== null && !(LAYOUT_ERROR_ID in err)) {
-    Object.defineProperty(err, LAYOUT_ERROR_ID, { value: layoutId, enumerable: false })
-  }
-  return err
-}
-
-const layoutErrorId = (err: unknown): string | undefined =>
-  typeof err === "object" && err !== null
-    ? ((err as Record<symbol, unknown>)[LAYOUT_ERROR_ID] as string | undefined)
-    : undefined
-
-const STATUS_SIGNAL = Symbol.for("nifra.web.status-signal")
-
-/** Reason phrases for the plain-text fallback, used only when the app authored no `_<status>` and no
- * `_404` page. Deliberately not exhaustive - anything unlisted falls back to "Error", which is more
- * useful than shipping a table of every RFC status for a body almost nobody will see. */
-const STATUS_TEXT: Readonly<Record<number, string>> = {
-  400: "Bad Request",
-  401: "Unauthorized",
-  402: "Payment Required",
-  403: "Forbidden",
-  404: "Not Found",
-  410: "Gone",
-  451: "Unavailable For Legal Reasons",
-  500: "Internal Server Error",
-}
-
-interface StatusSignal extends Response {
-  readonly [STATUS_SIGNAL]: { readonly status: number; readonly headers?: HeadersLike }
-}
-
-function isStatusSignal(value: unknown): value is StatusSignal {
-  return value instanceof Response && STATUS_SIGNAL in value
-}
-
-function statusSignal(status: number, options: StatusPageOptions): never {
-  if (!Number.isInteger(status) || status < 400 || status > 599) {
-    throw new Error(
-      `[nifra/web] statusPage(${JSON.stringify(status)}) must be an integer 4xx or 5xx status. Use redirect() for 3xx, and return data for a successful render.`,
-    )
-  }
-  const response = new Response(null, { status })
-  // Non-enumerable so the brand never lands in a structured clone or a JSON log of the response.
-  Object.defineProperty(response, STATUS_SIGNAL, {
-    value: { status, ...(options.headers !== undefined ? { headers: options.headers } : {}) },
-    enumerable: false,
-  })
-  throw response
-}
-
-/** Options shared by {@link notFound}, {@link gone}, and {@link statusPage}. */
-export interface StatusPageOptions {
-  /**
-   * Extra headers for the rendered response - `cache-control` above all.
-   *
-   * The defaults differ by status for a reason: a 404 may be a race with publication, so it wants a
-   * short TTL, while a 410 is a promise that the URL is permanently gone and can be cached hard.
-   * Getting this wrong is the difference between a crawler dropping a dead URL and re-fetching it
-   * for weeks.
-   */
-  readonly headers?: HeadersLike
-}
-
-/**
- * Render the nearest `_404` page at status **404**. `throw` it from a loader when the record does not
- * exist.
- *
- * This is the fix for the soft 404: a matched route whose loader finds nothing has otherwise no way to
- * answer 404, so the path of least resistance is to return empty data and render "not found" inside a
- * **200**. That looks correct in a browser and is invisible in review, which is why it ships and stays
- * shipped - while search engines penalise it and keep the dead URL indexed.
- *
- * Returns `never`: these throw, so a loader narrows without a redundant `return`, and the type states
- * the thing the "loaders `throw` redirect, actions `return` it" rule already trips people on.
- */
-export function notFound(options: StatusPageOptions = {}): never {
-  return statusSignal(404, options)
-}
-
-/**
- * Render a terminal page at status **410 Gone**. `throw` it from a loader for a record that existed and
- * was deliberately removed - a withdrawn listing, a deleted post.
- *
- * 410 is not a pedantic 404: it tells a crawler to **drop** the URL rather than re-fetch it for weeks
- * on the assumption the 404 was transient. Uses `_410.tsx` if the app has one, otherwise `_404`.
- */
-export function gone(options: StatusPageOptions = {}): never {
-  return statusSignal(410, options)
-}
-
-/**
- * Render a terminal page at any 4xx/5xx status - the escape hatch behind {@link notFound} and
- * {@link gone} (402, 451, …). Uses `_<status>.tsx` if present, otherwise `_404`.
- */
-export function statusPage(status: number, options: StatusPageOptions = {}): never {
-  return statusSignal(status, options)
-}
-
-/** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
- * shape (not a class) so `@nifrajs/client`'s `ActionData` can unwrap it structurally without importing
- * from `@nifrajs/web`. `createWebApp` strips the wrapper - the client receives `data` as the body and
- * the paths via the `X-Nifra-Revalidate` header. */
-export interface RevalidateResult<T> {
-  readonly __nifraRevalidate: readonly string[]
-  readonly data: T
-}
-
-/**
- * Return this from an action to declare which routes the mutation changed (alongside the action's
- * `data`). `createWebApp` sets the `X-Nifra-Revalidate` response header; after the submit the client
- * marks those cached routes stale - refetching the active one and any mounted fetcher showing them -
- * so a mutation can refresh views beyond the one that was submitted. `data` is still surfaced to the
- * component as `actionData` (the wrapper is transparent to `ActionData<typeof action>`).
- */
-export function revalidate<T>(paths: readonly string[], data: T): RevalidateResult<T> {
-  return { __nifraRevalidate: paths, data }
-}
-
-/**
- * Serialize loader data for embedding inside an inline `<script>`. `JSON.stringify` alone
- * is NOT safe there: a string containing `</script>` or `<!--` would break out of the
- * script element (an XSS vector). Escape `<`/`>` to `\uXXXX`, plus the U+2028/U+2029
- * separators.
- */
-export function serializeData(data: unknown): string {
-  const serialized = JSON.stringify(data ?? null)
-  // Most loader payloads contain no script-sensitive characters. Guard with chained `indexOf`
-  // rather than a regex `.test`: each probe is a native memchr-style scan, measured ~7x faster than
-  // the regex scan on V8 for a multi-KB payload (and the engine rejects the two >0xFF separator
-  // probes in O(1) when the string is internally one-byte, which serialized JSON almost always is).
-  // The same four characters are probed as the SCRIPT_ESCAPE class, so any payload the regex would
-  // escape still takes the escape path - this is only a cheaper detector, never a security
-  // relaxation.
-  const needsEscape =
-    serialized.indexOf("<") !== -1 ||
-    serialized.indexOf(">") !== -1 ||
-    serialized.indexOf(LINE_SEP) !== -1 ||
-    serialized.indexOf(PARA_SEP) !== -1
-  return needsEscape
-    ? serialized.replace(SCRIPT_ESCAPE, (ch) => SCRIPT_ESCAPE_MAP[ch] ?? ch)
-    : serialized
-}
-
-function escapeHtml(value: string): string {
-  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
-}
-
-/**
- * Escape a `<script>` element's text content so it cannot break out of the element. Per the HTML spec,
- * a script's text may contain any character EXCEPT the sequences that the parser treats as element
- * boundaries: `</` (which would begin the end tag - `</script>` is the obvious XSS vector, but ANY `</`
- * starts script-data-end-tag parsing), and the comment/CDATA edges `<!--` / `]]>`. We escape the `<`
- * (and the `>` of `]]>`) to its JS unicode escape: inside a JS/JSON string literal `<` is the
- * identical character, so a JSON-LD payload is byte-equivalent after parsing - but the raw `<`/`>` the
- * HTML tokenizer scans for is gone. This is the JSON-LD-in-HTML rule (content is JSON, never raw HTML),
- * mirroring {@link serializeData}'s posture for the data-global script. Idempotent on already-safe text.
- */
-function escapeScriptContent(content: string): string {
-  // Order matters: rewrite `]]>` first (its `>` becomes `>`), then every `<` (covers `</` and
-  // `<!--` in one pass). `<` → `<`; the lone `>` of `]]>` → `>`. A bare `>` elsewhere is
-  // harmless in script data, so only the `]]>` close is targeted for `>`.
-  return content.replaceAll("]]>", "]]\\u003e").replaceAll("<", "\\u003c")
-}
-
-function escapeAttr(value: string): string {
-  return value
-    .replaceAll("&", "&amp;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-}
-
-/** Serialize attributes that passed the shared SSR/client head trust policy. */
-function tagAttrs(tag: "meta" | "link", attrs: Readonly<object>): string | null {
-  const trusted = trustedHeadAttributes(tag, attrs)
-  if (trusted === null) return null
-  let out = ""
-  for (const [name, value] of trusted) {
-    if (out !== "") out += " "
-    out += value === true ? name : `${name}="${escapeAttr(value)}"`
-  }
-  return out
-}
-
-// Memoize the serialized head-tag string by the resolved `Meta` object's identity. A STATIC route
-// `meta` is returned by-reference from resolveMeta, so the same object recurs every request → cache
-// hit, and the invariant string is serialized once per route, not per request. A FUNCTION `meta`
-// builds a fresh object each request (new identity) → miss → recompute, exactly as needed (its
-// content can vary). WeakMap so a route module that's GC'd takes its entry with it.
-const headTagsCache = new WeakMap<Meta, string>()
-
-function assertExecutableScriptType(type: string): void {
-  if (!EXECUTABLE_SCRIPT_TYPES.has(type)) {
-    throw new TypeError(
-      `[nifra/web] executable inline scripts accept ${[...EXECUTABLE_SCRIPT_TYPES].map((t) => JSON.stringify(t)).join(" or ")}; received ${JSON.stringify(type)}`,
-    )
-  }
-}
-
-/** Render a route's `meta`/`link`/`script` as managed (`data-nifra`) head tags. Title is set
- * separately. XSS-safe by construction: every attribute flows through the shared tag-specific trust
- * policy then value escaping, and each `script[].content` through `escapeScriptContent`
- * (breakout-escaped) - so loader-derived strings (LLM-authored `og:*`, user content) can't inject markup
- * or close the tag early. String concatenation (no intermediate `.map()` arrays + spread) - parity with
- * the already concat-based preloadLinks/styleLinks/islandPreloads loops; byte-identical output. Result
- * is memoized per resolved-`Meta` identity (static meta → serialized once per route). */
-function headTags(head: Meta | undefined): string {
-  if (head === undefined) return ""
-  const cached = headTagsCache.get(head)
-  if (cached !== undefined) return cached
-  let out = ""
-  if (head.meta !== undefined)
-    for (const m of head.meta) {
-      const attrs = tagAttrs("meta", m)
-      if (attrs !== null) out += `<meta${attrs === "" ? "" : ` ${attrs}`} data-nifra>`
-    }
-  if (head.link !== undefined)
-    for (const l of head.link) {
-      const attrs = tagAttrs("link", l)
-      if (attrs !== null) out += `<link${attrs === "" ? "" : ` ${attrs}`} data-nifra>`
-    }
-  // `<script>` slot - JSON-LD + other inert head scripts. `type` is attribute-escaped; `content` is
-  // breakout-escaped (`escapeScriptContent`) so a `</script>` (or `<!--`/`]]>`) payload can't close the
-  // element early. Managed (`data-nifra`) so a soft-nav's `applyHead` cleanly replaces it.
-  if (head.script !== undefined)
-    for (const s of head.script) {
-      const type = s.type ?? "application/ld+json"
-      if (!INERT_SCRIPT_TYPES.has(type)) {
-        throw new TypeError(
-          `[nifra/web] head.script only accepts inert JSON script types; received ${JSON.stringify(type)}. Use unsafeInlineScript() with a CSP nonce for executable code.`,
-        )
-      }
-      out += `<script type="${type}" data-nifra>${escapeScriptContent(s.content)}</script>`
-    }
-  if (head.unsafeScript !== undefined)
-    for (const s of head.unsafeScript) {
-      if (s.unsafe !== true || s.nonce.trim() === "") {
-        throw new TypeError("[nifra/web] executable inline scripts require a non-empty CSP nonce")
-      }
-      // `type` is validated, not escaped, for the same reason as the inert slot above: an unknown
-      // value here is a bug, and escaping one would emit a nonsense script type rather than say so.
-      // It was interpolated raw while the `nonce` beside it was escaped, so a descriptor built by hand
-      // - `unsafeScript` is a public field, the helper is only a convenience - could close the
-      // attribute and inject markup. Measured: `type: '"><img src=x onerror=alert(1)>'` reached the
-      // document. An injection in the slot whose whole purpose is to make script emission trustworthy.
-      assertExecutableScriptType(s.type)
-      out += `<script type="${s.type}" nonce="${escapeAttr(s.nonce)}" data-nifra>${escapeScriptContent(s.content)}</script>`
-    }
-  headTagsCache.set(head, out)
-  return out
-}
-
-/**
- * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
- * engines which URL is authoritative for a page (deduping query-string / tracking variants).
- *
- * ```ts
- * export const meta = (a) => ({ link: [canonical(`https://site.com/posts/${a.params.slug}`)] })
- * ```
- */
-export function canonical(href: string): LinkDescriptor {
-  return { rel: "canonical", href }
-}
-
-/** Inputs for {@link openGraph} - the common Open Graph properties. All optional; only the provided
- * ones become tags. `type` defaults to `"website"`. */
-export interface OpenGraphInput {
-  readonly title?: string
-  readonly description?: string
-  /** Absolute URL of the share image (`og:image`). */
-  readonly image?: string
-  /** Canonical URL of the page (`og:url`). */
-  readonly url?: string
-  /** Object type (`og:type`) - `"website"`, `"article"`, … Default `"website"`. */
-  readonly type?: string
-}
-
-/**
- * Build the Open Graph `<meta property="og:*">` entries for a route's `meta.meta`. Returns only the
- * properties you supplied (plus `og:type`, defaulting to `"website"`), so it composes with other meta.
- *
- * ```ts
- * export const meta = { meta: [...openGraph({ title: "Nifra", image: "https://site.com/og.png" })] }
- * ```
- */
-export function openGraph(input: OpenGraphInput): MetaDescriptor[] {
-  const tags: MetaDescriptor[] = []
-  const add = (property: string, content: string | undefined): void => {
-    if (content !== undefined) tags.push({ property, content })
-  }
-  add("og:title", input.title)
-  add("og:description", input.description)
-  add("og:image", input.image)
-  add("og:url", input.url)
-  // `og:type` always present (the spec's required property) - default "website" when unset.
-  tags.push({ property: "og:type", content: input.type ?? "website" })
-  return tags
-}
-
-/**
- * Build a JSON-LD `<script type="application/ld+json">` entry for a route's `meta.script` from a plain
- * object. `JSON.stringify` produces the body; the head renderer breakout-escapes it (see
- * `escapeScriptContent`), so a string field containing `</script>` is embedded safely.
- *
- * ```ts
- * export const meta = {
- *   script: [jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })],
- * }
- * ```
- */
-export function jsonLd(data: Record<string, unknown>): ScriptDescriptor {
-  return { type: "application/ld+json", content: JSON.stringify(data) }
-}
-
-/**
- * Deliberately unsafe escape hatch for executable inline code. The required nonce keeps the result
- * compatible with a strict CSP and makes the security-sensitive choice visible at the call site.
- */
-export function unsafeInlineScript(
-  content: string,
-  options: { readonly nonce: string; readonly type?: "module" | "text/javascript" },
-): UnsafeScriptDescriptor {
-  if (options.nonce.trim() === "") {
-    throw new TypeError("[nifra/web] unsafeInlineScript requires a non-empty CSP nonce")
-  }
-  const type = options.type ?? "module"
-  // Checked here as well as at emit: the type union is compile-time only, and this helper is the one
-  // place a caller is told what it may pass. Failing at the call site names the argument; failing at
-  // render names a document.
-  assertExecutableScriptType(type)
-  return {
-    unsafe: true,
-    type,
-    nonce: options.nonce,
-    content,
-  }
-}
-
-export interface CreateWebAppOptions<Env = unknown> {
-  readonly adapter: RenderAdapter
-  readonly manifest: Manifest
-  /** URL of the built client entry (module script) injected into every page. */
-  readonly clientEntry: string
-  /** Default document title for all pages. */
-  readonly title?: string
-  /**
-   * Options for the underlying `server()` - `requestTimeoutMs`, `admission`, `gracefulSignals`, and
-   * the rest of {@link ServerOptions}.
-   *
-   * Needed because the `Server` is constructed in here, so a caller has no other way to reach its
-   * constructor: a page app could set no request timeout and no capacity gate, which are exactly the
-   * two knobs a production readiness check looks for. An SSR app wants them MORE than a backend does -
-   * a render is slow and allocation-heavy, so a burst that a JSON API would absorb is the one that
-   * exhausts the pod.
-   *
-   * Applies to the whole app, {@link mounts} and the {@link api} auto-mount included: the capacity gate
-   * sits at the fetch entry, ahead of the request hooks those are dispatched from.
-   */
-  readonly server?: ServerOptions
-  /**
-   * Runs against the app BEFORE any page route is registered - the seam for `securityHeaders()`,
-   * `requestId()`, `logger()`, a rate limit, or anything else applied with `use`.
-   *
-   * ```ts
-   * createWebApp({
-   *   …,
-   *   use: (app) => {
-   *     app.use(securityHeaders())
-   *     app.use(requestId())
-   *   },
-   * })
-   * ```
-   *
-   * A callback rather than an array because `use` is overloaded - `Middleware`, `IdentityPlugin`,
-   * `ContextPlugin` - and only the real call site instantiates the right overload. The return value
-   * is ignored: this is for cross-cutting concerns, not for declaring routes (declare those on the
-   * returned app, where they get their types).
-   *
-   * **Why the timing matters.** `beforeHandle`, `afterHandle`, `around`, `derive`/`decorate`, and
-   * `onError` are snapshotted into each route AS IT IS DECLARED, and `createWebApp` declares every
-   * page (plus the `/*` catch-all) before it returns - so a caller's `app.use(…)` afterwards binds
-   * them to nothing, silently. `requestId()` is exactly that case: it is a `derive`, so applied late
-   * it leaves every page without `c.requestId`. Route assurance evidence is order-scoped the same
-   * way, so a late `securityHeaders()` leaves the pages unable to PROVE the header to `nifra assure`
-   * even though it does still set it.
-   *
-   * `onRequest`/`onResponse` (and the response header/body hooks) are app-global arrays read at
-   * request time, so those alone DO work when added late. Using this seam for everything avoids
-   * having to remember which is which.
-   *
-   * Runs ahead of the {@link mounts} / {@link api} request hooks, so an `onRequest` middleware guards
-   * a mounted auth handler too.
-   *
-   * A `ContextPlugin` applied here takes runtime effect but cannot widen the declared return type of
-   * this function, so `c.requestId` is not typed on routes you declare afterwards. Named plugins are
-   * idempotent, so `app.use(requestId())` on the returned app recovers the TYPE without applying the
-   * plugin a second time.
-   */
-  readonly use?: (app: ReturnType<typeof server<Env>>) => void
-  /** Injected into each loader's `ctx.api` - typically an `inProcessClient(app)` (typed
-   * per-route via `@nifrajs/client`'s `createRoutes`). Opaque to the core.
-   *
-   * **Auto-mount.** Every `inProcessClient(backend)` exposes the symbol-keyed platform-aware backend
-   * 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. */
-  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. */
-  readonly apiPrefix?: string
-  /**
-   * Strip {@link apiPrefix} from the pathname before dispatching to `api` (default `false`).
-   *
-   * The default suits a backend that declares FULL paths (`server().post("/api/sync", …)`), which is
-   * right when it is only ever mounted here. Set this when the backend declares its routes WITHOUT the
-   * prefix because it also runs standalone behind its own shell, so its paths cannot carry a prefix that
-   * only exists when it is mounted. Without it every request 404s inside the backend, and the workaround
-   * is a `Proxy` that rewrites each URL.
-   */
-  readonly apiStrip?: boolean
-  /**
-   * Sub-apps mounted ahead of page routing - an auth handler, a webhook receiver, a stack's routes.
-   *
-   * Structural on purpose: anything with `{ path, app: { fetch } }` fits, so a library that exposes its
-   * routes as such a list mounts as `mounts: theirRoutes` without `@nifrajs/web` taking a dependency on
-   * it. `better-auth` is the motivating case - it is not a `backend` route, so `/api/auth/*` used to 404
-   * silently.
-   *
-   * 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.
-   */
-  readonly mounts?: ReadonlyArray<{
-    readonly path: string
-    readonly app: { fetch(request: Request): Response | Promise<Response> }
-    readonly stripPrefix?: boolean
-  }>
-  /** 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`).
-   * Pair with `withISR({ draftSecret })` so editors bypass the cache. Omit to disable draft mode. */
-  readonly draftSecret?: string
-  /** Per-route chunk URLs (`buildClient`'s `BuildManifest.routes`) - `routeId → [layout chunks…, own
-   * chunk]`. When present, each page `modulepreload`s its matched route's chunks alongside the entry,
-   * so the route code downloads in parallel (no entry→route-chunk waterfall). Omit ⇒ entry-only. */
-  readonly routePreload?: Readonly<Record<string, readonly string[]>>
-  /** The app's bundled stylesheet URLs (`buildClient`'s `BuildManifest.css`) - the aggregate, injected
-   * as `<link rel="stylesheet">` in a page's `<head>`. Used as the fallback for any route absent from
-   * {@link routeStyles}. Omit ⇒ no links (dev, where Vite injects CSS, or a CSS-free app). */
-  readonly styles?: readonly string[]
-  /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) - `routeId → [chain CSS]`.
-   * When a matched route has an entry here, only those (its layout chain + own CSS) are linked instead
-   * 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[]>>
-  /** 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. */
-  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
-  /** 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
-   * default for unmapped routes) renders unlisted paths on-demand. */
-  readonly staticFallbacks?: Readonly<Record<string, "ssr" | "404">>
-  /** In-memory reference cache for explicitly `static` boundary values. It never persists payloads
-   * across processes; operated/durable cache implementations stay outside the public framework. */
-  readonly staticBoundaryCache?: import("./boundary.ts").StaticBoundaryCache
-  /** Observe every loader/action failure - for error-reporting plugins (Sentry-style). Called for
-   * real throws (not control-flow `Response`s like `redirect`), **before** the nearest `_error`
-   * boundary renders / a soft-nav 500 / a rethrow - so it sees errors that the boundary would
-   * otherwise hide. Observation only; its own throws are swallowed so a faulty reporter can't break
-   * rendering. (`beforeLoader` is intentionally omitted - the core HTTP hooks already cover
-   * pre-request work.) */
-  readonly onLoaderError?: (
-    error: unknown,
-    ctx: {
-      readonly request: Request
-      readonly params: Readonly<Record<string, string>>
-      readonly route: string
-    },
-  ) => 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.
- *
- * Needed because two conventions exist and both are reasonable. `createWebApp`'s auto-mount assumes a
- * backend that declares FULL paths (`server().post("/api/sync")`), which is right when the backend is
- * only ever mounted here. A backend that also runs standalone declares paths WITHOUT the prefix and
- * lets its own shell supply it - and mounting one of those here used to require the caller to wrap it
- * in a `Proxy` that rewrote every URL. Two apps wrote that same wrapper independently, which is the
- * signal that it belonged in the framework.
- *
- * 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 {
-  if ((typeof api !== "object" && typeof api !== "function") || api === null) return undefined
-  const explicit = (api as Partial<BackendMount>)[NIFRA_BACKEND_MOUNT]
-  if (typeof explicit !== "function") return undefined
-  return (request, platform) => explicit.call(api, request, platform)
-}
-
-// `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
-}
-
-/**
- * Build a nifra app from a route manifest: every route SSRs its layout chain via `renderPage`,
- * and a wildcard catch-all renders `_404` (or a plain 404). Reuses @nifrajs/core's router +
- * lifecycle, so matching, params, and precedence are battle-tested. fs-free - feed it a
- * manifest from `discoverRoutes` (`@nifrajs/web/fs`) at startup, so the served app stays portable.
- *
- * **Typed platform bindings.** Pass `Env` - `createWebApp<Env>({ … })` - to declare the app's Workers
- * bindings ONCE. It seeds the returned `Server`'s context with `{ env: Env }` (exactly as the backend's
- * `server<Env>()` does), so `app.fetch(req, { env })` / `toFetchHandler(app)` type-check the `env`
- * argument against the declared shape - no per-binding cast at the edge entry. Per-route loaders/actions
- * stay typed independently of this call: annotate them with `@nifrajs/client`'s `LoaderArgs<Api, Env>`
- * (same `Env`) so `ctx.env.MY_KV` is typed there too. Omit the parameter and `Env` is `unknown` - the
- * secure default; validate at the trust boundary before use.
- */
-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 } : {}
-  }
-  // 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 } : {}
-  }
-  // 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
-  // `app.fetch(req, { env })`; this is a compile-time-only seed (`server<Env>()` casts, doesn't store).
-  const app = server<Env>(options.server)
-  // Before the mount hooks and before every page route, so the order-scoped hooks (`derive`,
-  // `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)
-  // 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.
-  const apiPrefix = options.apiPrefix ?? "/api"
-  const apiStrip = options.apiStrip === true
-  const mountedApi = backendMountOf(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 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
-  }
-
-  /**
-   * 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) }
-  }
-
-  /** 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]),
-        })
-      } 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 "/"
-    }
-  }
-
-  /**
-   * 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),
-      ),
-    )
-    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)
-  }
-
-  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 }
-    }
-    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)
-        }
-        return new Response(ndjsonStream(payload, allDeferred), {
-          headers: { "content-type": "application/x-ndjson; charset=utf-8" },
-        })
-      }
-      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.
-          }
-        }
-        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 },
-        })
-      }
-      // 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,
-      })
-    })
-  }
-
-  // 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" },
-    })
-  })
-
-  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" },
-    })
-  })
-
-  // 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)))
-
-  return app
-}
-
-export interface GenerateClientEntryOptions {
-  /**
-   * Module specifier for the adapter's client runtime, e.g. `"@nifrajs/web-solid/client"`.
-   *
-   * **Contract:** the module MUST export `mountRouter({ router, routes, container })`. The generated
-   * bootstrap imports the specifier and calls it - so a self-executing entry that mounts on import
-   * builds cleanly and then does nothing, which is the trap this contract exists to name. The type is
-   * a bare `string` because a specifier is resolved by the bundler, not the type system, so the
-   * requirement is enforced by the bootstrap instead: it throws immediately, naming this module and
-   * the missing export, rather than failing later as `mountRouter is not a function`.
-   */
-  readonly clientModule: string
-  /** Turn a route/layout source file (relative to the routes dir) into an import specifier. */
-  readonly resolve: (file: string) => string
-}
-
-/**
- * Codegen: emit a client-entry module (as source) that lazily imports each route's layout chain
- * (so `Bun.build` with `splitting` code-splits one chunk per route), builds a `patterns` list,
- * then creates the agnostic router store (with a `loadModule` hook), installs history + form
- * interception, loads the initial route's chunk, and hydrates the adapter's stateful Router. The
- * initial route is derived from the URL (falling back to the server-injected route id, e.g.
- * `_404`), so after hydration the Router owns navigation and swaps routes without full reloads.
- * Bun has no `import.meta.glob`, so file-based routing needs this. Write the result to a file and
- * bundle it with `buildClient` / `Bun.build` (+ the adapter's transform).
- */
-export function generateClientEntry(
-  manifest: Manifest,
-  options: GenerateClientEntryOptions,
-): string {
-  const { clientModule, resolve } = options
-
-  const loaderRows: string[] = []
-  const patternRows: string[] = []
-  const statusRoutes: Record<number, string> = {}
-  // 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[] = []
-  // 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(", ")
-    return `() => Promise.all([${imports}])`
-  }
-  for (const route of manifest.routes) {
-    // layoutIds only reference layouts present in the manifest (buildManifest invariant).
-    const files = [
-      ...route.layoutIds.map((id) => (manifest.layouts[id] as LayoutEntry).file),
-      route.file,
-    ]
-    // Append the nearest `_error` file LAST, so loadModule can pull it off the tail and wrap the page.
-    const nearestErrorId = route.errorIds?.at(-1)
-    const errorFile =
-      nearestErrorId === undefined ? undefined : manifest.errors?.[nearestErrorId]?.file
-    if (errorFile !== undefined) {
-      files.push(errorFile)
-      errorRouteIds.push(route.id)
-    }
-    loaderRows.push(`  ${JSON.stringify(route.id)}: ${lazyLoader(files)},`)
-    patternRows.push(
-      `  { routeId: ${JSON.stringify(route.id)}, pattern: ${JSON.stringify(route.pattern)} },`,
-    )
-  }
-  if (manifest.notFound !== undefined) {
-    loaderRows.push(`  "_404": ${lazyLoader([manifest.notFound.file])},`)
-    statusRoutes[404] = "_404"
-  }
-  for (const [status, entry] of Object.entries(manifest.statusPages ?? {})) {
-    const routeId = `_${status}`
-    loaderRows.push(`  ${JSON.stringify(routeId)}: ${lazyLoader([entry.file])},`)
-    statusRoutes[Number(status)] = routeId
-  }
-
-  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"',
-    // 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.
-    `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
-    // hydration runners get a runtime identity from the exact adapter module that mounted the page. The
-    // registry is token-only and lives on a Symbol.for key so it cannot collide with app data.
-    "const __hydrationHook = __adapter.hydrationAssuranceHook",
-    'if (__hydrationHook && typeof __hydrationHook.runtimeIdentity === "function") {',
-    '  const __runtimeKey = Symbol.for("nifra.hydration.runtime")',
-    "  const __runtimeState = globalThis[__runtimeKey]",
-    "  const __identities = __runtimeState && Array.isArray(__runtimeState.identities) ? __runtimeState.identities : []",
-    "  globalThis[__runtimeKey] = { framework: __hydrationHook.framework, identities: [...__identities, __hydrationHook.runtimeIdentity()] }",
-    "}",
-    // The `clientModule` contract is a string specifier, so nothing type-checks that the module it
-    // names actually exports `mountRouter`. Without this the miss surfaces as
-    // "mountRouter is not a function" from inside a bundled chunk, at first paint, naming neither the
-    // module nor the requirement - a self-executing entry passes every build and fails only here.
-    `if (typeof mountRouter !== "function") throw new Error(${JSON.stringify(
-      `[nifra/web] clientModule ${JSON.stringify(clientModule)} does not export \`mountRouter\`. ` +
-        "A client module must export `mountRouter({ router, routes, container })` - it is called by " +
-        "the generated bootstrap, so a self-executing entry will not work. Use your adapter's " +
-        '`/client` entry (e.g. "@nifrajs/web-react/client"), or re-export mountRouter from it.',
-    )})`,
-    "const errorBoundary = __adapter.errorBoundary",
-    // A hot update that the framework cannot actually apply must end in a reload, not in nothing.
-    //
-    // Bun's dev server applies React Fast Refresh to JSX modules. For React that patches the component
-    // and preserves state. For Preact it does not - the module still LOOKS Fast-Refresh-able, so the
-    // update is accepted and then swallowed: `bun:beforeUpdate`/`bun:afterUpdate` both fire, the server
-    // logs a rebuild, and the page silently keeps rendering the old code. An edit that appears to do
-    // nothing is the worst failure mode in a dev loop - worse than a reload, because there is no signal
-    // to act on. An adapter that knows its framework is in that position says so, and the entry turns
-    // the swallowed update into an honest full reload.
-    'if (import.meta.hot && __adapter.hotUpdateNeedsReload) import.meta.hot.on("bun:afterUpdate", () => location.reload())',
-    `const errorRouteIds = new Set(${JSON.stringify(errorRouteIds)})`,
-    // Each route is a lazy loader: dynamic imports → Bun.build (splitting) emits one chunk per
-    // route, shared layouts/deps deduped into shared chunks, so a route's code loads only when
-    // visited. loadModule caches the [layouts…, page] component chain + the chain's meta list per id.
-    "const loaders = {",
-    ...loaderRows,
-    "}",
-    "const chains = {}",
-    "const metas = {}",
-    // routeId → the page module's `searchSchema` export (or undefined). Populated lazily with
-    // chains/metas so the mount can derive this route's typed `search` from the URL, matching the SSR.
-    "const searchSchemas = {}",
-    // routeId → the page's client-only search keys (`searchClientKeys`, or `[]`). The router reads this
-    // by reference to decide when a same-route search change can skip the loader fetch (re-render only).
-    "const searchClientKeys = {}",
-    // 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 = {}",
-    "const loadModule = async (id) => {",
-    "  if (chains[id]) return",
-    "  const mods = await loaders[id]()",
-    // For an error route the `_error` module is appended LAST: wrap the page (now second-to-last) in
-    // the adapter's boundary so a client render error renders the `_error` UI. DOM-transparent, so the
-    // hydrated tree matches the SSR markup (which has no boundary). Falls back to the plain chain when
-    // the adapter has no `errorBoundary`.
-    // `metas[id]` is the chain's `meta` exports in head order (outermost layout → … → page), so a
-    // soft-nav merges the layout chain's head with the page's - matching the SSR `<head>` (sitewide
-    // layout tags persist across client navigation, no flash of page-only head). `_error` carries no
-    // head (a terminal boundary), so it's excluded from the meta list for error routes.
-    "  if (errorBoundary && errorRouteIds.has(id)) {",
-    "    const fallback = mods[mods.length - 1].default",
-    "    const page = mods[mods.length - 2].default",
-    "    const layouts = mods.slice(0, mods.length - 2).map((m) => m.default)",
-    "    chains[id] = [...layouts, errorBoundary(fallback), page]",
-    "    metas[id] = mods.slice(0, mods.length - 1).map((m) => m.meta)",
-    // The search-schema CHAIN is the layout modules + page (all but the appended `_error`), so a layout's
-    // `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 ?? []",
-    "  } 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 ?? []",
-    "  }",
-    "  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.
-    "  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 }) })))",
-    "  routeHooks[id] = { clientLoader: page.clientLoader, clientAction: page.clientAction, boundaries }",
-    "}",
-    "const patterns = [",
-    ...patternRows,
-    "]",
-    // 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)",
-    // 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 : {},",
-    // 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).
-    "  path: location.pathname + location.search,",
-    `  data: mapDeferred(window.${DATA_GLOBAL}),`,
-    // Undefined on a page-only app, which is exactly what the router treats as "no layout data".
-    `  layoutData: window.${LAYOUT_DATA_GLOBAL} && window.${LAYOUT_DATA_GLOBAL}.map(mapDeferred),`,
-    `  boundaries: mapDeferred(window.${BOUNDARY_GLOBAL}),`,
-    // actionData (only set after a form POST) is in the initial state so the binding hydrates
-    // consistently with the server-rendered markup; mapped through `mapDeferred` too so a deferred
-    // action's placeholders become registry markers (a no-op when the action didn't defer).
-    `  actionData: mapDeferred(window.${ACTION_GLOBAL}),`,
-    "  pending: false,",
-    "}",
-    `const statusRoutes = ${JSON.stringify(statusRoutes)}`,
-    "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
-    // is a per-build artifact, so a hardcoded id is a guess: `renderPage({ rootId: "app" })` produced a
-    // perfect document that hydrated NOTHING, with no diagnostic, because the missing `#root` was
-    // swallowed by an `if (root)`. `renderPage` marks a custom container with `ROOT_ATTRIBUTE`; the
-    // default `#root` it leaves unmarked, which is what the fallback is for.
-    `const root = document.querySelector("body > div[${ROOT_ATTRIBUTE}]") ?? document.getElementById("root")`,
-    // Loud, because there is no recoverable case: this entry ships only in a document `renderPage`
-    // opened a container in, so reaching here means the document is not the one it was built for.
-    `if (!root) throw new Error(${JSON.stringify(
-      "[nifra/web] no hydration container found. The generated bootstrap mounts into the element " +
-        `renderPage opened the app in - the one marked \`${ROOT_ATTRIBUTE}\` when a custom \`rootId\` ` +
-        "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 })",
-    // 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.
-    "  router.hydrate().catch((error) => console.error('[nifra/web] clientLoader failed:', error))",
-    // Next frame: the adapter has committed its initial hydration, so handlers are attached. Flip the
-    // document to interactive (`data-nifra-hydrated` + `nifra:hydrated`) for apps to gate pre-hydration UI.
-    "  requestAnimationFrame(signalHydrated)",
-    "  router.subscribe(() => {",
-    "    const s = router.snapshot()",
-    // Merge the matched route's chain meta (layouts→page) into one head - same contract as SSR.
-    "    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 }",
-    "      applyHead(mergeHeads((metas[s.routeId] ?? [undefined]).map((m) => resolveMeta(m, args))))",
-    "    }",
-    "  })",
-    "})",
-  ].join("\n")}\n`
-}
-
-export interface GenerateRouteSearchTypesOptions {
-  /** Turn a route source file into a module specifier for a `typeof import(...)` type - the same contract
-   * as `generateClientEntry`'s `resolve`, but WITHOUT a file extension (a `.d.ts` imports a module, not a
-   * path). Relative to wherever the emitted `.d.ts` is written. */
-  readonly resolve: (file: string) => string
-  /** The module whose `RouteSearch` interface is augmented (default `"@nifrajs/web"`). Every adapter's
-   * `NavigateTarget` reads `@nifrajs/web`'s `RouteSearch`, so the default types `navigate` on all of them. */
-  readonly module?: string
-}
-
-/**
- * Codegen: emit a `.d.ts` that types cross-route `navigate({ to, search })` against each route's
- * `searchSchema`. It augments the {@link RouteSearch} map with `"<pattern>": SearchOf<typeof import(...)>`
- * for every **static** route (one with no `:param`/`*` segment - a concrete `to` a caller can pass; a
- * dynamic route's concrete path can't match its pattern key, so those keep the loose object form). Written
- * by `nifra sync-routes` next to the route tree and included in the app's `tsconfig`; because it is
- * regenerated from the route files, a `navigate` whose `search` no longer matches the route's schema
- * becomes a `tsc` error - the same drift guarantee as nifra's typed client, no hand-maintained map.
- */
-export function generateRouteSearchTypes(
-  manifest: Manifest,
-  options: GenerateRouteSearchTypesOptions,
-): string {
-  const { resolve, module = "@nifrajs/web" } = options
-  // Static routes only (no `:param` / `*` catch-all): their pattern IS a concrete `to`. Sorted for stable
-  // output; a dynamic route falls through to the loose `{ to: string; search?: Record<...> }` form.
-  const entries = manifest.routes
-    .filter((route) => !/[:*]/.test(route.pattern))
-    .map((route) => [route.pattern, resolve(route.file)] as const)
-    .sort((a, b) => (a[0] < b[0] ? -1 : 1))
-    .map(
-      ([pattern, spec]) =>
-        `    ${JSON.stringify(pattern)}: SearchOf<typeof import(${JSON.stringify(spec)})>`,
-    )
-  return `${[
-    "// GENERATED by @nifrajs/web generateRouteSearchTypes - typed cross-route navigate({ to, search }).",
-    "// Regenerated from the route files; a stale navigate search shape becomes a tsc error. Do not edit.",
-    'import type { SearchOf } from "@nifrajs/web"',
-    `declare module ${JSON.stringify(module)} {`,
-    "  interface RouteSearch {",
-    ...entries,
-    "  }",
-    "}",
-    "export {}",
-  ].join("\n")}\n`
-}
-
-export interface GenerateServerManifestOptions {
-  /** Turn a route/layout source file (relative to the routes dir) into an import specifier -
-   * same contract as `generateClientEntry`'s `resolve`. */
-  readonly resolve: (file: string) => string
-  /** The content-hashed client entry URL (from `buildClient`'s manifest), **baked** into the emitted
-   * module - a disk-less worker can't read `manifest.json` at runtime. */
-  readonly clientEntry: string
-  /** The app's aggregate stylesheet URLs (`buildClient`'s `BuildManifest.css`) - baked as
-   * `export const styles` so the server entry can hand them to `createWebApp` (→ `<link rel="stylesheet">`
-   * in `<head>`). Without this the built SSR page ships no CSS link and renders unstyled. */
-  readonly styles?: readonly string[] | undefined
-  /** 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
-  /** 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
-   * modes are fs-free with statically-analyzable specifiers; only the *when* differs. */
-  readonly lazy?: boolean
-}
-
-/**
- * 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
- * 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
- * `createWebApp`, unchanged) + `clientEntry` (baked). Write it to a file and bundle it into the worker
- * entry (see `buildServer` in `@nifrajs/web/build`).
- */
-// Route source files are emitted as EXTENSIONLESS import specifiers. An explicit `.tsx`/`.ts` in an
-// import is a hard error under a plain `tsc` (TS5097) unless `allowImportingTsExtensions` is set - which
-// only the nifra template tsconfig does - so the generated manifest failed a bare `tsc` with one error
-// per route. Every bundler and `moduleResolution` still resolves the extensionless form to the source
-// file, so dropping the extension costs nothing at build time and makes the output portable. Only a
-// known TS/JS source extension is stripped; the map KEY keeps its extension (it is the route identifier
-// `buildManifest` matches, not an import path).
-const SOURCE_EXTENSION = /\.(?:[mc]?tsx?|[mc]?jsx?)$/
-function moduleSpecifier(resolved: string): string {
-  return resolved.replace(SOURCE_EXTENSION, "")
-}
-
-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 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),
-    ]),
-  ].sort()
-  const header = [
-    "// GENERATED by @nifrajs/web generateServerManifest - route manifest for the disk-less edge",
-    "// (no filesystem; route imports are static specifiers the bundler resolves). buildManifest is",
-    "// the same pure logic discoverRoutes feeds, so patterns + layout chains match exactly.",
-    'import { buildManifest, type RouteModule } from "@nifrajs/web"',
-  ]
-  const clientEntryLine = `export const clientEntry = ${JSON.stringify(clientEntry)}`
-  // Baked stylesheet URLs so the server entry can pass them to createWebApp → <link rel="stylesheet">.
-  // 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 ?? {})}`
-  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
-    // `buildManifest` expects; the importer it builds calls the per-file loader.
-    const loaders = files.map(
-      (file) =>
-        `  ${jsStringLiteral(file)}: () => import(${jsStringLiteral(moduleSpecifier(resolve(file)))}),`,
-    )
-    return `${[
-      ...header,
-      "const loaders: Record<string, () => Promise<RouteModule>> = {",
-      ...loaders,
-      "}",
-      clientEntryLine,
-      stylesLine,
-      routeStylesLine,
-      "export const manifest = buildManifest(Object.keys(loaders), (file) => () => loaders[file]())",
-    ].join("\n")}\n`
-  }
-  // Eager: `import * as` per route (all bundled into the entry, parsed at boot). Index-based
-  // identifiers are collision-proof regardless of filename.
-  const imports = files.map(
-    (file, i) => `import * as m${i} from ${JSON.stringify(moduleSpecifier(resolve(file)))}`,
-  )
-  const entries = files.map((file, i) => `  ${JSON.stringify(file)}: m${i},`)
-  return `${[
-    ...header,
-    ...imports,
-    "const modules: Record<string, RouteModule> = {",
-    ...entries,
-    "}",
-    clientEntryLine,
-    stylesLine,
-    routeStylesLine,
-    "export const manifest = buildManifest(Object.keys(modules), (file) => () => Promise.resolve(modules[file]))",
-  ].join("\n")}\n`
-}
-
-/**
- * The two file-name conventions that decide what never reaches a browser: a `*.server` module is
- * EMPTIED in the client build, a `*.fn` module is REPLACED with client stubs.
- *
- * Exported because more than the bundlers need them. `nifra dev --bun` cannot transform (Bun's dev
- * bundler takes no plugins) so it must REFUSE instead, and a refusal driven by its own hand-written
- * glob drifts from the transform - which is how `.fn.mts` came to be stubbed by both build pipelines
- * and waved through by the guard that exists to stop it leaking. Anything deciding "is this module
- * server-only" should import the matcher rather than re-encode it.
- */
-export { SERVER_FN_MODULE, SERVER_ONLY_MODULE } from "./internal/server-boundary.ts"