@nifrajs/web 2.1.0 → 2.3.0

package/dist/index.js

@@ -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.
  */
@@ -11,44 +11,69 @@ import { NIFRA_BACKEND_MOUNT, } from "@nifrajs/core/mount";
 import { server } from "@nifrajs/core/server";
 import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, defer, MAP_DEFERRED_SOURCE, ndjsonStream, prepareDeferred, } from "./deferred.js";
 import { isDraftEnabled } from "./draft.js";
+import { trustedHeadAttributes } from "./internal/head-attributes.js";
+import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.js";
 import { ISR_REVALIDATE_HEADER } from "./isr.js";
 import { generateLlmsTxt } from "./llms-txt.js";
-import { DATA_HEADER, PRERENDERED_GLOBAL, REDIRECT_HEADER, REVALIDATE_HEADER, } from "./router.js";
-// Draft / preview mode — a signed cookie that flips `ctx.draft` for loaders + bypasses ISR for editors.
-export { DRAFT_COOKIE, disableDraft, enableDraft, isDraftEnabled, } from "./draft.js";
-// Font optimization — a CLS-safe `@font-face` generator + a preload `<link>` for self-hosted fonts.
+import { createMatcher, DATA_HEADER, NAV_FROM_HEADER, PRERENDERED_GLOBAL, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, STATUS_HEADER, } from "./router.js";
+import { searchOf, searchOfChain } from "./search.js";
+// Draft / preview mode - a signed cookie that flips `ctx.draft` for loaders + bypasses ISR for editors.
+export { DRAFT_COOKIE, disableDraft, enableDraft, isDraftEnabled, previewEndpoint, } from "./draft.js";
+// Font optimization - a CLS-safe `@font-face` generator + a preload `<link>` for self-hosted fonts.
 export { fontFace, fontPreload, } from "./fonts.js";
 // ISR (incremental static regeneration): a pluggable cache store + the `withISR` stale-while-revalidate
 // wrapper for rendered SSR responses.
 export { ISR_REVALIDATE_HEADER, ISR_STATUS_HEADER, KVCacheStore, MemoryCacheStore, revalidateEndpoint, withISR, } from "./isr.js";
-// 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 { buildManifest, enumerateStaticRoutes, filePathToPattern, filePathToPatterns, } from "./manifest.js";
-// 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 { getBrowserNavigate, setBrowserNavigate, } from "./navigation.js";
-// Keyed query-cache (agnostic) — a `query(key, fn)` primitive (dedup + staleness + invalidation + GC)
+export { getBrowserNavigate, IDLE_BLOCKER, registerBlocker, resolveNavigate, setBlockerController, setBrowserNavigate, } from "./navigation.js";
+// public/ - user-authored static files, served identically in dev and production by one handler.
+export { resolvePublicPath, servePublicDir, } from "./public-dir.js";
+// Keyed query-cache (agnostic) - a `query(key, fn)` primitive (dedup + staleness + invalidation + GC)
 // consumed by the per-adapter `useQuery`/`createQuery` bindings.
 export { createMutation, createQueryClient, hashQueryKey, } from "./query.js";
-// 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 { createClientRouter, createMatcher, DATA_HEADER, REDIRECT_HEADER, REVALIDATE_HEADER, } from "./router.js";
-// Deferred loader data (`defer()` + the `Deferred<T>` type) — consumed by the adapter's `<Await>`.
+export { createClientRouter, createMatcher, DATA_HEADER, NAV_FROM_HEADER, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, STATUS_HEADER, } from "./router.js";
+// Deferred loader data (`defer()` + the `Deferred<T>` type) - consumed by the adapter's `<Await>`.
 export { defer };
 export { assertRenderAdapterConformance, RenderAdapterConformanceError, } from "./conformance.js";
+// 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 { searchOf, searchOfChain, serializeSearch } from "./search.js";
 /** 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__";
 /** Global the server serializes an action's data return into (absent on GETs); the client
  * reads it so hydration after a native form POST matches the server-rendered markup. */
 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
