@nifrajs/web 2.1.0 → 2.3.0

package/dist/index.d.ts

@@ -1,41 +1,42 @@
 /**
- * @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.
  */
 import { server } from "@nifrajs/core/server";
 import { type Deferred, defer } from "./deferred.js";
-import type { LinkDescriptor, Manifest, Meta, MetaArgs, MetaInput, ScriptDescriptor } from "./manifest.js";
+import type { LinkDescriptor, Manifest, Meta, MetaArgs, MetaDescriptor, MetaInput, ScriptDescriptor, UnsafeScriptDescriptor } from "./manifest.js";
 import { type Submission } from "./router.js";
-export { DRAFT_COOKIE, type DraftCookieControls, disableDraft, type EnableDraftOptions, enableDraft, isDraftEnabled, } from "./draft.js";
+export { DRAFT_COOKIE, type DraftCookieControls, disableDraft, type EnableDraftOptions, enableDraft, isDraftEnabled, type PreviewEndpointOptions, previewEndpoint, } from "./draft.js";
 export { type FontDisplay, type FontFace, type FontPreloadInput, type FontSource, fontFace, fontPreload, } from "./fonts.js";
 export { type CachedResponse, type CacheStore, ISR_REVALIDATE_HEADER, ISR_STATUS_HEADER, type ISRApp, type ISROptions, type ISRPlatform, KVCacheStore, type KVCacheStoreOptions, type KVNamespaceLike, MemoryCacheStore, type MemoryCacheStoreOptions, type RevalidateEndpointOptions, revalidateEndpoint, withISR, } from "./isr.js";
-export { type Action, buildManifest, enumerateStaticRoutes, filePathToPattern, filePathToPatterns, type GetStaticPaths, type LayoutEntry, type LinkDescriptor, type Loader, type LoaderContext, type Manifest, type Meta, type MetaArgs, type MetaInput, type RouteEntry, type RouteModule, type ScriptDescriptor, type StaticPath, type StaticPaths, type StaticRoutes, } from "./manifest.js";
-export { type BrowserNavigate, getBrowserNavigate, type NavigateOptions, setBrowserNavigate, } from "./navigation.js";
+export { type Action, buildManifest, enumerateStaticRoutes, filePathToPattern, filePathToPatterns, type GetStaticPaths, type InertScriptType, type LayoutEntry, type LinkDescriptor, type Loader, type LoaderContext, type Manifest, type Meta, type MetaArgs, type MetaInput, type RouteEntry, type RouteModule, type ScriptDescriptor, type StaticPath, type StaticPaths, type StaticRoutes, type UnsafeScriptDescriptor, } from "./manifest.js";
+export { type Blocker, type BlockerController, type BlockerFunction, type BlockerLocation, type BlockerState, type BrowserNavigate, getBrowserNavigate, IDLE_BLOCKER, type NavigateFunction, type NavigateOptions, type NavigateSearchOf, type NavigateTargetInput, type RouteSearch, registerBlocker, resolveNavigate, setBlockerController, setBrowserNavigate, } from "./navigation.js";
+export { type PublicDirCache, resolvePublicPath, type ServePublicDirOptions, servePublicDir, } from "./public-dir.js";
 export { createMutation, createQueryClient, type DehydratedState, hashQueryKey, type InfiniteData, type InfiniteQueryHandle, type InfiniteQueryOptions, type MutationCallbacks, type MutationHandle, type MutationState, type MutationStatus, type QueryClient, type QueryClientOptions, type QueryHandle, type QueryOptions, type QueryState, type QueryStatus, } from "./query.js";
