@nifrajs/web 2.2.0 → 2.4.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,32 +11,40 @@ 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 { createMatcher, DATA_HEADER, NAV_FROM_HEADER, PRERENDERED_GLOBAL, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, STATUS_HEADER, } from "./router.js";
-// Draft / preview mode — a signed cookie that flips `ctx.draft` for loaders + bypasses ISR for editors.
+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.
+// 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";
-// public/ — user-authored static files, served identically in dev and production by one handler.
+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)
+// 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, 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>`.
+// 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
@@ -48,12 +56,24 @@ export const ROUTE_GLOBAL = "__NIFRA_ROUTE__";
  * 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
@@ -69,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
@@ -91,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).
@@ -102,16 +122,20 @@ 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 = [], headers: extraHeaders, } = 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);
     // Each layout's data is split in turn, each continuing the id space, so a `defer()` in a layout
@@ -130,7 +154,7 @@ export function renderPageResult(options) {
         ? 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.
+    // 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))};`;
@@ -138,9 +162,9 @@ export function renderPageResult(options) {
     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) {
@@ -149,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.
@@ -158,43 +182,50 @@ 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 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
+    // 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)}"`}`;
-    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}${adapter.hydrationHead()}</head><body><div id="${escapeAttr(rootId)}">`;
+    // 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}${layoutTail}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
@@ -215,10 +246,13 @@ 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) }
@@ -236,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.
@@ -248,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 {
@@ -289,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();
@@ -306,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);
@@ -340,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.
  *
@@ -355,12 +389,12 @@ 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 } });
 }
@@ -504,7 +538,7 @@ export function statusPage(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>`).
  */
@@ -526,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.
  */
@@ -546,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)}"`;
@@ -580,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) {
@@ -595,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;
 }
@@ -644,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;
 }
@@ -662,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}.
  *
@@ -669,20 +738,20 @@ 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];
@@ -692,6 +761,7 @@ export function mergeHeads(heads) {
     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
@@ -705,8 +775,10 @@ export function mergeHeads(heads) {
             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`).
@@ -719,6 +791,8 @@ 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)
@@ -760,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) {
@@ -785,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];
@@ -799,7 +873,7 @@ 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
@@ -822,7 +896,7 @@ export function createWebApp(options) {
                     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
+            // Exactly the prefix (`/api`) or a sub-path (`/api/…`) - NOT a sibling like `/apixyz` that merely
             // shares the prefix as a string head. Dispatch the original `req` (body intact) to the backend.
             if (mountedApi !== undefined && apiPrefix !== "" && underPrefix(pathname, apiPrefix)) {
                 return mountedApi(apiStrip ? stripMountPrefix(req, apiPrefix) : req, platform);
@@ -838,7 +912,7 @@ export function createWebApp(options) {
     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.
+    // 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).
@@ -849,7 +923,7 @@ export function createWebApp(options) {
             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.`);
+            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;
     };
@@ -937,6 +1011,13 @@ export function createWebApp(options) {
         }
         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)) {
@@ -1042,11 +1123,11 @@ export function createWebApp(options) {
         }
         return undefined;
     };
-    // The request's origin (scheme + host + port, NO trailing slash) — the one server fact `meta()` needs
+    // 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 {
@@ -1056,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.
@@ -1071,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");
@@ -1097,7 +1178,7 @@ 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 = (path) => renderTerminalStatus(404, path);
@@ -1121,13 +1202,22 @@ export function createWebApp(options) {
         // 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 { default: component } = await page.load();
+        const loaded = (await page.load());
+        const component = loaded.default;
         return renderPageResult({
             adapter,
             chain: [component],
             data: null,
             clientEntry,
             routeId,
+            // The page hydrates, so besides `path` its SSR `search` must equal the client mount's derivation for
+            // this routeId (`searchOf(searchSchema, url.search)`), or a status page reading `useSearch` drifts.
+            // Only when `path` is present (a real URL); a schema-less status page then gets the raw parsed query.
+            ...(path !== undefined
+                ? {
+                    search: searchOf(loaded.searchSchema, path.includes("?") ? path.slice(path.indexOf("?")) : ""),
+                }
+                : {}),
             // The page hydrates, so its SSR `path` must equal the client's initial
             // `location.pathname+search` (an unmatched path yields no params → `{}`), or a `useLocation`
             // on it would drift.
@@ -1160,7 +1250,7 @@ export function createWebApp(options) {
         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) => {
@@ -1184,6 +1274,7 @@ export function createWebApp(options) {
                     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
@@ -1195,8 +1286,12 @@ export function createWebApp(options) {
                 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) : null,
+                    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;
@@ -1209,7 +1304,7 @@ export function createWebApp(options) {
                 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;
@@ -1225,7 +1320,7 @@ export function createWebApp(options) {
                 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", {
@@ -1235,10 +1330,10 @@ export function createWebApp(options) {
                 }
                 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 pageSplit = prepareDeferred(data);
                 const layoutSplits = [];
@@ -1257,7 +1352,7 @@ export function createWebApp(options) {
                         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
+                // 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);
@@ -1274,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,
@@ -1285,6 +1380,10 @@ 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),
@@ -1296,7 +1395,7 @@ export function createWebApp(options) {
                 });
             }
             catch (err) {
-                // Same precedence as the loader catch above — a `meta()` may signal too.
+                // Same precedence as the loader catch above - a `meta()` may signal too.
                 if (isStatusSignal(err))
                     return renderStatusSignal(c.req, err);
                 if (err instanceof Response)
@@ -1318,7 +1417,7 @@ export function createWebApp(options) {
         });
         // 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);
@@ -1335,6 +1434,7 @@ export function createWebApp(options) {
                 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.
@@ -1343,7 +1443,7 @@ export function createWebApp(options) {
             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
@@ -1361,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)
@@ -1370,8 +1470,20 @@ 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(layoutModules, mod, {
                 data,
@@ -1379,7 +1491,7 @@ export function createWebApp(options) {
                 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,
@@ -1391,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),
@@ -1431,7 +1544,7 @@ export function generateClientEntry(manifest, options) {
     const loaderRows = [];
     const patternRows = [];
     const statusRoutes = {};
-    // Routes whose loader appends a nearest `_error` module (LAST) — the client wraps the page in the
+    // 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).
@@ -1468,7 +1581,7 @@ export function generateClientEntry(manifest, options) {
         '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
@@ -1476,7 +1589,7 @@ export function generateClientEntry(manifest, options) {
         // "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 " +
+            "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",
@@ -1489,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]()",
@@ -1497,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)) {",
@@ -1506,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 = [",
@@ -1537,23 +1663,34 @@ export function generateClientEntry(manifest, options) {
         "  pending: false,",
         "}",
         `const statusRoutes = ${JSON.stringify(statusRoutes)}`,
-        "const router = createClientRouter({ patterns, initial, loadModule, 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))))",
         "    }",
@@ -1561,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
+ * 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
+ * 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
@@ -1585,7 +1752,7 @@ export function generateServerManifest(manifest, options) {
         ]),
     ].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"',
@@ -1627,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