@@ -64,11 +89,11 @@ export const PRE_HYDRATION_GUARD = "(function(){addEventListener('submit',functi
 /**
  * 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();
 // XSS-safe `<script>` JSON escaping in a SINGLE pass: `<`/`>` would break out of the
 // script element; U+2028/U+2029 are valid JSON but historically break JS string literals. Built via
@@ -86,8 +111,8 @@ const SCRIPT_ESCAPE_MAP = {
 const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body");
 const RESPONSE_RESULT = Symbol.for("nifra.response.result");
 /**
- * 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`.
+ * 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).
@@ -97,27 +122,49 @@ export function renderPage(options) {
     return page instanceof Promise ? page.then((p) => p.toResponse()) : page.toResponse();
 }
 export function renderPageResult(options) {
-    const { adapter, chain, data, actionData, clientEntry, preload = [], styles = [], prerenderedPaths = [], revalidate, routeId, status = 200, title = "nifra", head, rootId = "root", hydrate = true, islandScripts = [], } = options;
+    const { adapter, chain, data, actionData, clientEntry, preload = [], styles = [], prerenderedPaths = [], revalidate, routeId, status = 200, title = "nifra", head, 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
         ? ""
         : `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);
-    const actionSplit = actionData === undefined ? undefined : prepareDeferred(actionData, deferred.length);
-    const allDeferred = actionSplit ? [...deferred, ...actionSplit.deferred] : deferred;
+    // 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 = [];
+    if (options.layoutData !== undefined) {
+        let offset = deferred.length;
+        for (const entry of options.layoutData) {
+            const split = prepareDeferred(entry, offset);
+            offset += split.deferred.length;
+            layoutSplits.push(split);
+        }
+    }
+    const layoutDeferred = layoutSplits.flatMap((split) => split.deferred);
+    const actionSplit = actionData === undefined
+        ? undefined
+        : prepareDeferred(actionData, deferred.length + layoutDeferred.length);
+    const 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) {
@@ -126,7 +173,7 @@ export function renderPageResult(options) {
                 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.
@@ -135,39 +182,61 @@ export function renderPageResult(options) {
         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 = { "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.
@@ -177,10 +246,17 @@ export function renderPageResult(options) {
         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
     // whole document in one pass. Progressive streaming only benefits pages with deferred boundaries
@@ -194,10 +270,10 @@ export function renderPageResult(options) {
             ? new BufferedRenderedPage(shellHtml + out + closeRootHtml + tailHtml, status, headers)
             : out.then((bodyHtml) => new BufferedRenderedPage(shellHtml + bodyHtml + closeRootHtml + tailHtml, status, headers));
     }
-    return renderStreamedPage(adapter, chain, renderProps, shellHtml, closeRootHtml, allDeferred, tailHtml, status, headers).then((response) => new ResponseRenderedPage(response));
+    return renderStreamedPage(adapter, chain, renderProps, shellHtml, closeRootHtml, allDeferred, tailHtml, status, headers, nonceAttr).then((response) => new ResponseRenderedPage(response));
 }
-async function renderStreamedPage(adapter, chain, renderProps, shellHtml, closeRootHtml, allDeferred, tailHtml, status, headers) {
-    // Streaming path — required for `defer()` (progressive `<Await>` resolution) and used by any adapter
+async function renderStreamedPage(adapter, chain, renderProps, shellHtml, closeRootHtml, allDeferred, tailHtml, status, headers, nonceAttr) {
+    // 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.
@@ -206,7 +282,7 @@ async function renderStreamedPage(adapter, chain, renderProps, shellHtml, closeR
     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 });
 }
 class BufferedRenderedPage {
@@ -247,11 +323,11 @@ function htmlResponse(body, init) {
 /**
  * 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(shell, stream, closeRoot, deferred, tail, enc) {
+function streamDocument(shell, stream, closeRoot, deferred, tail, enc, nonceAttr) {
     return new ReadableStream({
         async start(controller) {
             const reader = stream.getReader();
@@ -264,19 +340,19 @@ function streamDocument(shell, stream, closeRoot, deferred, tail, enc) {
                     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>`));
+                        controller.enqueue(enc.encode(`<script${nonceAttr}>window.__nifraResolve(${d.id},${value})</script>`));
                     }
                     catch (err) {
-                        // A rejected deferred streams __nifraReject (the client `<Await>` surfaces it) — it must
+                        // 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>`));
+                        controller.enqueue(enc.encode(`<script${nonceAttr}>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`));
                     }
                 }));
                 controller.enqueue(tail);
@@ -298,12 +374,12 @@ function isSameOriginPath(location) {
     return location.startsWith("/") && !location.startsWith("//");
 }
 /**
- * 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.
  *
@@ -313,19 +389,156 @@ export function redirect(location, options = {}) {
     if (options.external !== true && !isSameOriginPath(location)) {
         throw new Error(`[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//"), 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.`);
+        throw new Error(`[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 } });
 }
+/**
+ * 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 = [
+    /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) {
+    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;
+}
+/**
+ * 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, owned) {
+    if (owned === undefined)
+        return params; // hand-built manifest with no scope info: unchanged behaviour
+    if (owned.length === 0)
+        return EMPTY_LAYOUT_PARAMS;
+    const scoped = {};
+    for (const name of owned) {
+        const value = params[name];
+        if (value !== undefined)
+            scoped[name] = value;
+    }
+    return scoped;
+}
+const EMPTY_LAYOUT_PARAMS = Object.freeze({});
+const EMPTY_RETAIN = new Set();
+/**
+ * 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, layoutId) => {
+    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) => typeof err === "object" && err !== null
+    ? err[LAYOUT_ERROR_ID]
+    : 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 = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    410: "Gone",
+    451: "Unavailable For Legal Reasons",
+    500: "Internal Server Error",
+};
+function isStatusSignal(value) {
+    return value instanceof Response && STATUS_SIGNAL in value;
+}
+function statusSignal(status, options) {
+    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;
+}
+/**
+ * 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 = {}) {
+    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 = {}) {
+    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, options = {}) {
+    return statusSignal(status, options);
+}
 /**
  * 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>`).
  */