-export { type ClientRouter, type ClientRouterOptions, createClientRouter, createMatcher, DATA_HEADER, type Fetcher, type FetcherState, type FetchRouteData, type MountRouterOptions, REDIRECT_HEADER, REVALIDATE_HEADER, type RouteMatch, type RoutePattern, type RouterState, type Submission, type SubmitOptions, } from "./router.js";
+export { type ClientRouter, type ClientRouterOptions, createClientRouter, createMatcher, DATA_HEADER, type Fetcher, type FetcherState, type FetchRouteData, type MountRouterOptions, NAV_FROM_HEADER, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, type RouteMatch, type RoutePattern, type RouterState, STATUS_HEADER, type Submission, type SubmitOptions, } from "./router.js";
 export { type Deferred, defer };
 /** Phantom brand key for {@link ServerOnly}. A unique symbol so the brand can't be forged by a plain
  * object literal; `unique symbol` keys never appear in the emitted JS, so the brand is purely
  * type-level (zero runtime cost). The property is optional + `never`-typed, so a `ServerOnly<T>`
- * stays assignment-compatible with `T` — it documents intent without obstructing real use. */
+ * stays assignment-compatible with `T` - it documents intent without obstructing real use. */
 declare const SERVER_ONLY_BRAND: unique symbol;
 /**
- * Type-level intent marker for a value that must only exist on the server — a secret, a DB handle, a
+ * Type-level intent marker for a value that must only exist on the server - a secret, a DB handle, a
  * server-only client. `ServerOnly<T>` is structurally `T` (the brand is an optional phantom field, so
  * existing code keeps type-checking), but it advertises to readers + the compiler that the value is
- * not meant to cross to the browser. It is **purely type-level** and erases at build — it does NOT,
+ * not meant to cross to the browser. It is **purely type-level** and erases at build - it does NOT,
  * by itself, keep the value out of the client bundle.
  *
  * The enforcement is two runtime conventions:
- *  - add the side-effect import `import "@nifrajs/web/server-only"` at the top of the module — the
+ *  - add the side-effect import `import "@nifrajs/web/server-only"` at the top of the module - the
  *    client build ({@link buildClient}) fails loud, with the import chain, if it reaches a browser
  *    chunk (the poison-import marker);
- *  - or name the file `*.server.ts` — the `.server` convention empties it in the client build.
+ *  - or name the file `*.server.ts` - the `.server` convention empties it in the client build.
  *
  * Use this brand to express the intent in the types; pair it with one of those runtime markers so a
  * leak is caught at build time rather than shipping a secret to the client.
@@ -49,11 +50,20 @@ export type ServerOnly<T> = T & {
     readonly [SERVER_ONLY_BRAND]?: never;
 };
 export { assertRenderAdapterConformance, RenderAdapterConformanceError, type RenderAdapterConformanceFixture, } from "./conformance.js";
+export { type SearchOf, searchOf, searchOfChain, serializeSearch } from "./search.js";
 /** The data handed to a route component. Opaque to the core. `actionData` is the return of a
  * route `action` after a POST (absent on plain GETs). `pending` + `submission` are client-only
- * (absent on SSR): they drive **optimistic UI** — render from `submission.formData` while `pending`. */
+ * (absent on SSR): they drive **optimistic UI** - render from `submission.formData` while `pending`. */
 export interface RenderProps {
     readonly data: unknown;
+    /**
+     * Per-layout loader data, aligned index-for-index with the layout prefix of `chain`.
+     *
+     * Absent when no layout in the chain exports a `loader`, so a page-only app is byte-identical to
+     * before. An adapter that does not read it renders exactly as it did; one that does passes
+     * `layoutData[i]` to `chain[i]`.
+     */
+    readonly layoutData?: readonly unknown[];
     readonly actionData?: unknown;
     /** True while a client navigation or submit is in flight (client-only; absent/false on SSR). */
     readonly pending?: boolean;
@@ -66,10 +76,15 @@ export interface RenderProps {
      * SSR (from the request match) and on client navigation (from router state) so an adapter's
      * `useParams` reads the same value on both, with no hydration mismatch. Absent ⇒ no params (`{}`). */
     readonly params?: Readonly<Record<string, string>>;
-    /** The current URL's `pathname + search` (no hash — the hash never reaches the server). Threaded on
+    /** The current URL's `pathname + search` (no hash - the hash never reaches the server). Threaded on
      * SSR and client alike so an adapter's `useLocation`/`useSearchParams` hydrate consistently. Absent
      * on adapters/callers that don't supply it (treated as `""`). */
     readonly path?: string;
+    /** The route's typed, validated search params (the value the loader also gets as `ctx.search`),
+     * threaded to the adapter's `useSearch`. Derived identically on SSR (from the request) and on client
+     * navigation (adapter mount) via the shared `searchOf`, so a component reading it hydrates with no
+     * drift. Absent ⇒ no search context (`{}`). */
+    readonly search?: Record<string, unknown>;
 }
 /**
  * The seam every render adapter implements. New adapters should prove these invariants with
@@ -82,17 +97,17 @@ export interface RenderAdapter {
      * (the loader data); each layout wraps the child via its `children`. Returns (or resolves to)
      * a Web `ReadableStream<Uint8Array>`: a streaming renderer flushes the shell first and streams
      * Suspense boundaries as they resolve; a non-streaming renderer may return a one-chunk stream.
-     * May be async — e.g. React resolves once the shell is renderable, so a shell-render throw can
+     * May be async - e.g. React resolves once the shell is renderable, so a shell-render throw can
      * still map to an error status before any byte is sent.
      */
     renderToStream(chain: readonly unknown[], props: RenderProps): ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>;
     /**
      * Server (optional): render the chain to a complete HTML **string** in one pass, with the same
      * hydration markers `renderToStream` produces. When provided, `renderPage` uses it for any page
-     * that does **not** `defer()` — buffering the document is faster than the streaming pipeline there,
+     * that does **not** `defer()` - buffering the document is faster than the streaming pipeline there,
      * because the framework's synchronous renderer (React `renderToString`, Solid `renderToString`,
      * Preact `render`, Vue `renderToString`, Svelte `render`) is markedly cheaper than its streaming
-     * renderer — most visibly on Bun, where React Fizz / Solid `renderToStream` are the heaviest. Pages
+     * renderer - most visibly on Bun, where React Fizz / Solid `renderToStream` are the heaviest. Pages
      * that `defer()` keep the streaming path (progressive `<Await>` needs it). Markup MUST be
      * hydration-equivalent to `renderToStream`; a throw surfaces like the streaming shell-readiness
      * await (the `_error` boundary maps it to a status). Omit it to always stream.
@@ -102,22 +117,37 @@ export interface RenderAdapter {
      * Server: per-document bootstrap markup injected into `<head>` that the client
      * `hydrate` requires (Solid: `generateHydrationScript()`). Empty string if none.
      */
-    hydrationHead(): string;
+    hydrationHead(nonce?: string): string;
 }
 /** Global the server serializes loader data into; the client reads it to hydrate. */
 export declare 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 declare 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 declare 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 declare 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 declare 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
