@nifrajs/web 2.1.0 → 2.3.0

package/src/index.ts

@@ -1,9 +1,9 @@
 /**
- * @nifrajs/web — the framework-agnostic SSR core. It owns the render *seam* and the HTML
+ * @nifrajs/web - the framework-agnostic SSR core. It owns the render *seam* and the HTML
  * document orchestration, and knows nothing about any specific UI framework: a render
  * adapter (@nifrajs/web-solid, @nifrajs/web-react, …) supplies the actual render + hydrate.
  *
- * The core treats a "component" and a hydration "container" as opaque `unknown` — only
+ * The core treats a "component" and a hydration "container" as opaque `unknown` - only
  * the adapter interprets them. That keeps this package both framework-agnostic and free
  * of DOM types: it is pure server orchestration + string building.
  */
@@ -24,28 +24,39 @@ import {
   prepareDeferred,
 } from "./deferred.ts"
 import { isDraftEnabled } from "./draft.ts"
+import { trustedHeadAttributes } from "./internal/head-attributes.ts"
+import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.ts"
 import { ISR_REVALIDATE_HEADER } 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 {
+  createMatcher,
   DATA_HEADER,
+  NAV_FROM_HEADER,
   PRERENDERED_GLOBAL,
   REDIRECT_HEADER,
+  RETAIN_HEADER,
   REVALIDATE_HEADER,
+  STATUS_HEADER,
   type Submission,
 } 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.