@@ -347,10 +560,10 @@ function escapeHtml(value) {
 /**
  * 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.
  */
@@ -367,28 +580,13 @@ function escapeAttr(value) {
         .replaceAll("<", "&lt;")
         .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) {
+/** Serialize attributes that passed the shared SSR/client head trust policy. */
+function tagAttrs(tag, attrs) {
+    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)}"`;
@@ -401,11 +599,16 @@ function tagAttrs(attrs) {
 // builds a fresh object each request (new identity) → miss → recompute, exactly as needed (its
 // content can vary). WeakMap so a route module that's GC'd takes its entry with it.
 const headTagsCache = new WeakMap();
+function assertExecutableScriptType(type) {
+    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) {
@@ -416,17 +619,42 @@ function headTags(head) {
         return cached;
     let out = "";
     if (head.meta !== undefined)
-        for (const m of head.meta)
-            out += `<meta ${tagAttrs(m)} data-nifra>`;
+        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)
-            out += `<link ${tagAttrs(l)} data-nifra>`;
-    // `<script>` slot — JSON-LD + other inert head scripts. `type` is attribute-escaped; `content` is
+        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;
 }
@@ -465,7 +693,7 @@ export function openGraph(input) {
     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;
 }
@@ -483,6 +711,26 @@ export function openGraph(input) {
 export function jsonLd(data) {
     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, options) {
+    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}.
  *
@@ -490,38 +738,47 @@ export function jsonLd(data) {
  * `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) {
-    // 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];
     let title;
+    let lang;
+    let dir;
     const meta = [];
     const link = [];
     const script = [];
+    const unsafeScript = [];
     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`).
@@ -534,8 +791,34 @@ export function mergeHeads(heads) {
         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;
 }
+/**
+ * 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, prefix) {
+    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.
@@ -551,15 +834,15 @@ function backendMountOf(api) {
 /**
  * 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(options) {
@@ -576,7 +859,7 @@ export function createWebApp(options) {
         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) => {
         const perRoute = options.routeStyles?.[id];
@@ -590,21 +873,33 @@ export function createWebApp(options) {
     const app = server();
     // 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, prefix) => 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
         });
@@ -613,12 +908,186 @@ export function createWebApp(options) {
     // 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) => Promise.all(
-    // layoutIds only reference layouts present in the manifest (buildManifest invariant).
-    route.layoutIds.map((id) => manifest.layouts[id].load()));
+    // contributes). Loaded lazily - the data-only and 405 branches return before any layout is needed.
+    const loadLayoutModules = async (route) => {
+        const modules = await Promise.all(
+        // layoutIds only reference layouts present in the manifest (buildManifest invariant).
+        route.layoutIds.map((id) => manifest.layouts[id].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].action === undefined)
+                continue;
+            const id = route.layoutIds[i];
+            throw new Error(`[nifra/web] "${manifest.layouts[id].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) => {
+        if (header === null || header === "")
+            return EMPTY_RETAIN;
+        const out = new Set();
+        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, route, params) => {
+        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;
+        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();
+        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, 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, mod, request) => searchOfChain([...layoutMods.map((m) => m.searchSchema), mod.searchSchema], new URL(request.url).search);
+    const runLayoutChain = async (route, ctx, retain = new Set()) => {
+        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 = new Array(modules.length).fill(null);
+        const retained = [];
+        const pending = [];
+        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 = {
+                ...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]);
+                }
+                continue;
+            }
+            const layoutId = route.layoutIds[i];
+            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, ctx) => {
+        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]);
+            }
+        }
+        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`
@@ -633,11 +1102,32 @@ export function createWebApp(options) {
     };
     // Dir a special-file id lives in: `_error`→"" , `a/b/_error`→"a/b" (and likewise for `_layout`).
     const dirOfId = (id, suffix) => 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, err) => {
+        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], "_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) => {
         try {
@@ -647,7 +1137,7 @@ export function createWebApp(options) {
             return "";
         }
     };
-    // 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.
@@ -662,11 +1152,11 @@ export function createWebApp(options) {
     };
     /**
      * 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, errorId, err) => {
         const errDir = dirOfId(errorId, "_error");
@@ -688,35 +1178,79 @@ export function createWebApp(options) {
             ...titleOption,
         });
     };
-    // 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) => {
-        if (manifest.notFound === undefined) {
-            return new Response("Not Found", {
-                status: 404,
-                headers: { "content-type": "text/plain; charset=utf-8" },
-            });
+    const renderNotFound = (path) => 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, path, extraHeaders) => {
+        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());
+        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, signal) => {
+        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) => {
@@ -729,21 +1263,48 @@ export function createWebApp(options) {
             const mod = await route.load();
             const draft = await draftFlag(c.req);
             let data;
+            let layoutData;
+            let layoutModules;
+            let layoutRetained = [];
             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;
@@ -756,10 +1317,10 @@ export function createWebApp(options) {
                         // 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", {
@@ -767,21 +1328,40 @@ export function createWebApp(options) {
                         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 = [];
+                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,
+                        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, {
+            const { chain, head } = resolveChainAndHead(layoutModules ?? (await loadLayoutModules(route)), mod, {
                 data,
                 params: c.params,
                 origin: originOf(c.req),
@@ -789,7 +1369,7 @@ export function createWebApp(options) {
             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,
@@ -800,7 +1380,12 @@ export function createWebApp(options) {
                     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 ?? [],
@@ -810,6 +1395,9 @@ export function createWebApp(options) {
                 });
             }
             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.
@@ -821,15 +1409,15 @@ export function createWebApp(options) {
                         // 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) => {
             const mod = await route.load();
             const draft = await draftFlag(c.req);
@@ -839,18 +1427,23 @@ export function createWebApp(options) {
                     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.data : result;
             const revalidateHeader = isRevalidate
@@ -868,7 +1461,7 @@ export function createWebApp(options) {
             // 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)
@@ -877,16 +1470,28 @@ export function createWebApp(options) {
                     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,
@@ -898,6 +1503,7 @@ export function createWebApp(options) {
                 routeId: route.id,
                 params: c.params,
                 path: pathOf(c.req),
+                search,
                 hydrate: hydrateRoute,
                 ...preloadOf(route.id),
                 ...stylesOf(route.id),
@@ -937,7 +1543,8 @@ export function generateClientEntry(manifest, options) {
     const { clientModule, resolve } = options;
     const loaderRows = [];
     const patternRows = [];
-    // Routes whose loader appends a nearest `_error` module (LAST) — the client wraps the page in the
+    const statusRoutes = {};
+    // 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 = [];
     // Lazy loader returns the raw modules (for both the component chain + the page's `meta` export).
@@ -963,14 +1570,28 @@ export function generateClientEntry(manifest, options) {
     }
     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
@@ -981,6 +1602,12 @@ export function generateClientEntry(manifest, options) {
         "}",
         "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]()",
@@ -989,7 +1616,7 @@ export function generateClientEntry(manifest, options) {
         // 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)) {",
@@ -998,9 +1625,16 @@ export function generateClientEntry(manifest, options) {
         "    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 = [",
@@ -1020,29 +1654,43 @@ export function generateClientEntry(manifest, options) {
         // 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))))",
         "    }",
@@ -1050,12 +1698,42 @@ export function generateClientEntry(manifest, options) {
         "})",
     ].join("\n")}\n`;
 }
+/**
+ * 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, options) {
+    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)])
+        .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`;
+}
 /**
  * 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
@@ -1063,17 +1741,18 @@ export function generateClientEntry(manifest, options) {
  */
 export function generateServerManifest(manifest, options) {
     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"',
@@ -1115,4 +1794,15 @@ export function generateServerManifest(manifest, options) {
         "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.js";
 //# sourceMappingURL=index.js.map