@@ -127,7 +157,7 @@ export declare const PRE_HYDRATION_GUARD: string;
 /**
  * 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 declare const DEFAULT_DEV_PORT = 4321;
@@ -144,21 +174,27 @@ export interface RenderedPage {
 }
 export interface RenderPageOptions {
     readonly adapter: RenderAdapter;
-    /** The layout chain to render — outermost layout → page (opaque; the adapter renders it). */
+    /** The layout chain to render - outermost layout → page (opaque; the adapter renders it). */
     readonly chain: readonly unknown[];
     /** The loader output for this request. */
     readonly data: unknown;
-    /** An action's data return (POST only) — surfaced to the page as `actionData` + serialized
+    /** An action's data return (POST only) - surfaced to the page as `actionData` + serialized
      * for the client so post-POST hydration matches. Omit on GETs. */
     readonly actionData?: unknown;
-    /** URL of the built client entry (loaded as a module script). */
-    readonly clientEntry: string;
+    /**
+     * URL of the built client entry (loaded as a module script).
+     *
+     * Optional ONLY on a `hydrate: false` page, where there is no client takeover to feed and this value
+     * reaches no output at all. The union below is what enforces that: omitting it on a hydrating page
+     * stays a compile error rather than rendering `src=""`.
+     */
+    readonly clientEntry?: string;
     /** Chunk URLs for the **matched** route (its layout chain + own chunk) to `modulepreload` in the
-     * shell — so the route code downloads in parallel with the entry instead of after it
+     * shell - so the route code downloads in parallel with the entry instead of after it
      * (`buildClient`'s per-route map). Empty/omitted ⇒ only the entry is preloaded (unchanged). */
     readonly preload?: readonly string[];
     /** Stylesheet URLs for the **matched** route (its layout chain + own CSS, from `buildClient`'s
-     * `BuildManifest.css`) — injected as `<link rel="stylesheet">` in `<head>` so styles arrive with the
+     * `BuildManifest.css`) - injected as `<link rel="stylesheet">` in `<head>` so styles arrive with the
      * first paint (no FOUC). Rendered even on non-hydrated pages. Empty/omitted ⇒ none (unchanged). */
     readonly styles?: readonly string[];
     /** SSG: the prerendered-path set, serialized to `window.__NIFRA_PRERENDERED__` so the client fetches
@@ -169,52 +205,78 @@ export interface RenderPageOptions {
     readonly revalidate?: number;
     /** Matched route id; written to `window.__NIFRA_ROUTE__` so the client hydrates this chain. */
     readonly routeId?: string;
-    /** The matched route's decoded path params — surfaced to the page as `params` (via {@link RenderProps})
+    /** The matched route's decoded path params - surfaced to the page as `params` (via {@link RenderProps})
      * so an adapter's `useParams` is SSR-correct. Omit ⇒ `{}` (a route with no dynamic segments, or an
      * error/404 render). */
     readonly params?: Readonly<Record<string, string>>;
-    /** The request's `pathname + search` — surfaced as `path` (via {@link RenderProps}) so an adapter's
+    /** The request's `pathname + search` - surfaced as `path` (via {@link RenderProps}) so an adapter's
      * `useLocation`/`useSearchParams` render the right URL server-side and hydrate without drift. Omit ⇒
      * `""`. */
     readonly path?: string;
+    /** The route's validated search (`searchOf(mod.searchSchema, url.search)`, the same value handed to
+     * the loader as `ctx.search`), surfaced as `search` (via {@link RenderProps}) so an adapter's
+     * `useSearch` is SSR-correct. Omit ⇒ `{}` (a render with no search context). */
+    readonly search?: Record<string, unknown>;
+    /** Per-layout loader data, forwarded to the adapter as `RenderProps.layoutData`. Aligned with the
+     * chain's layout prefix; omitted when no layout in the chain has a loader. */
+    readonly layoutData?: readonly unknown[];
     /** HTTP status for the response (default 200; e.g. 404 for a not-found page). */
     readonly status?: number;