+// Draft / preview mode - a signed cookie that flips `ctx.draft` for loaders + bypasses ISR for editors.
 export {
   DRAFT_COOKIE,
   type DraftCookieControls,
@@ -53,8 +64,10 @@ export {
   type EnableDraftOptions,
   enableDraft,
   isDraftEnabled,
+  type PreviewEndpointOptions,
+  previewEndpoint,
 } from "./draft.ts"
-// Font optimization — a CLS-safe `@font-face` generator + a preload `<link>` for self-hosted fonts.
+// Font optimization - a CLS-safe `@font-face` generator + a preload `<link>` for self-hosted fonts.
 export {
   type FontDisplay,
   type FontFace,
@@ -82,8 +95,7 @@ export {
   revalidateEndpoint,
   withISR,
 } from "./isr.ts"
-
-// File-based routing manifest — pure + fs-free. `discoverRoutes` (fs) lives in `@nifrajs/web/fs`.
+// File-based routing manifest - pure + fs-free. `discoverRoutes` (fs) lives in `@nifrajs/web/fs`.
 export {
   type Action,
   buildManifest,
@@ -91,6 +103,7 @@ export {
   filePathToPattern,
   filePathToPatterns,
   type GetStaticPaths,
+  type InertScriptType,
   type LayoutEntry,
   type LinkDescriptor,
   type Loader,
@@ -105,16 +118,37 @@ export {
   type StaticPath,
   type StaticPaths,
   type StaticRoutes,
+  type UnsafeScriptDescriptor,
 } from "./manifest.ts"
-// Navigation bridge — a DOM-free seam the browser layer (`installHistory`) populates so an adapter's
+// Navigation bridge - a DOM-free seam the browser layer (`installHistory`) populates so an adapter's
 // `useNavigate` (a route component, importing only this agnostic entry) reaches history-aware nav.
 export {
+  type Blocker,
+  type BlockerController,
+  type BlockerFunction,
+  type BlockerLocation,
+  type BlockerState,
   type BrowserNavigate,
   getBrowserNavigate,
+  IDLE_BLOCKER,
+  type NavigateFunction,
   type NavigateOptions,
+  type NavigateSearchOf,
+  type NavigateTargetInput,
+  type RouteSearch,
+  registerBlocker,
+  resolveNavigate,
+  setBlockerController,
   setBrowserNavigate,
 } from "./navigation.ts"
-// Keyed query-cache (agnostic) — a `query(key, fn)` primitive (dedup + staleness + invalidation + GC)
+// public/ - user-authored static files, served identically in dev and production by one handler.
+export {
+  type PublicDirCache,
+  resolvePublicPath,
+  type ServePublicDirOptions,
+  servePublicDir,
+} from "./public-dir.ts"
+// Keyed query-cache (agnostic) - a `query(key, fn)` primitive (dedup + staleness + invalidation + GC)
 // consumed by the per-adapter `useQuery`/`createQuery` bindings.
 export {
   createMutation,
@@ -135,7 +169,7 @@ export {
   type QueryState,
   type QueryStatus,
 } from "./query.ts"
-// Agnostic client-side router core (pure + DOM-free) — consumed by per-adapter Router bindings.
+// 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 {
   type ClientRouter,
@@ -147,35 +181,38 @@ export {
   type FetcherState,
   type FetchRouteData,
   type MountRouterOptions,
+  NAV_FROM_HEADER,
   REDIRECT_HEADER,
+  RETAIN_HEADER,
   REVALIDATE_HEADER,
   type RouteMatch,
   type RoutePattern,
   type RouterState,
+  STATUS_HEADER,
   type Submission,
   type SubmitOptions,
 } from "./router.ts"
-// Deferred loader data (`defer()` + the `Deferred<T>` type) — consumed by the adapter's `<Await>`.
+// Deferred loader data (`defer()` + the `Deferred<T>` type) - consumed by the adapter's `<Await>`.
 export { type Deferred, defer }
 
 /** 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. */
+ * 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
+ * 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,
+ * 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
+ *  - 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.
+ *  - 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.
@@ -193,11 +230,25 @@ export {
   type RenderAdapterConformanceFixture,
 } from "./conformance.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"
+
 /** The data handed to a route component. Opaque to the core. `actionData` is the return of a
  * route `action` after a POST (absent on plain GETs). `pending` + `submission` are client-only
- * (absent on SSR): they drive **optimistic UI** — render from `submission.formData` while `pending`. */
+ * (absent on SSR): they drive **optimistic UI** - render from `submission.formData` while `pending`. */
 export interface RenderProps {
   readonly data: unknown
+  /**
+   * Per-layout loader data, aligned index-for-index with the layout prefix of `chain`.
+   *
+   * Absent when no layout in the chain exports a `loader`, so a page-only app is byte-identical to
+   * before. An adapter that does not read it renders exactly as it did; one that does passes
+   * `layoutData[i]` to `chain[i]`.
+   */
+  readonly layoutData?: readonly unknown[]
   readonly actionData?: unknown
   /** True while a client navigation or submit is in flight (client-only; absent/false on SSR). */
   readonly pending?: boolean
@@ -210,10 +261,15 @@ export interface RenderProps {
    * SSR (from the request match) and on client navigation (from router state) so an adapter's
    * `useParams` reads the same value on both, with no hydration mismatch. Absent ⇒ no params (`{}`). */
   readonly params?: Readonly<Record<string, string>>
-  /** The current URL's `pathname + search` (no hash — the hash never reaches the server). Threaded on
+  /** The current URL's `pathname + search` (no hash - the hash never reaches the server). Threaded on
    * SSR and client alike so an adapter's `useLocation`/`useSearchParams` hydrate consistently. Absent
    * on adapters/callers that don't supply it (treated as `""`). */
   readonly path?: string
+  /** The route's typed, validated search params (the value the loader also gets as `ctx.search`),
+   * threaded to the adapter's `useSearch`. Derived identically on SSR (from the request) and on client
+   * navigation (adapter mount) via the shared `searchOf`, so a component reading it hydrates with no
+   * drift. Absent ⇒ no search context (`{}`). */
+  readonly search?: Record<string, unknown>
 }
 
 /**
@@ -227,7 +283,7 @@ export interface RenderAdapter {
    * (the loader data); each layout wraps the child via its `children`. Returns (or resolves to)
    * a Web `ReadableStream<Uint8Array>`: a streaming renderer flushes the shell first and streams
    * Suspense boundaries as they resolve; a non-streaming renderer may return a one-chunk stream.
-   * May be async — e.g. React resolves once the shell is renderable, so a shell-render throw can
+   * May be async - e.g. React resolves once the shell is renderable, so a shell-render throw can
    * still map to an error status before any byte is sent.
    */
   renderToStream(
@@ -237,10 +293,10 @@ export interface RenderAdapter {
   /**
    * Server (optional): render the chain to a complete HTML **string** in one pass, with the same
    * hydration markers `renderToStream` produces. When provided, `renderPage` uses it for any page
-   * that does **not** `defer()` — buffering the document is faster than the streaming pipeline there,
+   * that does **not** `defer()` - buffering the document is faster than the streaming pipeline there,
    * because the framework's synchronous renderer (React `renderToString`, Solid `renderToString`,
    * Preact `render`, Vue `renderToString`, Svelte `render`) is markedly cheaper than its streaming
-   * renderer — most visibly on Bun, where React Fizz / Solid `renderToStream` are the heaviest. Pages
+   * renderer - most visibly on Bun, where React Fizz / Solid `renderToStream` are the heaviest. Pages
    * that `defer()` keep the streaming path (progressive `<Await>` needs it). Markup MUST be
    * hydration-equivalent to `renderToStream`; a throw surfaces like the streaming shell-readiness
    * await (the `_error` boundary maps it to a status). Omit it to always stream.
@@ -250,11 +306,14 @@ export interface RenderAdapter {
    * Server: per-document bootstrap markup injected into `<head>` that the client
    * `hydrate` requires (Solid: `generateHydrationScript()`). Empty string if none.
    */
-  hydrationHead(): string
+  hydrationHead(nonce?: string): string
 }
 
 /** Global the server serializes loader data into; the client reads it to hydrate. */
 export const DATA_GLOBAL = "__NIFRA_DATA__"
+/** Per-layout loader data for hydration. Emitted ONLY when some layout in the chain has a loader, so
+ * a page-only app's HTML is byte-identical to before layout loaders existed. */
+export const LAYOUT_DATA_GLOBAL = "__NIFRA_LAYOUT_DATA__"
 
 /** Global the server writes the matched route id into; the client uses it to pick the chain. */
 export const ROUTE_GLOBAL = "__NIFRA_ROUTE__"
@@ -264,12 +323,25 @@ export const ROUTE_GLOBAL = "__NIFRA_ROUTE__"
 export const ACTION_GLOBAL = "__NIFRA_ACTION__"
 
 /**
- * Pre-hydration form guard — a tiny inline script flushed in `<head>` (it runs in the window between
+ * Marker attribute on the app container, emitted ONLY when `rootId` is not the default.
+ *
+ * `rootId` is a per-RENDER option; the client entry is a per-BUILD artifact, so it cannot be
+ * generated knowing which id a given render will use. The container therefore announces itself, and
+ * the entry finds it by this attribute before falling back to `#root`. It has to be the DOM rather
+ * than another `window.__NIFRA_*` global: a second copy of the id can drift from the markup, while
+ * this is written by the same expression that writes the id and cannot.
+ *
+ * Absent on a default render, so an app that never sets `rootId` emits the same bytes it always has.
+ */
+export const ROOT_ATTRIBUTE = "data-nifra-root"
+
+/**
+ * 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
+ * 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
@@ -287,12 +359,12 @@ export const PRE_HYDRATION_GUARD =
 /**
  * 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`
+ * (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.
+// Shared, stateless - allocated once at module load, not per render/stream.
 const TEXT_ENCODER = new TextEncoder()
 
 type MaybePromise<T> = T | Promise<T>
@@ -325,21 +397,27 @@ export interface RenderedPage {
 
 export interface RenderPageOptions {
   readonly adapter: RenderAdapter
-  /** The layout chain to render — outermost layout → page (opaque; the adapter renders it). */
+  /** 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
+  /** 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). */
-  readonly clientEntry: string
+  /**
+   * 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
+   * 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
+   * `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
@@ -350,57 +428,80 @@ export interface RenderPageOptions {
   readonly revalidate?: number
   /** 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})
+  /** 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
+  /** 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[]
   /** 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
+  /** 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
+   * 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). `<link>` attributes are name-validated
-   * (any letter/digit/hyphen name — covers `rel`/`href`/`hreflang`/`crossorigin`/`media`/`sizes`/`as`/
-   * `integrity`/`fetchpriority`/…) and value-escaped against XSS. */
+   * `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"`). */
+  /** 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
+  /** 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
+   * 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
 }
 
 /**
- * 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`.
+ * `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: RenderPageOptions): MaybePromise<Response> {
+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: RenderPageOptions): MaybePromise<RenderedPage> {
+export function renderPageResult(options: RenderPageInput): MaybePromise<RenderedPage> {
   const {
     adapter,
     chain,
@@ -418,9 +519,15 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
     rootId = "root",
     hydrate = true,
     islandScripts = [],
+    nonce,
+    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
+  // 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
@@ -428,20 +535,41 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
       : `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
+  // 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)
-  const allDeferred = actionSplit ? [...deferred, ...actionSplit.deferred] : deferred
+    actionData === undefined
+      ? undefined
+      : prepareDeferred(actionData, deferred.length + layoutDeferred.length)
+  const allDeferred = [...deferred, ...layoutDeferred, ...(actionSplit ? actionSplit.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 deferredRuntime = allDeferred.length > 0 ? `<script>${DEFERRED_RUNTIME}</script>` : ""
+  const deferredRuntime =
+    allDeferred.length > 0 ? `<script${nonceAttr}>${DEFERRED_RUNTIME}</script>` : ""
   // Matched-route chunk preloads, concatenated directly (skip the `filter().map()`
-  // intermediate arrays — and the whole loop — on the common no-extra-preload render). De-duped
+  // intermediate arrays - and the whole loop - on the common no-extra-preload render). De-duped
   // against the entry, which is preloaded separately below.
   let preloadLinks = ""
   if (preload.length > 0) {
@@ -450,7 +578,7 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
         preloadLinks += `<link rel="modulepreload" href="${escapeAttr(url)}">`
     }
   }
-  // The matched route's stylesheets — `<link rel="stylesheet">` in `<head>` so CSS arrives with the
+  // 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, so
   // `styles` is empty there.
@@ -458,41 +586,62 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
   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>` (below), 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` (an island page
+  // so the fetch starts immediately, in parallel with parsing - regardless of `hydrate` (an island page
   // is typically hydrate:false). Without this, a heavy island bundle on a cold first load leaves its
   // server-rendered placeholder visible until that late, un-prefetched fetch lands ("stuck loading").
   let islandPreloads = ""
   for (const src of islandScripts)
     islandPreloads += `<link rel="modulepreload" href="${escapeAttr(src)}">`
-  // Shell — flushed before the app finishes rendering: `<head>` (title, meta, hydration head) + the
-  // open container. `modulepreload` of the client entry — plus the matched route's own chunks
-  // (`preloadLinks`) — lets the JS download while the body streams. One template literal (no
-  // intermediate array + `join`) — byte-identical to the prior output.
+  // Shell - flushed before the app finishes rendering: `<head>` (title, meta, hydration head) + the
+  // open container. `modulepreload` of the client entry - plus the matched route's own chunks
+  // (`preloadLinks`) - lets the JS download while the body streams. One template literal (no
+  // intermediate array + `join`) - byte-identical to the prior output.
   // A non-hydrated page (e.g. an `_error` boundary) omits the client-entry preload, route-chunk
-  // preloads, and deferred runtime — there's no client takeover to feed.
+  // preloads, and deferred runtime - there's no client takeover to feed.
   const hydrationLinks = hydrate
-    ? `<link rel="modulepreload" href="${escapeAttr(clientEntry)}">${preloadLinks}${deferredRuntime}`
+    ? `<link rel="modulepreload" href="${escapeAttr(clientEntry ?? "")}">${preloadLinks}${deferredRuntime}`
     : ""
   // 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>${PRE_HYDRATION_GUARD}</script>` : ""
-  const shellHtml = `<!doctype html><html lang="en"><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}${hydrationLinks}${islandPreloads}${adapter.hydrationHead()}</head><body><div id="${escapeAttr(rootId)}">`
+  const hydrationGuard = hydrate ? `<script${nonceAttr}>${PRE_HYDRATION_GUARD}</script>` : ""
+  // `<html>` attributes. `lang` defaults to `"en"` (so an app that never sets it is byte-identical to
+  // before); `dir` is omitted entirely when unset, which IS HTML's `ltr` default - emitting it
+  // unconditionally would change every existing app's output for no gain. Both attribute-escaped.
+  // `client.ts`'s `applyHead` mirrors this exact defaulting on soft-nav, so a hard load and a client
+  // navigation to the same URL produce the same `<html>` (no drift on a multilingual site).
+  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. A
+  // static attribute name with no value, so `rootId` never reaches the markup twice and there is
+  // nothing here to escape. Omitted on the default so existing output is unchanged.
+  const rootMarker = rootId === "root" ? "" : ` ${ROOT_ATTRIBUTE}`
+  const hydrationHead = adapter
+    .hydrationHead(nonce)
+    .replace(/<script(?![^>]*\bnonce=)(?=[\s>])/g, `<script${nonceAttr}`)
+  const shellHtml = `<!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}${hydrationLinks}${islandPreloads}${hydrationHead}</head><body><div id="${escapeAttr(rootId)}"${rootMarker}>`
   // 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
+  // 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.
-  // Island bundles load regardless of `hydrate` — a static page (hydrate:false) ships no framework
+  // 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)}"></script>`
+    islandTags += `<script type="module" src="${escapeAttr(src)}"${nonceAttr}></script>`
   const tailHtml = `${
     hydrate
-      ? `<script>${route}${action}${prerendered}window.${DATA_GLOBAL}=${serializeData(forClient)}</script><script type="module" src="${escapeAttr(clientEntry)}"></script>`
+      ? `<script${nonceAttr}>${route}${action}${prerendered}${layoutTail}window.${DATA_GLOBAL}=${serializeData(forClient)}</script><script type="module" src="${escapeAttr(clientEntry ?? "")}"${nonceAttr}></script>`
       : ""
   }${islandTags}</body></html>`
   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.
@@ -501,10 +650,17 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
     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
+    // 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) }
+      : {}),
   }
 
   // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
@@ -537,6 +693,7 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
     tailHtml,
     status,
     headers,
+    nonceAttr,
   ).then((response) => new ResponseRenderedPage(response))
 }
 
@@ -550,8 +707,9 @@ async function renderStreamedPage(
   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
+  // 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.
@@ -560,7 +718,7 @@ async function renderStreamedPage(
   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)
+  const body = streamDocument(shell, appStream, closeRoot, allDeferred, tail, enc, nonceAttr)
   return new Response(body, { status, headers })
 }
 
@@ -614,8 +772,8 @@ function htmlResponse(body: string, init: ResponseInit): 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
+ * 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(
@@ -625,6 +783,7 @@ function streamDocument(
   deferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
   tail: Uint8Array,
   enc: TextEncoder,
+  nonceAttr: string,
 ): ReadableStream<Uint8Array> {
   return new ReadableStream({
     async start(controller) {
@@ -637,23 +796,23 @@ function streamDocument(
           controller.enqueue(value)
         }
         controller.enqueue(closeRoot)
-        // Stream each resolution as ITS OWN promise settles — NOT in array order. A slow
+        // 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>window.__nifraResolve(${d.id},${value})</script>`),
+                enc.encode(`<script${nonceAttr}>window.__nifraResolve(${d.id},${value})</script>`),
               )
             } catch (err) {
-              // A rejected deferred streams __nifraReject (the client `<Await>` surfaces it) — it must
+              // 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>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`,
+                  `<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`,
                 ),
               )
             }
@@ -688,12 +847,12 @@ function isSameOriginPath(location: string): boolean {
 }
 
 /**
- * Build a redirect `Response` — return it from a route `action` for the Post/Redirect/Get
+ * Build a redirect `Response` - 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
+ * 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 returns the action's `Response` verbatim.
  *
@@ -705,21 +864,223 @@ export function redirect(location: string, options: RedirectOptions = {}): Respo
       `[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//"), 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
+  // 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.`,
+      `[nifra/web] redirect location contains a CR/LF character - refusing to emit a header-injecting redirect.`,
     )
   }
   return new Response(null, { status: options.status ?? 303, 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
+}
+
+/** 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"]
+}>
+
+/**
+ * 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
+ * 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[]
@@ -729,7 +1090,7 @@ export interface RevalidateResult<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 —
+ * 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>`).
  */
@@ -754,10 +1115,10 @@ function escapeHtml(value: string): string {
 /**
  * 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 `</`
+ * 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
+ * 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.
  */
@@ -776,27 +1137,12 @@ function escapeAttr(value: string): string {
     .replaceAll(">", "&gt;")
 }
 
-// Attribute-NAME guard for emitted `<meta>`/`<link>` tags. Intentionally a *name-shape* allowlist, not
-// a hardcoded per-attribute one: any letter/digit/hyphen name beginning with a letter is permitted, so
-// every standard `<link>` attribute flows through — `rel`, `href`, `hreflang`, `crossorigin`, `media`,
-// `sizes`, `type`, `as`, `title`, `integrity`, `referrerpolicy`, `imagesrcset`, `imagesizes`,
-// `disabled`, `color`, `fetchpriority` — alongside `<meta>`'s `name`/`property`/`content` and custom
-// `data-*`. A hardcoded list would silently drop valid attrs (the bug this guards against: `hreflang`
-// /`crossorigin` getting filtered out). What it rejects is name-shape abuse only — a name with a space,
-// `=`, `>`, quote, or a leading digit can't break out of the tag. Attribute VALUES are escaped
-// separately (they may carry loader data → XSS), so a widened name set never widens the injection
-// surface. Names that fail the shape check are dropped.
-const SAFE_ATTR_NAME = /^[a-zA-Z][a-zA-Z0-9-]*$/
-
-/** Serialize a meta/link tag's attributes: validate the name shape (see {@link SAFE_ATTR_NAME}) +
- * escape the value against XSS. Invalid attribute names are dropped. Values follow the HTML attribute
- * conventions {@link LinkDescriptor} types: a string renders `name="escaped"`; `true` renders the bare
- * boolean attribute (`disabled`); `false` and `undefined` are skipped (a conditionally-absent attr). */
-function tagAttrs(attrs: Record<string, string | boolean | undefined>): string {
+/** 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 Object.entries(attrs)) {
-    if (value === undefined || value === false) continue // omitted / absent boolean attribute
-    if (!SAFE_ATTR_NAME.test(name)) continue // name-shape abuse — dropped (see SAFE_ATTR_NAME)
+  for (const [name, value] of trusted) {
     if (out !== "") out += " "
     out += value === true ? name : `${name}="${escapeAttr(value)}"`
   }
@@ -810,11 +1156,19 @@ function tagAttrs(attrs: Record<string, string | boolean | undefined>): string {
 // 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 {@link tagAttrs} (name shape-
- * validated, value HTML-escaped), 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
+ * 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 {
@@ -822,14 +1176,43 @@ function headTags(head: Meta | undefined): string {
   const cached = headTagsCache.get(head)
   if (cached !== undefined) return cached
   let out = ""
-  if (head.meta !== undefined) for (const m of head.meta) out += `<meta ${tagAttrs(m)} data-nifra>`
-  if (head.link !== undefined) for (const l of head.link) out += `<link ${tagAttrs(l)} data-nifra>`
-  // `<script>` slot — JSON-LD + other inert head scripts. `type` is attribute-escaped; `content` is
+  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)
-      out += `<script type="${escapeAttr(s.type ?? "application/ld+json")}" data-nifra>${escapeScriptContent(s.content)}</script>`
+    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
 }
@@ -852,7 +1235,7 @@ export function canonical(href: string): LinkDescriptor {
   return { rel: "canonical", href }
 }
 
-/** Inputs for {@link openGraph} — the common Open Graph properties. All optional; only the provided
+/** 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
@@ -861,7 +1244,7 @@ export interface OpenGraphInput {
   readonly image?: string
   /** Canonical URL of the page (`og:url`). */
   readonly url?: string
-  /** Object type (`og:type`) — `"website"`, `"article"`, … Default `"website"`. */
+  /** Object type (`og:type`) - `"website"`, `"article"`, … Default `"website"`. */
   readonly type?: string
 }
 
@@ -873,8 +1256,8 @@ export interface OpenGraphInput {
  * export const meta = { meta: [...openGraph({ title: "Nifra", image: "https://site.com/og.png" })] }
  * ```
  */
-export function openGraph(input: OpenGraphInput): Array<Record<string, string>> {
-  const tags: Array<Record<string, string>> = []
+export function openGraph(input: OpenGraphInput): MetaDescriptor[] {
+  const tags: MetaDescriptor[] = []
   const add = (property: string, content: string | undefined): void => {
     if (content !== undefined) tags.push({ property, content })
   }
@@ -882,7 +1265,7 @@ export function openGraph(input: OpenGraphInput): Array<Record<string, string>>
   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.
+  // `og:type` always present (the spec's required property) - default "website" when unset.
   tags.push({ property: "og:type", content: input.type ?? "website" })
   return tags
 }
@@ -902,6 +1285,30 @@ 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,
+  }
+}
+
 /**
  * Merge a route's `<head>` contributions from its layout chain + the page into one {@link Meta}.
  *
@@ -909,33 +1316,39 @@ export function jsonLd(data: Record<string, unknown>): ScriptDescriptor {
  * `meta` to put sitewide tags (`hreflang`, `preconnect`, a default `<title>`, …) on every page below
  * it. `heads` is passed **outermost layout → … → innermost layout → page** (the same order as the
  * render chain), and merges:
- *  - **`title`** — *nearest-wins*: the last defined value across the list, so the page overrides an
+ *  - **`title`** - *nearest-wins*: the last defined value across the list, so the page overrides an
  *    inner layout, which overrides an outer one. A layout `title` is the section default; an undefined
  *    page `title` keeps it.
- *  - **`meta` / `link`** — *concatenated* in list order (outermost first, page last). Duplicate-tag
+ *  - **`meta` / `link`** - *concatenated* in list order (outermost first, page last). Duplicate-tag
  *    de-duplication is the caller's concern; the framework emits exactly what's declared so a layout
  *    can ship N `<link rel="alternate" hreflang>` tags and a page can add its own canonical.
  *
  * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a
- * static (by-reference) `Meta` and there is exactly one — otherwise a new object each call. That is
+ * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is
  * fine: {@link headTags}'s memo is keyed on identity, so a per-request merge simply recomputes (its
  * content can vary with loader data anyway).
  */
 export function mergeHeads(heads: readonly Meta[]): Meta {
-  // Single-head fast path (a route with no layout `meta`, by far the common case) — return the
+  // Single-head fast path (a route with no layout `meta`, by far the common case) - return the
   // resolved object by reference so headTags' identity-keyed memo hits across requests for static meta.
   if (heads.length === 1) return heads[0] as Meta
   let title: string | undefined
-  const meta: Array<Record<string, string>> = []
+  let lang: string | undefined
+  let dir: Meta["dir"]
+  const meta: MetaDescriptor[] = []
   const link: LinkDescriptor[] = []
   const script: ScriptDescriptor[] = []
+  const unsafeScript: UnsafeScriptDescriptor[] = []
   for (const h of heads) {
     if (h.title !== undefined) title = h.title // nearest-wins: later (more specific) overrides
+    if (h.lang !== undefined) lang = h.lang // nearest-wins, like title
+    if (h.dir !== undefined) dir = h.dir
     if (h.meta !== undefined) meta.push(...h.meta)
     if (h.link !== undefined) link.push(...h.link)
     if (h.script !== undefined) script.push(...h.script) // concatenated like meta/link (outermost first)
+    if (h.unsafeScript !== undefined) unsafeScript.push(...h.unsafeScript)
   }
-  // Build the result with only the fields that were actually contributed — an empty `meta`/`link`/
+  // Build the result with only the fields that were actually contributed - an empty `meta`/`link`/
   // `script` array would otherwise be a spurious (if harmless) key. A mutable local; the cast to `Meta`
   // is sound because a key is assigned only when defined (so `exactOptionalPropertyTypes` never sees
   // `undefined`).
@@ -944,11 +1357,17 @@ export function mergeHeads(heads: readonly Meta[]): Meta {
     meta?: Meta["meta"]
     link?: Meta["link"]
     script?: Meta["script"]
+    unsafeScript?: Meta["unsafeScript"]
+    lang?: string
+    dir?: Meta["dir"]
   } = {}
   if (title !== undefined) merged.title = title
   if (meta.length > 0) merged.meta = meta
   if (link.length > 0) merged.link = link
   if (script.length > 0) merged.script = script
+  if (unsafeScript.length > 0) merged.unsafeScript = unsafeScript
+  if (lang !== undefined) merged.lang = lang
+  if (dir !== undefined) merged.dir = dir
   return merged as Meta
 }
 
@@ -959,7 +1378,7 @@ export interface CreateWebAppOptions {
   readonly clientEntry: string
   /** Default document title for all pages. */
   readonly title?: string
-  /** Injected into each loader's `ctx.api` — typically an `inProcessClient(app)` (typed
+  /** 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
@@ -975,19 +1394,46 @@ export interface CreateWebAppOptions {
    * 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
+  /** 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
+  /** 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]`.
+  /** 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`. */
@@ -998,14 +1444,14 @@ export interface CreateWebAppOptions {
   readonly prerenderedPaths?: readonly string[]
   /** 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
+   * `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">>
-  /** Observe every loader/action failure — for error-reporting plugins (Sentry-style). Called for
+  /** 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
+   * 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
+   * rendering. (`beforeLoader` is intentionally omitted - the core HTTP hooks already cover
    * pre-request work.) */
   readonly onLoaderError?: (
     error: unknown,
@@ -1017,7 +1463,7 @@ export interface CreateWebAppOptions {
   ) => void
 }
 
-/** The handler context fields createWebApp uses — a structural subset of nifra's `Context`. */
+/** The handler context fields createWebApp uses - a structural subset of nifra's `Context`. */
 interface RouteContext {
   readonly params: Record<string, string>
   readonly req: Request
@@ -1025,6 +1471,27 @@ interface RouteContext {
   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.
@@ -1039,15 +1506,15 @@ function backendMountOf(api: unknown): BackendMountHandler | undefined {
 /**
  * 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
+ * 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
+ * **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
+ * 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
+ * (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>(
@@ -1067,7 +1534,7 @@ export function createWebApp<Env = unknown>(
     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
+  // (`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]
@@ -1080,21 +1547,34 @@ export function createWebApp<Env = unknown>(
   const app = server<Env>()
   // 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`)
+  // 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)
-  if (apiPrefix !== "" && mountedApi !== undefined) {
+  // 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 } = new URL(req.url)
-      // Exactly the prefix (`/api`) or a sub-path (`/api/…`) — NOT a sibling like `/apixyz` that merely
+      // 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 (pathname === apiPrefix || pathname.startsWith(`${apiPrefix}/`)) {
-        return mountedApi(req, platform)
+      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
     })
@@ -1103,24 +1583,219 @@ export function createWebApp<Env = unknown>(
   // 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 = (
-    route: RouteEntry,
-  ): Promise<ReadonlyArray<{ default: unknown; meta?: MetaInput }>> =>
-    Promise.all(
+  // 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, new URL(request.url).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],
+      new URL(request.url).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: ReadonlyArray<{ default: unknown; meta?: MetaInput }>,
+    layoutModules: LoadedLayoutModules,
     page: RouteModule,
     metaArgs: MetaArgs,
   ): { chain: unknown[]; head: Meta } => {
@@ -1136,11 +1811,31 @@ export function createWebApp<Env = unknown>(
   const dirOfId = (id: string, suffix: string): string =>
     id === suffix ? "" : id.slice(0, id.length - suffix.length - 1)
 
-  // The request's origin (scheme + host + port, NO trailing slash) — the one server fact `meta()` needs
+  /**
+   * 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 —
+  // (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 {
@@ -1150,7 +1845,7 @@ export function createWebApp<Env = unknown>(
     }
   }
 
-  // The request's `pathname + search` — threaded into `renderPage` so an adapter's `useLocation`/
+  // 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.
@@ -1165,11 +1860,11 @@ export function createWebApp<Env = unknown>(
 
   /**
    * 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
+   * 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).
+   * message }` - never the stack (no internals leak into HTML).
    */
   const renderError = async (
     route: RouteEntry,
@@ -1200,36 +1895,96 @@ export function createWebApp<Env = unknown>(
     })
   }
 
-  // The 404 response — the `_404` page (status 404) or a plain-text fallback. Shared by the wildcard
+  // 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 = async (path?: string): Promise<Response | RenderedPage> => {
-    if (manifest.notFound === undefined) {
-      return new Response("Not Found", {
-        status: 404,
-        headers: { "content-type": "text/plain; charset=utf-8" },
-      })
+  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 })
     }
-    const { default: notFound } = await manifest.notFound.load()
+    // 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: [notFound],
+      chain: [component],
       data: null,
       clientEntry,
-      routeId: "_404",
-      // `_404` hydrates, so its SSR `path` must equal the client's initial `location.pathname+search`
-      // (an unmatched path yields no params → `{}`), or a `useLocation` on the 404 page would drift.
+      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: 404,
-      ...preloadOf("_404"),
-      ...stylesOf("_404"),
+      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
+    // 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"
     app.register("GET", route.pattern, undefined, async (c: RouteContext) => {
@@ -1242,20 +1997,50 @@ export function createWebApp<Env = unknown>(
       const mod = await route.load()
       const draft = await draftFlag(c.req)
       let data: unknown
+      let layoutData: readonly unknown[] | undefined
+      let layoutModules: LoadedLayoutModules | undefined
+      let layoutRetained: readonly number[] = []
       try {
-        data = mod.loader
-          ? await mod.loader({
-              params: c.params,
-              request: c.req,
-              req: c.req,
-              api,
-              env: c.env,
-              draft,
-            })
-          : null
+        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
+        // 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] = await Promise.all([
+          mod.loader
+            ? mod.loader({ ...ctx, search: searchChainOf(run.modules, mod, c.req) })
+            : null,
+          run.pending, // a non-gate layout loader that rejects must still surface, not go unhandled
+        ])
+        data = pageData
+        layoutData = run.layoutData
       } 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 `Response` is a control-flow signal (a guard's `redirect(...)`, an explicit error
-        // response) — let it propagate to core, which returns it as-is. Real errors render the nearest
+        // response) - let it propagate to core, which returns it as-is. Real errors render the nearest
         // `_error` boundary, if any; with none, rethrow (unchanged 500 behavior).
         if (err instanceof Response) throw err
         // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
@@ -1266,9 +2051,9 @@ export function createWebApp<Env = unknown>(
             // A faulty reporter must never break error rendering.
           }
         }
-        const errorId = route.errorIds?.at(-1)
+        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
+        // 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", {
@@ -1276,28 +2061,53 @@ export function createWebApp<Env = unknown>(
             headers: { "content-type": "text/plain; charset=utf-8" },
           })
         }
-        return renderError(route, errorId, err)
+        return renderError(route, errorId, withDuplicateInstanceHint(err))
       }
-      // Client-side navigation asks (via the X-Nifra-Data header) for just the loader data — no full
+      // 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.
+      // same auth - only the transport differs.
       if (c.req.headers.get(DATA_HEADER) !== null) {
-        const { forClient, deferred } = prepareDeferred(data)
-        if (deferred.length === 0) return Response.json(data ?? null)
-        return new Response(ndjsonStream(forClient, deferred), {
+        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 payload =
+          layoutData === undefined
+            ? pageSplit.forClient
+            : {
+                v: 1 as const,
+                data: pageSplit.forClient,
+                layoutData: layoutSplits.map((split) => split.forClient),
+                retained: layoutRetained,
+              }
+        // 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 (deferred.length === 0) {
+          return Response.json(payload ?? null)
+        }
+        return new Response(ndjsonStream(payload, deferred), {
           headers: { "content-type": "application/x-ndjson; charset=utf-8" },
         })
       }
-      const { chain, head } = resolveChainAndHead(await loadLayoutModules(route), mod, {
-        data,
-        params: c.params,
-        origin: originOf(c.req),
-      })
+      const { chain, head } = resolveChainAndHead(
+        layoutModules ?? (await loadLayoutModules(route)),
+        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
+        // 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,
@@ -1308,7 +2118,12 @@ export function createWebApp<Env = unknown>(
           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 } : {}),
           ...preloadOf(route.id),
           ...stylesOf(route.id),
           prerenderedPaths: options.prerenderedPaths ?? [],
@@ -1317,6 +2132,8 @@ export function createWebApp<Env = unknown>(
           ...titleOption,
         })
       } catch (err) {
+        // Same precedence as the loader catch above - a `meta()` may signal too.
+        if (isStatusSignal(err)) return renderStatusSignal(c.req, err)
         if (err instanceof Response) throw err
         // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
         if (options.onLoaderError !== undefined) {
@@ -1326,15 +2143,15 @@ export function createWebApp<Env = unknown>(
             // A faulty reporter must never break error rendering.
           }
         }
-        const errorId = route.errorIds?.at(-1)
+        const errorId = boundaryFor(route, err)
         if (errorId === undefined) throw err
-        return renderError(route, errorId, err)
+        return renderError(route, errorId, withDuplicateInstanceHint(err))
       }
     })
 
     // POST runs the route's `action` (mutation). A `Response` 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.
+    // 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)
@@ -1344,18 +2161,23 @@ export function createWebApp<Env = unknown>(
           headers: { allow: "GET", "content-type": "text/plain; charset=utf-8" },
         })
       }
-      const result = await mod.action({
+      const actionContext = {
         params: c.params,
         request: c.req,
         req: c.req,
         api,
         env: c.env,
         draft,
-      })
+        search: loaderSearch(mod.searchSchema, c.req),
+      }
+      // 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.
+      const layoutModules = await runLayoutGates(route, actionContext)
+      const result = await mod.action(actionContext)
       const isDataRequest = c.req.headers.get(DATA_HEADER) !== null
       // 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).
+      // 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
@@ -1374,7 +2196,7 @@ export function createWebApp<Env = unknown>(
       // 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
+        // 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)
@@ -1383,16 +2205,28 @@ export function createWebApp<Env = unknown>(
           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 })
+        ? await mod.loader({
+            params: c.params,
+            request: c.req,
+            req: c.req,
+            api,
+            env: c.env,
+            draft,
+            search,
+          })
         : null
-      const { chain, head } = resolveChainAndHead(await loadLayoutModules(route), mod, {
+      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 —
+      // 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,
@@ -1404,6 +2238,7 @@ export function createWebApp<Env = unknown>(
         routeId: route.id,
         params: c.params,
         path: pathOf(c.req),
+        search,
         hydrate: hydrateRoute,
         ...preloadOf(route.id),
         ...stylesOf(route.id),
@@ -1435,8 +2270,16 @@ export function createWebApp<Env = unknown>(
 }
 
 export interface GenerateClientEntryOptions {
-  /** Module specifier for the adapter's client runtime (exports `mountRouter`), e.g.
-   * `"@nifrajs/web-solid/client"`. */
+  /**
+   * 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
@@ -1460,7 +2303,8 @@ export function generateClientEntry(
 
   const loaderRows: string[] = []
   const patternRows: string[] = []
-  // Routes whose loader appends a nearest `_error` module (LAST) — the client wraps the page in the
+  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).
@@ -1489,15 +2333,31 @@ export function generateClientEntry(
   }
   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 `${[
     'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web"',
     '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.
+    // 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 `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",
     `const errorRouteIds = new Set(${JSON.stringify(errorRouteIds)})`,
     // Each route is a lazy loader: dynamic imports → Bun.build (splitting) emits one chunk per
@@ -1508,6 +2368,12 @@ export function generateClientEntry(
     "}",
     "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 = {}",
     "const loadModule = async (id) => {",
     "  if (chains[id]) return",
     "  const mods = await loaders[id]()",
@@ -1516,7 +2382,7 @@ export function generateClientEntry(
     // 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
+    // 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)) {",
@@ -1525,9 +2391,16 @@ export function generateClientEntry(
     "    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 patterns = [",
@@ -1547,29 +2420,45 @@ export function generateClientEntry(
     // 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),`,
     // 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 router = createClientRouter({ patterns, initial, loadModule })",
+    `const statusRoutes = ${JSON.stringify(statusRoutes)}`,
+    "const router = createClientRouter({ patterns, initial, loadModule, statusRoutes, searchClientKeys })",
     "installHistory(router)",
     "installForms(router)",
-    'const root = document.getElementById("root")',
+    // 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.
-    "if (root) loadModule(initial.routeId).then(() => {",
-    "  mountRouter({ router, routes: chains, container: root })",
+    "loadModule(initial.routeId).then(() => {",
+    "  mountRouter({ router, routes: chains, searchSchemas, container: root })",
     // 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.
+    // 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.
+    // 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))))",
     "    }",
@@ -1578,22 +2467,69 @@ export function generateClientEntry(
   ].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 —
+  /** 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. */
+   * 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
+  /** 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
+  /** 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
+   * 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
@@ -1601,10 +2537,10 @@ export interface GenerateServerManifestOptions {
 
 /**
  * Codegen: emit a **server manifest** module (as source) for disk-less edge runtimes (Cloudflare
- * Workers, …) — and, with a `target`, any portable server bundle. `discoverRoutes` scans `node:fs`
- * and dynamic-imports each route by a *runtime* path — neither exists on workerd. This instead emits
- * **statically-analyzable** imports of every route/layout/`_error`/`_404` (so the bundler includes them) and
- * rebuilds the manifest with `buildManifest` — the SAME pure logic `discoverRoutes` feeds, so patterns
+ * 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
@@ -1615,17 +2551,18 @@ export function generateServerManifest(
   options: GenerateServerManifestOptions,
 ): string {
   const { resolve, clientEntry, styles, routeStyles, lazy = false } = options
-  // Every unique source file in the manifest (routes + layouts + `_error` + `_404`), sorted for stable output.
+  // 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",
+    "// 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 } from "@nifrajs/web"',
@@ -1669,3 +2606,15 @@ export function generateServerManifest(
     "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"