@nifrajs/web 2.2.0 → 2.3.0

package/src/manifest.ts

@@ -1,16 +1,17 @@
 /**
- * Route manifest — the fs-free heart of file-based routing. Maps route file paths to nifra
+ * Route manifest - the fs-free heart of file-based routing. Maps route file paths to nifra
  * router patterns + their nested layout chain. `discoverRoutes` (in `@nifrajs/web/fs`) scans
  * the filesystem and feeds `buildManifest`; everything here is pure logic, so it stays
  * portable (no fs, no DOM) and fully unit-testable. Edge deploys pre-build the manifest.
  */
+import type { StandardSchemaV1 } from "@nifrajs/core/server"
 
 /** Context passed to a route `loader`. The `api` + `env` are injected by `createWebApp` and typed
  * per-route via `@nifrajs/client`'s `LoaderArgs<Api, Env>` (here they are opaque to the agnostic core). */
 export interface LoaderContext {
   readonly params: Record<string, string>
   readonly request: Request
-  /** Alias of {@link request} — mirrors a route handler's `c.req` so the same name works in both. */
+  /** Alias of {@link request} - mirrors a route handler's `c.req` so the same name works in both. */
   readonly req: Request
   readonly api: unknown
   /** Platform bindings forwarded from the request `c.env` (Workers env/KV/D1). Opaque here. */
@@ -18,6 +19,10 @@ export interface LoaderContext {
   /** `true` when the request carries a valid draft/preview cookie (only when `createWebApp` is given a
    * `draftSecret`; otherwise always `false`). Branch on it to load unpublished content for editors. */
   readonly draft: boolean
+  /** The URL search params, validated against the route's `searchSchema` (a Standard Schema) when it
+   * declares one - failing closed to the schema's defaults - else the raw parsed query. Typed per-route
+   * via `@nifrajs/client`'s `LoaderArgs<Api, Env, Search>`. */
+  readonly search: Record<string, unknown>
 }
 
 /** A route's optional data loader: params/request in, data out. */
@@ -25,20 +30,20 @@ export type Loader = (ctx: LoaderContext) => unknown | Promise<unknown>
 
 /**
  * A route's optional mutation, run on POST. Shares the loader context (params/request/api);
- * read the form/JSON body off `request`. Returns either a `Response` (e.g. a redirect —
+ * read the form/JSON body off `request`. Returns either a `Response` (e.g. a redirect -
  * passed straight through) or data, surfaced to the page component as `actionData`.
  */
 export type Action = (ctx: LoaderContext) => unknown | Promise<unknown>
 
 /**
  * One `<link>` tag's attributes for a route/layout's `meta.link`. The common HTML `<link>` attributes
- * are spelled out and **optional** so a typed partial like `{ rel, href, hreflang }` is assignable —
+ * are spelled out and **optional** so a typed partial like `{ rel, href, hreflang }` is assignable -
  * the previous `Record<string, string>` required *every* value to be a present string, which rejected
- * exactly that idiomatic shape (the bug this fixes). The index signature keeps custom/`data-*` attrs
- * (and any future standard attr) passing without a cast; `boolean` covers boolean attributes like
- * `disabled` (rendered as a bare attribute when `true`, omitted when `false`), and `undefined` lets a
- * caller spread in a conditionally-absent attribute. Attribute *names* are still shape-validated and
- * values HTML-escaped at render — a widened type never widens the injection surface.
+ * exactly that idiomatic shape (the bug this fixes). Standard attributes are explicit and the template
+ * index signature admits inert `data-*` metadata without opening executable `on*` attributes. `boolean`
+ * covers `disabled` (rendered bare when `true`, omitted when `false`), and `undefined` lets a caller
+ * spread in a conditionally absent attribute. SSR and soft navigation apply one runtime allowlist too,
+ * so a cast or untyped route cannot widen the injection surface.
  */
 export interface LinkDescriptor {
   readonly rel?: string
@@ -46,6 +51,7 @@ export interface LinkDescriptor {
   readonly hreflang?: string
   readonly crossorigin?: string
   readonly media?: string
+  readonly nonce?: string
   readonly sizes?: string
   readonly type?: string
   readonly as?: string
@@ -57,49 +63,74 @@ export interface LinkDescriptor {
   readonly imagesizes?: string
   readonly color?: string
   readonly disabled?: boolean
-  readonly [attr: string]: string | boolean | undefined
+  readonly [attr: `data-${string}`]: string | undefined
 }
 
-/** One `<script>` element a route contributes to `<head>` — for structured data (JSON-LD) and other
+/** One managed `<meta>` tag. Standard attributes and inert `data-*` metadata only. */
+export interface MetaDescriptor {
+  readonly charset?: string
+  readonly content?: string
+  readonly "http-equiv"?: string
+  readonly itemprop?: string
+  readonly media?: string
+  readonly name?: string
+  readonly property?: string
+  readonly scheme?: string
+  readonly [attr: `data-${string}`]: string | undefined
+}
+
+/** One `<script>` element a route contributes to `<head>` - for structured data (JSON-LD) and other
  * inert, non-executable head scripts. The `content` is the script body; `type` defaults to
  * `"application/ld+json"` (the common case). The renderer escapes `content` against an HTML breakout
- * (`</`, `<!--`, `]]>`) — see `escapeScriptContent` — so a JSON-LD payload can never close the
+ * (`</`, `<!--`, `]]>`) - see `escapeScriptContent` - so a JSON-LD payload can never close the
  * `<script>` element early. `content` is **JSON/text, never raw HTML**: this slot is not an XSS escape
  * hatch for arbitrary markup. */
+export type InertScriptType = "application/ld+json" | "application/json"
+
 export interface ScriptDescriptor {
   /** The script's `type` attribute. Default `"application/ld+json"`. */
-  readonly type?: string
+  readonly type?: InertScriptType
   /** The script body (e.g. a `JSON.stringify`'d JSON-LD object). Escaped for safe `<script>` embedding. */
   readonly content: string
 }
 
+/** Explicit escape hatch for executable inline code. A CSP nonce is mandatory. */
+export interface UnsafeScriptDescriptor {
+  readonly unsafe: true
+  readonly type: "module" | "text/javascript"
+  readonly nonce: string
+  readonly content: string
+}
+
 /**
- * The document head a route contributes — title + `<meta>`/`<link>`/`<script>` tag sets. Returned by a
+ * The document head a route contributes - title + `<meta>`/`<link>`/`<script>` tag sets. Returned by a
  * route/layout `meta` (statically, or from a {@link MetaArgs} function). Every value is serialized into
- * managed (`data-nifra`) head tags: attribute *names* are shape-validated and *values* HTML-escaped at
- * render (see `tagAttrs`/`headTags` in `@nifrajs/web`), and `script[].content` is breakout-escaped — so
- * loader-derived strings (LLM-authored `og:*`, user content) are XSS-safe in the head by construction.
+ * managed (`data-nifra`) head tags: tag-specific attribute allowlists reject event handlers and active
+ * URL/refresh contexts, values are HTML-escaped at render, and `script[].content` is breakout-escaped -
+ * so loader-derived strings (LLM-authored `og:*`, user content) are XSS-safe by construction.
  * Layout-chain heads merge with the page's via `mergeHeads` (arrays concat outermost→page; `title` is
  * nearest-wins). Build `og:*`/`twitter:*` with `openGraph(...)`, canonical with `canonical(...)`, and
  * JSON-LD with `jsonLd(...)` (all from `@nifrajs/web`) rather than hand-writing the records.
  */
 export interface Meta {
   readonly title?: string
-  readonly meta?: ReadonlyArray<Record<string, string>>
+  readonly meta?: readonly MetaDescriptor[]
   readonly link?: readonly LinkDescriptor[]
   /** Inert head `<script>`s (JSON-LD structured data, etc.). See {@link ScriptDescriptor}. */
   readonly script?: readonly ScriptDescriptor[]
+  /** Executable inline scripts. Prefer external modules; construct only with `unsafeInlineScript()`. */
+  readonly unsafeScript?: readonly UnsafeScriptDescriptor[]
   /**
-   * The document language — `<html lang="...">`. Nearest-wins like `title`, so a localized route can
+   * The document language - `<html lang="...">`. Nearest-wins like `title`, so a localized route can
    * override a layout's default. Defaults to `"en"` when no head in the chain sets it.
    *
    * This is the ONLY way to set it: the shell's `<html>` is framework-owned, so a multilingual app
-   * otherwise serves every URL as `lang="en"` — which tells a screen reader to pronounce every locale
+   * otherwise serves every URL as `lang="en"` - which tells a screen reader to pronounce every locale
    * with an English voice, and suppresses the browser's translation offer.
    */
   readonly lang?: string
   /**
-   * The document writing direction — `<html dir="...">`. Nearest-wins like `title`. Omitted from the
+   * The document writing direction - `<html dir="...">`. Nearest-wins like `title`. Omitted from the
    * shell when unset, which is HTML's `ltr` default, so an LTR app's output is byte-identical.
    *
    * Required for Arabic/Hebrew/Urdu/Persian: without it the browser lays the page out left-to-right
@@ -110,7 +141,7 @@ export interface Meta {
 
 /**
  * Args for a route's `meta` function: the loader's `data` + the route `params` + the request `origin`.
- * `meta()` runs in BOTH SSR and client navigation, so it has **no `request`/`process.env`/server access** —
+ * `meta()` runs in BOTH SSR and client navigation, so it has **no `request`/`process.env`/server access** -
  * `origin` is the only server-resolved fact it gets (so you needn't thread `siteUrl` through loader data
  * for absolute `og:url`/`canonical`/`og:image` URLs). See {@link origin}.
  */
@@ -118,10 +149,10 @@ export interface MetaArgs<Data = unknown> {
   readonly data: Data
   readonly params: Record<string, string>
   /**
-   * The site origin — scheme + host (+ port), e.g. `"https://news.example.com"`, **with no trailing
+   * The site origin - scheme + host (+ port), e.g. `"https://news.example.com"`, **with no trailing
    * slash**. The single piece of server/env knowledge `meta()` otherwise can't see: it runs in BOTH
    * SSR and client navigation, so it has no `request`/`process.env`. The framework resolves it from the
-   * request URL during SSR and from `location.origin` on client nav — and they match, so an absolute
+   * request URL during SSR and from `location.origin` on client nav - and they match, so an absolute
    * `og:url`/`canonical`/`og:image` built from it never drifts between the server-rendered `<head>` and
    * a soft-nav. Use it for absolute URLs (`origin + "/posts/" + slug`) instead of threading `siteUrl`
    * through loader data. Empty string (`""`) when the origin is unknown (e.g. a hand-built test render
@@ -131,7 +162,7 @@ export interface MetaArgs<Data = unknown> {
 }
 
 /** A route's `meta`: a static {@link Meta}, or a function of the loader data + params + the request
- * origin ({@link MetaArgs}). Use the `origin` arg for absolute `canonical`/`og:url`/`og:image` URLs —
+ * origin ({@link MetaArgs}). Use the `origin` arg for absolute `canonical`/`og:url`/`og:image` URLs -
  * it's resolved server-side from the request and matches the client's `location.origin`. */
 export type MetaInput = Meta | ((args: MetaArgs) => Meta)
 
@@ -146,7 +177,7 @@ export interface StaticPaths {
   readonly paths: readonly StaticPath[]
   /**
    * How a path NOT in `paths` is handled. `"ssr"` (default) → rendered on-demand by the worker
-   * (the natural hybrid behavior — an unlisted path simply isn't a static file); `"404"` → only the
+   * (the natural hybrid behavior - an unlisted path simply isn't a static file); `"404"` → only the
    * listed paths exist. Recorded by `prerenderRoutes` for the deploy layer.
    */
   readonly fallback?: "ssr" | "404"
@@ -155,11 +186,21 @@ export interface StaticPaths {
 /** A dynamic route's build-time param enumeration (the SSG equivalent of "which pages exist"). */
 export type GetStaticPaths = () => StaticPaths | Promise<StaticPaths>
 
-/** A route module — the default component + optional loader / action / meta. */
+/** A route module - the default component + optional loader / action / meta. */
 export interface RouteModule {
   readonly default: unknown
   readonly loader?: Loader
   readonly action?: Action
+  /** A Standard Schema validating this route's URL search params. When present, `ctx.search` is parsed +
+   * validated against it (failing closed to the schema's defaults on invalid input); type it into the
+   * loader with `LoaderArgs<Api, Env, typeof searchSchema>`. */
+  readonly searchSchema?: StandardSchemaV1<unknown, Record<string, unknown>>
+  /** Search keys that are purely client-side UI (`"tab"`, a client-side `"sort"`, `"modal"`) and do NOT
+   * affect this route's loader. When a client navigation stays on the same route + pathname and changes
+   * ONLY these keys, the router updates the URL (so `useSearch` re-renders) WITHOUT re-running the loader.
+   * Any other key change revalidates as usual - so omitting a data-affecting key here can never serve
+   * stale data, it only forgoes the optimization. Client-only: the server always renders fresh. */
+  readonly searchClientKeys?: readonly string[]
   readonly meta?: MetaInput
   /**
    * Opt this route out of nifra's full-document client hydration. The server still renders the full
@@ -171,12 +212,12 @@ export interface RouteModule {
   /**
    * Opt a **static** route (no `:param`/`*`) into build-time prerendering (SSG): `prerenderRoutes`
    * (from `@nifrajs/web/build`) renders it to a static `index.html` at build. The loader runs at build
-   * with the in-process `api` (build-safe data only — no per-request cookies/secrets); `defer()` on a
+   * with the in-process `api` (build-safe data only - no per-request cookies/secrets); `defer()` on a
    * prerendered route resolves at build. For **dynamic** routes use {@link getStaticPaths} instead.
    */
   readonly prerender?: boolean
   /**
-   * Enumerate the concrete params to prerender for a **dynamic** (`:param`) route — the SSG path list
+   * Enumerate the concrete params to prerender for a **dynamic** (`:param`) route - the SSG path list
    * (blogs/docs/etc.). Runs at build; `prerenderRoutes` renders one `index.html` per returned path.
    */
   readonly getStaticPaths?: GetStaticPaths
@@ -188,7 +229,7 @@ export interface RouteModule {
   readonly revalidate?: number
   /**
    * No-framework island bundles (`@nifrajs/web/islands`) to load on this route, as `<script
-   * type="module">` in the document tail. Loaded **regardless of `hydrate`** — pair with
+   * type="module">` in the document tail. Loaded **regardless of `hydrate`** - pair with
    * `export const hydrate = false` for a static page that ships zero framework JS and mounts
    * interactivity through `<Island>` markers + `mountIslands` enhancers instead.
    */
@@ -198,7 +239,7 @@ export interface RouteModule {
 /** A layout (or `_404`/`_error`) entry: its source file (for client codegen) + a lazy loader.
  *
  * A `_layout.tsx` may export `meta` (static {@link Meta} or a function of the loader data + params,
- * same shape as a route's) to contribute sitewide `<head>` tags — `hreflang`/`preconnect`/etc. that
+ * same shape as a route's) to contribute sitewide `<head>` tags - `hreflang`/`preconnect`/etc. that
  * belong on every page under the layout. The layout chain's heads merge with the page's: arrays
  * (`meta`/`link`) concatenate outermost→innermost→page; scalars (`title`) are nearest-wins (the page
  * overrides an inner layout, which overrides an outer one). See `mergeHeads` in `@nifrajs/web`. */
@@ -247,7 +288,7 @@ export interface Manifest {
 
 // `.svelte` and `.vue` routes are supported too: their `default` export is the component and
 // `loader`/`action`/`meta` come from a module-level script block (Svelte `<script module>`, Vue's plain
-// `<script>`) as named ESM exports — the same RouteModule shape as `.tsx`. Both compile via their
+// `<script>`) as named ESM exports - the same RouteModule shape as `.tsx`. Both compile via their
 // package's Bun plugin (`@nifrajs/web-svelte/plugin`, `@nifrajs/web-vue/plugin`).
 const ROUTE_EXT = /\.(tsx|jsx|svelte|vue|mdx)$/
 const PARAM = /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/
@@ -256,7 +297,7 @@ const CATCH_ALL = /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/
 // two patterns (`:lang` present / absent), so `[[lang]]/about` serves both `/about` and `/en/about`.
 const OPTIONAL = /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/
 // A route group: a `(name)` folder organizes routes (and can hold its own `_layout`) without
-// contributing a URL segment — mirrors Next/Remix. Requires content between the parens.
+// contributing a URL segment - mirrors Next/Remix. Requires content between the parens.
 const GROUP = /^\(.+\)$/
 // A terminal status page: `_410.tsx`, `_451.tsx`. `_404` is matched before this and stays its own
 // thing. Restricted to 3 digits so `_401k` or `_4` is treated as an ordinary underscore-prefixed
@@ -274,7 +315,7 @@ const errorIdFor = (dir: string): string => (dir === "" ? "_error" : `${dir}/_er
  * Derive **every** nifra router pattern a route file maps to (relative to the routes dir):
  * `index` → the parent path, `[id]` → `:id`, `[...slug]` → `*slug` (catch-all, captures the rest of
  * the path into one param), `(group)` folders are dropped from the URL (organization only), and an
- * optional `[[lang]]` expands the set — once with the segment present (`:lang`) and once absent. A file
+ * optional `[[lang]]` expands the set - once with the segment present (`:lang`) and once absent. A file
  * with no optionals yields exactly one pattern. Throws on an invalid param or a catch-all that isn't
  * the last segment.
  */
@@ -311,12 +352,12 @@ function mixedFileSegment(seg: string, file: string): string | undefined {
     const inner = marker[1] ?? ""
     if (inner.startsWith("...")) {
       throw new Error(
-        `[nifra/web] catch-all "[${inner}]" cannot be combined with literal text in "${file}" (segment "${seg}") — a catch-all captures the rest of the path, so a trailing literal can never match. Give it its own segment.`,
+        `[nifra/web] catch-all "[${inner}]" cannot be combined with literal text in "${file}" (segment "${seg}") - a catch-all captures the rest of the path, so a trailing literal can never match. Give it its own segment.`,
       )
     }
     if (inner.startsWith("[")) {
       throw new Error(
-        `[nifra/web] optional "[${inner}]]" cannot be combined with literal text in "${file}" (segment "${seg}") — there is no sensible form for the segment when it is absent. Use a required [name], or give the optional its own segment.`,
+        `[nifra/web] optional "[${inner}]]" cannot be combined with literal text in "${file}" (segment "${seg}") - there is no sensible form for the segment when it is absent. Use a required [name], or give the optional its own segment.`,
       )
     }
     if (!FILE_PARAM_NAME.test(inner)) {
@@ -372,11 +413,11 @@ export function filePathToRoutes(file: string): FileRoutePattern[] {
       continue
     }
     if (GROUP.test(seg)) {
-      // Route group — no URL segment (its `_layout` still applies, keyed by dir).
+      // Route group - no URL segment (its `_layout` still applies, keyed by dir).
       mark()
       continue
     }
-    // A segment that is part literal, part `[param]` — `[inKey].txt`, `post-[id].html`. Checked
+    // A segment that is part literal, part `[param]` - `[inKey].txt`, `post-[id].html`. Checked
     // before the whole-segment forms below, which only handle a marker spanning the entire segment.
     const mixed = mixedFileSegment(seg, file)
     if (mixed !== undefined) {
@@ -425,7 +466,7 @@ export function filePathToRoutes(file: string): FileRoutePattern[] {
 }
 
 /**
- * The **canonical** single pattern for a route file — all optional segments present. A file with no
+ * The **canonical** single pattern for a route file - all optional segments present. A file with no
  * optionals yields its one pattern. Use {@link filePathToPatterns} to get every pattern (optionals
  * expand the set).
  */
@@ -469,7 +510,7 @@ const ancestorDirs = (file: string): string[] => {
 
 /**
  * Build a manifest from route file paths (relative to the routes dir) + an `importer` that
- * turns a path into a lazy module loader. Pure — no fs. Throws at boot (the loud-and-early
+ * turns a path into a lazy module loader. Pure - no fs. Throws at boot (the loud-and-early
  * RouteConfigError ethos) on duplicate patterns. `_layout`/`_404`/`_error` files are special; other
  * `_`-prefixed files are ignored (private/colocated, never routed).
  */
@@ -577,7 +618,7 @@ export function fillRoutePattern(
 /** The static-routing facts a server needs from the route modules: which concrete paths are
  * prerendered, plus each dynamic route's `getStaticPaths` fallback policy. */
 export interface StaticRoutes {
-  /** Concrete prerendered paths — static `prerender` routes + each `getStaticPaths` entry. */
+  /** Concrete prerendered paths - static `prerender` routes + each `getStaticPaths` entry. */
   readonly paths: string[]
   /** Per dynamic route pattern, its `getStaticPaths` `fallback` (`"ssr"` default). `createWebApp` uses
    * `"404"` to reject an unlisted path under that route at runtime (the path simply doesn't exist). */
@@ -585,7 +626,7 @@ export interface StaticRoutes {
 }
 
 /**
- * Enumerate the static-routing facts `prerenderRoutes` would produce — static routes opted in via
+ * Enumerate the static-routing facts `prerenderRoutes` would produce - static routes opted in via
  * `export const prerender = true`, each `getStaticPaths` entry of a dynamic route, and each dynamic
  * route's `fallback` policy. Pure (no rendering), so a server can compute what to hand `createWebApp`
  * (the prerendered set for the client's static-`_data.json` soft-nav + the fallback map for

package/src/module-graph.ts

@@ -82,10 +82,10 @@ export function fromBunMetafile(meta: BunMetafileLike | undefined): ClientModule
 /**
  * The slice of a Rollup/Vite output bundle this seam consumes. `OutputBundle` is
  * `Record<fileName, OutputChunk | OutputAsset>`; only chunks carry a module graph. Typed structurally
- * (no `rollup`/`vite` type dependency) — the fields are stable Rollup output API.
+ * (no `rollup`/`vite` type dependency) - the fields are stable Rollup output API.
  */
 export interface RollupChunkLike {
-  /** `"chunk"` for JS output, `"asset"` for CSS/static — assets have no module graph. */
+  /** `"chunk"` for JS output, `"asset"` for CSS/static - assets have no module graph. */
   readonly type?: string
   /** The entry module id this chunk was built for, if it is an entry. Rollup's `facadeModuleId`. */
   readonly facadeModuleId?: string | null
@@ -95,12 +95,12 @@ export interface RollupChunkLike {
 export type RollupBundleLike = Readonly<Record<string, RollupChunkLike>>
 
 /**
- * Adapt a Rollup/Vite output bundle to the neutral graph — the second producer the seam was built for.
+ * Adapt a Rollup/Vite output bundle to the neutral graph - the second producer the seam was built for.
  *
  * The bundle records which modules landed in which chunk (`moduleIds`) but NOT each module's import
  * edges, so those come from `importsOf`, which the caller backs with `this.getModuleInfo(id).importedIds`
- * inside a plugin hook (a test backs it with a plain map). Edges carry only the RESOLVED id — Rollup does
- * not keep the as-written specifier per edge — so `path` is set and `original` is left undefined. Both
+ * inside a plugin hook (a test backs it with a plain map). Edges carry only the RESOLVED id - Rollup does
+ * not keep the as-written specifier per edge - so `path` is set and `original` is left undefined. Both
  * guards read the resolved `path` as their fallback (a `node:` prefix, the `server-only` basename), so
  * detection is unaffected; only the human-readable chain shows resolved paths instead of as-written ones.
  *
@@ -136,7 +136,7 @@ export function fromRollupBundle(
       }
     }
     chunks[fileName] = {
-      // `facadeModuleId` is null for a shared/common chunk (no single entry) — omit it then, matching
+      // `facadeModuleId` is null for a shared/common chunk (no single entry) - omit it then, matching
       // how a non-entry Bun output omits `entryPoint`, so the guards' entry set stays the real entries.
       ...(output.facadeModuleId ? { entryPoint: output.facadeModuleId } : {}),
       modules: chunkModules,

package/src/navigation.ts

@@ -1,23 +1,94 @@
 /**
- * `@nifrajs/web` navigation bridge — a tiny, DOM-free seam that lets an adapter's `useNavigate`
- * (a route component, which must import only from the agnostic `@nifrajs/web` main entry — never the
+ * `@nifrajs/web` navigation bridge - a tiny, DOM-free seam that lets an adapter's `useNavigate`
+ * (a route component, which must import only from the agnostic `@nifrajs/web` main entry - never the
  * DOM-only `/client`) reach the browser's history-aware navigate, WITHOUT the route component pulling
  * `@nifrajs/web/client` (and its `document`/`history` access) into a bundle that also renders on the
  * server.
  *
  * The browser layer (`installHistory`, in `./client.ts`) populates this on setup and clears it on
- * teardown; a framework binding reads it via {@link getBrowserNavigate}. Module-level singleton — the
+ * teardown; a framework binding reads it via {@link getBrowserNavigate}. Module-level singleton - the
  * browser mounts exactly one app per page (the same convention the adapters' `setMountedRouter` uses).
  * On the server (and before hydration) the getter returns `undefined`, so a binding degrades to the
- * native `<a href>` full-page navigation — progressive enhancement, no throw.
+ * native `<a href>` full-page navigation - progressive enhancement, no throw.
  */
 
+import { serializeSearch } from "./search.ts"
+
 /** Options for a programmatic navigation. */
 export interface NavigateOptions {
   /** Replace the current history entry instead of pushing a new one (like `history.replaceState`). */
   readonly replace?: boolean
 }
 
+/**
+ * The augmentable route -> search-type map for typed cross-route navigation. Empty by default (so an
+ * object-form navigate to any path is allowed with a loose `search`). A build step (`nifra sync-routes`)
+ * OR the app declares one entry per route path against its `searchSchema` output:
+ *
+ * ```ts
+ * declare module "@nifrajs/web" {
+ *   interface RouteSearch {
+ *     "/reports": { page: number; q: string }
+ *   }
+ * }
+ * ```
+ *
+ * With that, `navigate({ to: "/reports", search: { page: 2 } })` type-checks `search` against
+ * `/reports`'s schema, and a wrong shape is a compile error. See {@link NavigateTarget}.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmentation target - empty by design, apps/codegen fill it.
+export interface RouteSearch {}
+
+/**
+ * The `search` type for a navigate to `To`: the route's schema output when `To` is a mapped
+ * {@link RouteSearch} key, otherwise the loose `Record<string, unknown>` (so a navigate to any path is
+ * always allowed). Keyed on `To` rather than a union, so a mapped route can't fall back to the loose form
+ * with a wrong shape - `navigate({ to: "/reports", search: { page: "x" } })` is a compile error.
+ */
+export type NavigateSearchOf<To extends string> = To extends keyof RouteSearch
+  ? RouteSearch[To]
+  : Record<string, unknown>
+
+/** The runtime shape of an object-form navigate target (loose - the typed narrowing lives in
+ * {@link NavigateFunction}'s generic call signature). `to` is a bare pathname; `search` is serialized
+ * onto it; `replace` folds into the options. */
+export interface NavigateTargetInput {
+  readonly to: string
+  readonly search?: Record<string, unknown>
+  readonly replace?: boolean
+}
+
+/**
+ * A programmatic navigate, shared by every adapter's `useNavigate`. Three forms: a string path (push, or
+ * replace via `{ replace: true }`), a history delta (`-1`/`1`), or an object target `{ to, search, replace }`
+ * whose `search` is typed against `to`'s route schema via {@link NavigateSearchOf} (a wrong shape for a
+ * mapped route is a compile error; an unmapped path takes a loose `search`). The object form's `search` is
+ * serialized onto `to`. A no-op on the server / before hydration.
+ */
+export interface NavigateFunction {
+  (to: string | number, options?: NavigateOptions): void
+  <To extends string>(target: {
+    readonly to: To
+    readonly search?: NavigateSearchOf<To>
+    readonly replace?: boolean
+  }): void
+}
+
+/**
+ * Normalize a navigate argument to the bridge's `(to, options)`: a string path or history-delta passes
+ * through; an object target has its `search` serialized onto `to` and its `replace` folded into the
+ * options. The one place the object form becomes a URL, so every adapter's `navigate` resolves it
+ * identically.
+ */
+export function resolveNavigate(
+  to: string | number | NavigateTargetInput,
+  options?: NavigateOptions,
+): { readonly to: string | number; readonly options: NavigateOptions | undefined } {
+  if (typeof to !== "object") return { to, options }
+  const query = to.search !== undefined ? serializeSearch(to.search) : ""
+  return { to: to.to + query, options: to.replace === true ? { replace: true } : options }
+}
+
 /**
  * A history-aware navigate. A **string** `to` is a same-origin path (`/users/7?tab=a`) navigated to
  * (push, or replace with `{ replace: true }`); a **number** is a history delta (`-1` back, `1`
@@ -29,7 +100,7 @@ export type BrowserNavigate = (to: string | number, options?: NavigateOptions) =
 // per page; absent on the server and before hydration.
 let browserNavigate: BrowserNavigate | undefined
 
-/** Register (or clear, with `undefined`) the browser navigate — called by `installHistory`. Not for
+/** Register (or clear, with `undefined`) the browser navigate - called by `installHistory`. Not for
  * app use. */
 export function setBrowserNavigate(navigate: BrowserNavigate | undefined): void {
   browserNavigate = navigate
@@ -40,3 +111,78 @@ export function setBrowserNavigate(navigate: BrowserNavigate | undefined): void
 export function getBrowserNavigate(): BrowserNavigate | undefined {
   return browserNavigate
 }
+
+/** A parsed navigation target the {@link BlockerFunction} decides on. `pathname`/`search`/`hash` match
+ * the DOM `Location` shape (search keeps its `?`, hash its `#`). */
+export interface BlockerLocation {
+  readonly pathname: string
+  readonly search: string
+  readonly hash: string
+}
+
+/**
+ * Decide whether a navigation should be halted. Receives where the app is (`currentLocation`) and where
+ * it's heading (`nextLocation`), so a guard can allow same-section moves and block only real exits. A
+ * boolean form (`useBlocker(isDirty)`) is sugar for `() => isDirty`. Runs synchronously at navigation
+ * time - return the current answer; the async "are you sure?" happens afterward via {@link Blocker}'s
+ * `proceed`/`reset`.
+ */
+export type BlockerFunction = (args: {
+  readonly currentLocation: BlockerLocation
+  readonly nextLocation: BlockerLocation
+}) => boolean
+
+/**
+ * The blocker's lifecycle. `unblocked` - idle, nothing intercepted. `blocked` - a navigation was halted
+ * and is awaiting the app's decision (`proceed`/`reset` are live). `proceeding` - the app called
+ * `proceed`; the held navigation is being replayed.
+ */
+export type BlockerState = "unblocked" | "blocked" | "proceeding"
+
+/**
+ * A navigation guard, mirroring react-router's shape. When `state` is `blocked`, `proceed()` lets the
+ * held navigation through and `reset()` cancels it (staying put); both are `undefined` otherwise. The
+ * pair is what a boolean `when` can't express - the app shows its OWN async confirmation UI, then calls
+ * one of them, instead of the browser's synchronous `confirm()`.
+ */
+export interface Blocker {
+  readonly state: BlockerState
+  readonly proceed: (() => void) | undefined
+  readonly reset: (() => void) | undefined
+}
+
+/** The idle blocker - a stable reference (no needless adapter re-renders while unblocked). */
+export const IDLE_BLOCKER: Blocker = { state: "unblocked", proceed: undefined, reset: undefined }
+
+/**
+ * The browser layer's blocker registry - installed by `installHistory` (which owns navigation and can
+ * therefore halt, restore, and replay it) and read by an adapter's `useBlocker` through
+ * {@link registerBlocker}. Kept here, DOM-free, for the same reason as {@link BrowserNavigate}: a route
+ * component's blocker hook must import only this agnostic entry.
+ */
+export interface BlockerController {
+  register(shouldBlock: BlockerFunction, onChange: (blocker: Blocker) => void): () => void
+}
+
+// The active controller (set by `installHistory`, cleared on teardown). Module-scoped: one app per page.
+let blockerController: BlockerController | undefined
+
+/** Register (or clear, with `undefined`) the blocker controller - called by `installHistory`. Not for
+ * app use. */
+export function setBlockerController(controller: BlockerController | undefined): void {
+  blockerController = controller
+}
+
+/**
+ * Register a navigation guard, returning an unregister function. `onChange` is called with the current
+ * {@link Blocker} whenever its state changes (so the adapter can re-render its confirmation UI). Before
+ * `installHistory` has run (SSR, pre-hydration), there's no controller: registration is a no-op and the
+ * caller stays on {@link IDLE_BLOCKER}, degrading to native navigation. Called by an adapter's
+ * `useBlocker`, not by app code directly.
+ */
+export function registerBlocker(
+  shouldBlock: BlockerFunction,
+  onChange: (blocker: Blocker) => void,
+): () => void {
+  return blockerController?.register(shouldBlock, onChange) ?? (() => {})
+}

package/src/plugins/kit.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/web/plugins` shared kit — the small infrastructure every CSS-bearing asset plugin reuses, so
+ * `@nifrajs/web/plugins` shared kit - the small infrastructure every CSS-bearing asset plugin reuses, so
  * P1 (CSS Modules), P2 (SCSS), and any future P4 (LESS/Stylus/PostCSS) don't each re-implement the
  * CSS→client-bundle wiring, the deterministic hash, or the optional-peer guard. Internal to
  * `@nifrajs/web` (imported by the sibling plugin modules); not a public subpath.
@@ -8,7 +8,7 @@ import { existsSync } from "node:fs"
 import { dirname, relative } from "node:path"
 import type { BunPlugin } from "bun"
 
-/** The argument Bun passes to a plugin's `setup` — Bun doesn't export the type, so derive it. */
+/** The argument Bun passes to a plugin's `setup` - Bun doesn't export the type, so derive it. */
 export type PluginBuilder = Parameters<BunPlugin["setup"]>[0]
 
 const packageRootCache = new Map<string, string>()
@@ -23,7 +23,7 @@ function packageRootOf(startDir: string): string {
     if (existsSync(`${dir}/package.json`)) break
     const parent = dirname(dir)
     if (parent === dir) {
-      dir = startDir // reached the filesystem root with no package.json — anchor on the file's own dir
+      dir = startDir // reached the filesystem root with no package.json - anchor on the file's own dir
       break
     }
     dir = parent
@@ -33,11 +33,11 @@ function packageRootOf(startDir: string): string {
 }
 
 /**
- * A **package-root-relative**, forward-slashed form of an absolute path — the input to {@link hash8} for
+ * A **package-root-relative**, forward-slashed form of an absolute path - the input to {@link hash8} for
  * any build-stable identifier (e.g. CSS-module scoped names). Anchoring on the file's nearest
  * `package.json` (not the absolute path, not `process.cwd()`) makes the result independent of BOTH the
- * machine's directory layout AND the working directory: the dom build and the ssr runtime — even on
- * different machines or from different cwds — derive the SAME relative path for a given file, so their
+ * machine's directory layout AND the working directory: the dom build and the ssr runtime - even on
+ * different machines or from different cwds - derive the SAME relative path for a given file, so their
  * scoped class maps always agree. (Hashing the absolute path would differ across CI/host; a
  * cwd-relative path would silently desync if the SSR server started from a non-project-root cwd.)
  */
@@ -47,7 +47,7 @@ export function reproduciblePath(absolutePath: string): string {
 }
 
 /**
- * Deterministic 8-hex hash (djb2/xor). Stable across builds — no `Date.now`/`Math.random` — so build
+ * Deterministic 8-hex hash (djb2/xor). Stable across builds - no `Date.now`/`Math.random` - so build
  * output is reproducible. The single hash implementation behind CSS-module scoped names (and a drop-in
  * for any SFC scope id).
  */
@@ -58,7 +58,7 @@ export function hash8(input: string): string {
 }
 
 /**
- * Records compiled CSS and wires it into the client bundle through a virtual `?<namespace>` module —
+ * Records compiled CSS and wires it into the client bundle through a virtual `?<namespace>` module -
  * the idiom the Vue plugin established (`?vue-css`). Register one per plugin `setup`; call `emit` per
  * file to stash its CSS and get back the `import` line to append to the JS module.
  */
@@ -70,7 +70,7 @@ export interface StylesheetEmitter {
 /**
  * Wire the virtual-CSS-module handlers onto `build` for `namespace`, returning an {@link StylesheetEmitter}.
  * The `namespace` must be a plain identifier (letters/`-`); it's used verbatim as the import suffix and
- * the Bun namespace. Only the `"dom"` build should emit CSS — the `"ssr"` build ships no stylesheet.
+ * the Bun namespace. Only the `"dom"` build should emit CSS - the `"ssr"` build ships no stylesheet.
  */
 export function createStylesheetEmitter(
   build: PluginBuilder,
@@ -97,7 +97,7 @@ export function createStylesheetEmitter(
 
 /**
  * Load an optional peer compiler at build time, throwing a consistent, actionable install-hint error if
- * it's absent — the `@vue/compiler-sfc` peer pattern, centralized. Build-time only, so the dynamic
+ * it's absent - the `@vue/compiler-sfc` peer pattern, centralized. Build-time only, so the dynamic
  * `import` (which keeps the peer out of the package's hard dependencies) is correct here.
  */
 export async function requirePeer<T>(
@@ -107,7 +107,7 @@ export async function requirePeer<T>(
   try {
     return (await import(specifier)) as T
   } catch (err) {
-    // Only a genuine resolution failure means "not installed" — surface anything else (a corrupt
+    // Only a genuine resolution failure means "not installed" - surface anything else (a corrupt
     // install, a native-binding error, a throw at module top-level) as the real error rather than
     // masking it behind a misleading "please install it" hint.
     if ((err as { code?: unknown }).code === "ERR_MODULE_NOT_FOUND") {