+    /** Extra response headers - e.g. the `cache-control` a terminal status page wants. `content-type`
+     * is ignored (the document is always HTML) and the ISR freshness header is applied after these,
+     * so neither can be overridden from here. */
+    readonly headers?: HeadersLike;
     /** Document title (fallback when `head.title` is unset). */
     readonly title?: string;
-    /** Resolved route head — `title` overrides `title` above; `meta`/`link` render as managed
+    /** Resolved route head - `title` overrides `title` above; `meta`/`link` render as managed
      * (`data-nifra`) tags the client updates on navigation.
      *
      * **Head contract (the layout chain contributes).** `createWebApp` resolves this via
      * {@link mergeHeads}: a route's head is its **layout chain's** `meta`/`head` exports merged with the
-     * page's. A `_layout.tsx` may `export const meta` (or `export function meta(args)`) — its tags land
+     * page's. A `_layout.tsx` may `export const meta` (or `export function meta(args)`) - its tags land
      * on every page below it (the home for `hreflang`, `preconnect`, a section-default `<title>`). The
      * merge is **nearest-wins for scalars** (the page's `title` overrides an inner layout's, which
      * overrides an outer one; an undefined page title keeps the layout's) and **concatenated for the
-     * `meta`/`link` arrays** (outermost layout first, page last). `<link>` attributes are name-validated
-     * (any letter/digit/hyphen name — covers `rel`/`href`/`hreflang`/`crossorigin`/`media`/`sizes`/`as`/
-     * `integrity`/`fetchpriority`/…) and value-escaped against XSS. */
+     * `meta`/`link` arrays** (outermost layout first, page last). `<meta>`/`<link>` attributes pass a
+     * shared tag-specific allowlist (including inert `data-*` metadata) and values are escaped. */
     readonly head?: Meta;
-    /** Id of the container wrapping the app markup (default `"root"`). */
+    /** Id of the container wrapping the app markup (default `"root"`). A non-default id also gets
+     * {@link ROOT_ATTRIBUTE}, which is how the generated client entry finds the container to hydrate -
+     * the entry is built once and cannot know what a given render chose. */
     readonly rootId?: string;
-    /** When `false`, emit a complete but **non-hydrated** document — no client entry script, data
+    /** When `false`, emit a complete but **non-hydrated** document - no client entry script, data
      * globals, or modulepreloads. Used for server-rendered `_error` pages: a terminal state that needs no
      * client takeover, and it sidesteps an SSR/hydrate mismatch (the server rendered the boundary, not
      * the page the client manifest maps this route id to). Default `true`. */
     readonly hydrate?: boolean;
     /** Island client bundles (`@nifrajs/web/islands`) to load as `<script type="module">` in the document
-     * tail — emitted **regardless of `hydrate`**, so a static (`hydrate: false`) page can still mount
+     * tail - emitted **regardless of `hydrate`**, so a static (`hydrate: false`) page can still mount
      * no-framework islands. URLs are attribute-escaped. Empty/omitted ⇒ none (unchanged output). */
     readonly islandScripts?: readonly string[];
+    /** CSP nonce applied to every framework-owned executable script in this document. */
+    readonly nonce?: string;
 }
 /**
- * Server: render a full HTML document for a page — the adapter's hydration head + the SSR
- * markup (**streamed**) + the serialized loader data + the client module — as a `Response`.
+ * `renderPage` input. A hydrating page (the default) must supply `clientEntry`, because the document
+ * loads it as a module script; a `hydrate: false` page may omit it, because nothing in the emitted
+ * document references it. Expressed as a union so the compiler enforces the pairing rather than the
+ * renderer discovering an empty `src` at runtime.
+ */
+export type RenderPageInput = RenderPageOptions & ({
+    readonly hydrate?: true;
+    readonly clientEntry: string;
+} | {
+    readonly hydrate: false;
+});
+/**
+ * Server: render a full HTML document for a page - the adapter's hydration head + the SSR
+ * markup (**streamed**) + the serialized loader data + the client module - as a `Response`.
  * The shell (`<head>` + the open container) flushes first, the adapter's app stream follows,
  * then the tail (data globals + client entry). Pure Web Standards, so it returns straight from
  * a nifra route handler and streams on any fetch runtime (Bun/Node/Deno/Workers).
  */
-export declare function renderPage(options: RenderPageOptions): MaybePromise<Response>;
-export declare function renderPageResult(options: RenderPageOptions): MaybePromise<RenderedPage>;
+export declare function renderPage(options: RenderPageInput): MaybePromise<Response>;
+export declare function renderPageResult(options: RenderPageInput): MaybePromise<RenderedPage>;
 /** Options for {@link redirect}. */
 export interface RedirectOptions {
     /** HTTP status (default 303 See Other; pass 307/308 to preserve the method). */
@@ -225,21 +287,76 @@ export interface RedirectOptions {
     readonly external?: boolean;
 }
 /**
- * Build a redirect `Response` — return it from a route `action` for the Post/Redirect/Get
+ * Build a redirect `Response` - return it from a route `action` for the Post/Redirect/Get
  * pattern (POST mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit).
  * Defaults to 303 (See Other); pass `{ status: 307 }` or `{ status: 308 }` to preserve the method.
  *
  * **Secure by default:** `location` must be a same-origin path (begins with `/`, not `//`). An
- * off-origin/absolute destination throws unless you pass `{ external: true }` — this closes the
+ * off-origin/absolute destination throws unless you pass `{ external: true }` - this closes the
  * open-redirect footgun of `return redirect(formData.get("next"))` on the no-JS (native-form) path,
  * which returns the action's `Response` verbatim.
  *
  * @param options redirect status and whether an off-origin destination is intentional.
  */
 export declare function redirect(location: string, options?: RedirectOptions): Response;
+/**
+ * Brand marking a `Response` as a **terminal-status signal** rather than a response to serve verbatim.
+ *
+ * A loader that throws a bare `Response` has always been passed straight through - that is how
+ * `throw redirect(...)` works, and apps rely on it. So "render the `_404` boundary at 404" cannot be
+ * expressed by throwing a plain `Response`: the framework would have no way to tell it apart from a
+ * hand-rolled body the app wants served exactly as written. The brand is that distinction, and
+ * checking it *before* the pass-through is what keeps every existing throw working unchanged.
+ *
+ * `Symbol.for` matches `RESPONSE_RESULT` above: a registry symbol survives two copies of this module,
+ * which a `unique symbol` would not - and a duplicate-install turning a 404 into a raw 404 body would
+ * be a maddening bug to trace.
+ */
+/** Derived from the `Headers` constructor rather than the DOM lib's `HeadersInit`: `@nifrajs/web`
+ * is consumed from DOM-free programs (the root tsconfig runs `types: ["bun"]`), and naming the DOM
+ * type here would break their build. Same workaround as `SSEInit.headers` in core. */
+type HeadersLike = ConstructorParameters<typeof Headers>[0];
+/** Options shared by {@link notFound}, {@link gone}, and {@link statusPage}. */
+export interface StatusPageOptions {
+    /**
+     * Extra headers for the rendered response - `cache-control` above all.
+     *
+     * The defaults differ by status for a reason: a 404 may be a race with publication, so it wants a
+     * short TTL, while a 410 is a promise that the URL is permanently gone and can be cached hard.
+     * Getting this wrong is the difference between a crawler dropping a dead URL and re-fetching it
+     * for weeks.
+     */
+    readonly headers?: HeadersLike;
+}
+/**
+ * Render the nearest `_404` page at status **404**. `throw` it from a loader when the record does not
+ * exist.
+ *
+ * This is the fix for the soft 404: a matched route whose loader finds nothing has otherwise no way to
+ * answer 404, so the path of least resistance is to return empty data and render "not found" inside a
+ * **200**. That looks correct in a browser and is invisible in review, which is why it ships and stays
+ * shipped - while search engines penalise it and keep the dead URL indexed.
+ *
+ * Returns `never`: these throw, so a loader narrows without a redundant `return`, and the type states
+ * the thing the "loaders `throw` redirect, actions `return` it" rule already trips people on.
+ */
+export declare function notFound(options?: StatusPageOptions): never;
+/**
+ * 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 declare function gone(options?: StatusPageOptions): never;
+/**
+ * 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 declare function statusPage(status: number, options?: StatusPageOptions): never;
 /** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
  * shape (not a class) so `@nifrajs/client`'s `ActionData` can unwrap it structurally without importing
- * from `@nifrajs/web`. `createWebApp` strips the wrapper — the client receives `data` as the body and
+ * from `@nifrajs/web`. `createWebApp` strips the wrapper - the client receives `data` as the body and
  * the paths via the `X-Nifra-Revalidate` header. */
 export interface RevalidateResult<T> {
     readonly __nifraRevalidate: readonly string[];
@@ -248,7 +365,7 @@ export interface RevalidateResult<T> {
 /**
  * Return this from an action to declare which routes the mutation changed (alongside the action's
  * `data`). `createWebApp` sets the `X-Nifra-Revalidate` response header; after the submit the client
- * marks those cached routes stale — refetching the active one and any mounted fetcher showing them —
+ * marks those cached routes stale - refetching the active one and any mounted fetcher showing them -
  * so a mutation can refresh views beyond the one that was submitted. `data` is still surfaced to the
  * component as `actionData` (the wrapper is transparent to `ActionData<typeof action>`).
  */
@@ -271,7 +388,7 @@ export declare function resolveMeta(meta: MetaInput | undefined, args: MetaArgs)
  * ```
  */
 export declare function canonical(href: string): LinkDescriptor;
-/** Inputs for {@link openGraph} — the common Open Graph properties. All optional; only the provided
+/** Inputs for {@link openGraph} - the common Open Graph properties. All optional; only the provided
  * ones become tags. `type` defaults to `"website"`. */
 export interface OpenGraphInput {
     readonly title?: string;
@@ -280,7 +397,7 @@ export interface OpenGraphInput {
     readonly image?: string;
     /** Canonical URL of the page (`og:url`). */
     readonly url?: string;
-    /** Object type (`og:type`) — `"website"`, `"article"`, … Default `"website"`. */
+    /** Object type (`og:type`) - `"website"`, `"article"`, … Default `"website"`. */
     readonly type?: string;
 }
 /**
@@ -291,7 +408,7 @@ export interface OpenGraphInput {
  * export const meta = { meta: [...openGraph({ title: "Nifra", image: "https://site.com/og.png" })] }
  * ```
  */
-export declare function openGraph(input: OpenGraphInput): Array<Record<string, string>>;
+export declare function openGraph(input: OpenGraphInput): MetaDescriptor[];
 /**
  * Build a JSON-LD `<script type="application/ld+json">` entry for a route's `meta.script` from a plain
  * object. `JSON.stringify` produces the body; the head renderer breakout-escapes it (see
@@ -304,6 +421,14 @@ export declare function openGraph(input: OpenGraphInput): Array<Record<string, s
  * ```
  */
 export declare function jsonLd(data: Record<string, unknown>): ScriptDescriptor;
+/**
+ * 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 declare function unsafeInlineScript(content: string, options: {
+    readonly nonce: string;
+    readonly type?: "module" | "text/javascript";
+}): UnsafeScriptDescriptor;
 /**
  * Merge a route's `<head>` contributions from its layout chain + the page into one {@link Meta}.
  *
@@ -311,15 +436,15 @@ export declare function jsonLd(data: Record<string, unknown>): ScriptDescriptor;
  * `meta` to put sitewide tags (`hreflang`, `preconnect`, a default `<title>`, …) on every page below
  * it. `heads` is passed **outermost layout → … → innermost layout → page** (the same order as the
  * render chain), and merges:
- *  - **`title`** — *nearest-wins*: the last defined value across the list, so the page overrides an
+ *  - **`title`** - *nearest-wins*: the last defined value across the list, so the page overrides an
  *    inner layout, which overrides an outer one. A layout `title` is the section default; an undefined
  *    page `title` keeps it.
- *  - **`meta` / `link`** — *concatenated* in list order (outermost first, page last). Duplicate-tag
+ *  - **`meta` / `link`** - *concatenated* in list order (outermost first, page last). Duplicate-tag
  *    de-duplication is the caller's concern; the framework emits exactly what's declared so a layout
  *    can ship N `<link rel="alternate" hreflang>` tags and a page can add its own canonical.
  *
  * Returns a fresh object whose identity is stable per `heads` *content* only when every entry is a
- * static (by-reference) `Meta` and there is exactly one — otherwise a new object each call. That is
+ * static (by-reference) `Meta` and there is exactly one - otherwise a new object each call. That is
  * fine: {@link headTags}'s memo is keyed on identity, so a per-request merge simply recomputes (its
  * content can vary with loader data anyway).
  */
@@ -331,7 +456,7 @@ export interface CreateWebAppOptions {
     readonly clientEntry: string;
     /** Default document title for all pages. */
     readonly title?: string;
-    /** Injected into each loader's `ctx.api` — typically an `inProcessClient(app)` (typed
+    /** Injected into each loader's `ctx.api` - typically an `inProcessClient(app)` (typed
      * per-route via `@nifrajs/client`'s `createRoutes`). Opaque to the core.
      *
      * **Auto-mount.** Every `inProcessClient(backend)` exposes the symbol-keyed platform-aware backend
@@ -347,19 +472,48 @@ export interface CreateWebAppOptions {
      * auto-mount entirely (the app serves pages only and `api` stays a loader-only `ctx.api`). Mounting
      * is also a no-op when `api` does not expose the symbol mount. */
     readonly apiPrefix?: string;
+    /**
+     * Strip {@link apiPrefix} from the pathname before dispatching to `api` (default `false`).
+     *
+     * The default suits a backend that declares FULL paths (`server().post("/api/sync", …)`), which is
+     * right when it is only ever mounted here. Set this when the backend declares its routes WITHOUT the
+     * prefix because it also runs standalone behind its own shell, so its paths cannot carry a prefix that
+     * only exists when it is mounted. Without it every request 404s inside the backend, and the workaround
+     * is a `Proxy` that rewrites each URL.
+     */
+    readonly apiStrip?: boolean;
+    /**
+     * Sub-apps mounted ahead of page routing - an auth handler, a webhook receiver, a stack's routes.
+     *
+     * Structural on purpose: anything with `{ path, app: { fetch } }` fits, so a library that exposes its
+     * routes as such a list mounts as `mounts: theirRoutes` without `@nifrajs/web` taking a dependency on
+     * it. `better-auth` is the motivating case - it is not a `backend` route, so `/api/auth/*` used to 404
+     * silently.
+     *
+     * Tried longest-path-first and BEFORE the `api` mount, so a mount at `/api/auth` wins over a backend
+     * at `/api` no matter which was declared first. `stripPrefix` is the per-mount form of {@link apiStrip}:
+     * leave it off to pass the full path through.
+     */
+    readonly mounts?: ReadonlyArray<{
+        readonly path: string;
+        readonly app: {
+            fetch(request: Request): Response | Promise<Response>;
+        };
+        readonly stripPrefix?: boolean;
+    }>;
     /** Secret for **draft / preview mode** (see `enableDraft`). When set, a request carrying a valid
      * signed `__nifra_draft` cookie gets `ctx.draft === true` in loaders/actions (else always `false`).
      * Pair with `withISR({ draftSecret })` so editors bypass the cache. Omit to disable draft mode. */
     readonly draftSecret?: string;
-    /** Per-route chunk URLs (`buildClient`'s `BuildManifest.routes`) — `routeId → [layout chunks…, own
+    /** Per-route chunk URLs (`buildClient`'s `BuildManifest.routes`) - `routeId → [layout chunks…, own
      * chunk]`. When present, each page `modulepreload`s its matched route's chunks alongside the entry,
      * so the route code downloads in parallel (no entry→route-chunk waterfall). Omit ⇒ entry-only. */
     readonly routePreload?: Readonly<Record<string, readonly string[]>>;
-    /** The app's bundled stylesheet URLs (`buildClient`'s `BuildManifest.css`) — the aggregate, injected
+    /** The app's bundled stylesheet URLs (`buildClient`'s `BuildManifest.css`) - the aggregate, injected
      * as `<link rel="stylesheet">` in a page's `<head>`. Used as the fallback for any route absent from
      * {@link routeStyles}. Omit ⇒ no links (dev, where Vite injects CSS, or a CSS-free app). */
     readonly styles?: readonly string[];
-    /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) — `routeId → [chain CSS]`.
+    /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) - `routeId → [chain CSS]`.
      * When a matched route has an entry here, only those (its layout chain + own CSS) are linked instead
      * of the aggregate `styles`, so a page ships only the CSS it uses. An empty array ⇒ no `<link>` (the
      * page imports no CSS). Routes absent here fall back to `styles`. Omit ⇒ always use `styles`. */
@@ -370,14 +524,14 @@ export interface CreateWebAppOptions {
     readonly prerenderedPaths?: readonly string[];
     /** SSG: per dynamic route pattern, its `getStaticPaths` `fallback` (from `enumerateStaticRoutes` or
      * the build's `prerendered.json`). A route mapped to `"404"` rejects any path NOT in
-     * `prerenderedPaths` with the 404 page — the unlisted path simply doesn't exist. `"ssr"` (the
+     * `prerenderedPaths` with the 404 page - the unlisted path simply doesn't exist. `"ssr"` (the
      * default for unmapped routes) renders unlisted paths on-demand. */
     readonly staticFallbacks?: Readonly<Record<string, "ssr" | "404">>;
-    /** Observe every loader/action failure — for error-reporting plugins (Sentry-style). Called for
+    /** Observe every loader/action failure - for error-reporting plugins (Sentry-style). Called for
      * real throws (not control-flow `Response`s like `redirect`), **before** the nearest `_error`
-     * boundary renders / a soft-nav 500 / a rethrow — so it sees errors that the boundary would
+     * boundary renders / a soft-nav 500 / a rethrow - so it sees errors that the boundary would
      * otherwise hide. Observation only; its own throws are swallowed so a faulty reporter can't break
-     * rendering. (`beforeLoader` is intentionally omitted — the core HTTP hooks already cover
+     * rendering. (`beforeLoader` is intentionally omitted - the core HTTP hooks already cover
      * pre-request work.) */
     readonly onLoaderError?: (error: unknown, ctx: {
         readonly request: Request;
@@ -388,21 +542,29 @@ export interface CreateWebAppOptions {
 /**
  * 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 declare function createWebApp<Env = unknown>(options: CreateWebAppOptions): ReturnType<typeof server<Env>>;
 export interface GenerateClientEntryOptions {
-    /** Module specifier for the adapter's client runtime (exports `mountRouter`), e.g.
-     * `"@nifrajs/web-solid/client"`. */
+    /**
+     * Module specifier for the adapter's client runtime, e.g. `"@nifrajs/web-solid/client"`.
+     *
+     * **Contract:** the module MUST export `mountRouter({ router, routes, container })`. The generated
+     * bootstrap imports the specifier and calls it - so a self-executing entry that mounts on import
+     * builds cleanly and then does nothing, which is the trap this contract exists to name. The type is
+     * a bare `string` because a specifier is resolved by the bundler, not the type system, so the
+     * requirement is enforced by the bootstrap instead: it throws immediately, naming this module and
+     * the missing export, rather than failing later as `mountRouter is not a function`.
+     */
     readonly clientModule: string;
     /** Turn a route/layout source file (relative to the routes dir) into an import specifier. */
     readonly resolve: (file: string) => string;
@@ -418,36 +580,66 @@ export interface GenerateClientEntryOptions {
  * bundle it with `buildClient` / `Bun.build` (+ the adapter's transform).
  */
 export declare function generateClientEntry(manifest: Manifest, options: GenerateClientEntryOptions): string;
+export interface GenerateRouteSearchTypesOptions {
+    /** Turn a route source file into a module specifier for a `typeof import(...)` type - the same contract
+     * as `generateClientEntry`'s `resolve`, but WITHOUT a file extension (a `.d.ts` imports a module, not a
+     * path). Relative to wherever the emitted `.d.ts` is written. */
+    readonly resolve: (file: string) => string;
+    /** The module whose `RouteSearch` interface is augmented (default `"@nifrajs/web"`). Every adapter's
+     * `NavigateTarget` reads `@nifrajs/web`'s `RouteSearch`, so the default types `navigate` on all of them. */
+    readonly module?: string;
+}
+/**
+ * Codegen: emit a `.d.ts` that types cross-route `navigate({ to, search })` against each route's
+ * `searchSchema`. It augments the {@link RouteSearch} map with `"<pattern>": SearchOf<typeof import(...)>`
+ * for every **static** route (one with no `:param`/`*` segment - a concrete `to` a caller can pass; a
+ * dynamic route's concrete path can't match its pattern key, so those keep the loose object form). Written
+ * by `nifra sync-routes` next to the route tree and included in the app's `tsconfig`; because it is
+ * regenerated from the route files, a `navigate` whose `search` no longer matches the route's schema
+ * becomes a `tsc` error - the same drift guarantee as nifra's typed client, no hand-maintained map.
+ */
+export declare function generateRouteSearchTypes(manifest: Manifest, options: GenerateRouteSearchTypesOptions): string;
 export interface GenerateServerManifestOptions {
-    /** Turn a route/layout source file (relative to the routes dir) into an import specifier —
+    /** Turn a route/layout source file (relative to the routes dir) into an import specifier -
      * same contract as `generateClientEntry`'s `resolve`. */
     readonly resolve: (file: string) => string;
     /** The content-hashed client entry URL (from `buildClient`'s manifest), **baked** into the emitted
-     * module — a disk-less worker can't read `manifest.json` at runtime. */
+     * module - a disk-less worker can't read `manifest.json` at runtime. */
     readonly clientEntry: string;
-    /** The app's aggregate stylesheet URLs (`buildClient`'s `BuildManifest.css`) — baked as
+    /** The app's aggregate stylesheet URLs (`buildClient`'s `BuildManifest.css`) - baked as
      * `export const styles` so the server entry can hand them to `createWebApp` (→ `<link rel="stylesheet">`
      * in `<head>`). Without this the built SSR page ships no CSS link and renders unstyled. */
     readonly styles?: readonly string[] | undefined;
-    /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) — baked as
+    /** Per-route stylesheet URLs (`buildClient`'s `BuildManifest.routeStyles`) - baked as
      * `export const routeStyles` so a page links only the CSS its route chain uses. */
     readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined;
     /** Emit **lazy** per-route loaders (`() => import("./routes/x")`, a static specifier) instead of
-     * eager `import * as`, so a bundler with code-splitting emits one chunk per route — loaded on the
+     * eager `import * as`, so a bundler with code-splitting emits one chunk per route - loaded on the
      * first request to it, not all at boot (smaller cold-start parse). Default `false` (eager). Both
      * modes are fs-free with statically-analyzable specifiers; only the *when* differs. */
     readonly lazy?: boolean;
 }
 /**
  * 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
  * entry (see `buildServer` in `@nifrajs/web/build`).
  */
 export declare function generateServerManifest(manifest: Manifest, options: GenerateServerManifestOptions): string;
+/**
+ * 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.d.ts.map