@nifrajs/web-react 2.2.0 → 2.4.0

package/src/compose.ts

@@ -5,22 +5,26 @@ import { RouterContext } from "./router.ts"
 // Stable empty params so the provider value's `params` has a fixed reference when a route has none.
 const EMPTY_PARAMS: Readonly<Record<string, string>> = Object.freeze({})
 
+// Stable empty search for the same reason: a render with no search context (or a non-router usage).
+const EMPTY_SEARCH: Readonly<Record<string, unknown>> = Object.freeze({})
+
 /**
  * Fold a layout chain (outermost layout → page) into a single React tree: the page
  * (innermost) receives `props` (the loader data); each layout wraps the child via its
  * `children`. Shared by the server adapter (renderToString) and the client (hydrateRoot).
  *
  * The whole tree is wrapped in a {@link RouterContext} provider carrying the matched `params`, the
- * current `path`, and the client `pending` flag (all threaded through `RenderProps` identically on SSR
- * and client), so the routing hooks (`useParams`/`useLocation`/`useNavigation`) read the same value on
- * both sides - no hydration mismatch (`pending` is `false` on SSR and on the initial client render).
+ * current `path`, the validated `search`, and the client `pending` flag (all threaded through
+ * `RenderProps` identically on SSR and client), so the routing hooks
+ * (`useParams`/`useLocation`/`useSearch`/`useNavigation`) read the same value on both sides - no
+ * hydration mismatch (`pending` is `false` on SSR and on the initial client render).
  * A render with no routing fields (a non-router adapter usage) provides the empty default.
  */
 export function compose(chain: readonly unknown[], props: RenderProps): ReactNode {
   const last = chain.length - 1
   let node: ReactNode = createElement(chain[last] as FunctionComponent<RenderProps>, props)
   for (let i = last - 1; i >= 0; i--) {
-    // children passed as the 3rd arg (not a `children` prop) — React's canonical form.
+    // children passed as the 3rd arg (not a `children` prop) - React's canonical form.
     // Each layout receives its own loader data at its own index. Layouts are the chain's leading
     // prefix, so `layoutData[i]` belongs to `chain[i]`; anything past that end (a client-only `_error`
     // boundary marker, the page) reads `undefined` and is unaffected.
@@ -36,6 +40,7 @@ export function compose(chain: readonly unknown[], props: RenderProps): ReactNod
       value: {
         params: props.params ?? EMPTY_PARAMS,
         path: props.path ?? "",
+        search: props.search ?? EMPTY_SEARCH,
         pending: props.pending ?? false,
         pendingPath: props.pendingPath,
       },

package/src/content.ts

@@ -1,10 +1,10 @@
 /**
- * `@nifrajs/web-react/content` — render pre-rendered HTML (e.g. a `@nifrajs/content` collection entry's
+ * `@nifrajs/web-react/content` - render pre-rendered HTML (e.g. a `@nifrajs/content` collection entry's
  * `.html`, or any Markdown→HTML string) into the DOM via `dangerouslySetInnerHTML`. Pairs with content
  * collections: `<Content html={entry.html} />`.
  *
  * Security: this injects raw HTML, so the `html` MUST be trusted (your own Markdown/content, rendered
- * at build/server time) — never pass user-supplied HTML without sanitizing it first.
+ * at build/server time) - never pass user-supplied HTML without sanitizing it first.
  */
 import {
   type ComponentPropsWithoutRef,

package/src/error.ts

@@ -1,5 +1,5 @@
 /**
- * `errorBoundary` — the React error-boundary chain element for nifra's `_error.tsx`. Kept in its own
+ * `errorBoundary` - the React error-boundary chain element for nifra's `_error.tsx`. Kept in its own
  * module (imports only `react`, never `react-dom/client`) so it's unit-testable off the DOM and the
  * client codegen can import it from `@nifrajs/web-react/client` (which re-exports it).
  */
@@ -9,7 +9,7 @@ import { Component, createElement, type FunctionComponent, type ReactNode } from
  * Build an error-boundary chain element bound to `fallback` (a route's `_error` component). nifra's
  * client codegen inserts it before the page in the matched chain; a render error in the subtree renders
  * `fallback` with `{ data: { name, message } }` instead of crashing the app. DOM-transparent (it renders
- * its children directly — no wrapper element), so it adds no markup and never disturbs hydration.
+ * its children directly - no wrapper element), so it adds no markup and never disturbs hydration.
  */
 export function errorBoundary(fallback: unknown): unknown {
   type Props = { children?: ReactNode }
@@ -25,7 +25,7 @@ export function errorBoundary(fallback: unknown): unknown {
     override render(): ReactNode {
       const { error } = this.state
       if (error === null) return this.props.children
-      // `fallback` is the route's `_error` default export — opaque to the core, a component here.
+      // `fallback` is the route's `_error` default export - opaque to the core, a component here.
       const Fallback = fallback as FunctionComponent<{ data: { name: string; message: string } }>
       return createElement(Fallback, { data: { name: error.name, message: error.message } })
     }

package/src/fetcher.ts

@@ -1,12 +1,12 @@
 import type { ClientRouter, Fetcher, FetcherState } from "@nifrajs/web"
 /**
- * `@nifrajs/web-react/fetcher` — React bindings for concurrent fetchers. `useFetcher(key)` subscribes a
+ * `@nifrajs/web-react/fetcher` - React bindings for concurrent fetchers. `useFetcher(key)` subscribes a
  * component to an independent {@link Fetcher} (via `useSyncExternalStore`) and returns its reactive
  * state plus `load`/`submit`; `useFetchers()` subscribes to the whole live collection. Imports only
  * `react` (never `react-dom/*`), so route components can use it on the server *and* client without
  * dragging either DOM build into the wrong bundle. No JSX (the package builds with plain `tsc`).
  *
- * The router that owns the fetchers is the one `mountRouter` hydrated — it registers itself here via
+ * The router that owns the fetchers is the one `mountRouter` hydrated - it registers itself here via
  * `setMountedRouter`. On the server (no mount) there is no router, so the hooks return an idle state
  * (fetchers are client-only); the first client render after `mountRouter` sees the real fetcher, so
  * there's no hydration mismatch.
@@ -17,7 +17,7 @@ import { useSyncExternalStore } from "react"
 // page, and fetchers never exist on the server. Shared with `client.ts`'s `mountRouter`.
 let mountedRouter: ClientRouter | undefined
 
-/** Register (or clear) the router that owns fetchers — called by `mountRouter`. Not for app use. */
+/** Register (or clear) the router that owns fetchers - called by `mountRouter`. Not for app use. */
 export function setMountedRouter(router: ClientRouter | undefined): void {
   mountedRouter = router
 }
@@ -53,7 +53,7 @@ export function useFetcher(key: string): FetcherHandle {
 }
 
 /**
- * Subscribe to the whole live fetcher collection — for a global busy view (e.g. "3 saving…"). Read
+ * Subscribe to the whole live fetcher collection - for a global busy view (e.g. "3 saving…"). Read
  * each entry's `.snapshot()` for its state. Re-renders whenever any fetcher transitions or a new one
  * is created.
  */

package/src/fn.ts

@@ -0,0 +1,43 @@
+/**
+ * `@nifrajs/web-react/fn` - React binding for a server function's pending/error state.
+ *
+ * Calling a server function needs no hook: the client stub is `(input) => Promise<Output>`. This adds
+ * the part a component usually wants around it - in flight, last result, last error - and nothing more.
+ *
+ * The state machine is `@nifrajs/web`'s `createServerFnStore`, shared with every other adapter, so
+ * "is it pending" has one answer rather than five that drift. This file contributes only the `useSyncExternalStore` subscription.
+ */
+
+import type { ClientServerFn, ServerFnReference } from "@nifrajs/web/fn"
+import { createServerFnStore, type ServerFnState } from "@nifrajs/web/fn-state"
+import { useMemo, useRef, useSyncExternalStore } from "react"
+
+/** A server function's state plus the call itself. */
+export interface ServerFnHandle<Input, Output> extends ServerFnState<Output> {
+  /** Invoke it. Records state, and rejects on failure - attach `.catch` if you only render state. */
+  readonly call: (input: Input) => Promise<Output>
+  /** Back to idle. */
+  readonly reset: () => void
+}
+
+/**
+ * Track one server function's call state.
+ *
+ *     const addTodo = useServerFn(fns.addTodo)
+ *     <button disabled={addTodo.pending} onClick={() => addTodo.call({ text }).catch(() => {})}>
+ *
+ * The store is per component instance and created once; `fn` is read on the first render only, so a
+ * freshly-created inline function neither resets the state nor goes stale.
+ */
+export function useServerFn<Input, Output>(
+  fn: ServerFnReference<Input, Output>,
+): ServerFnHandle<Input, Output> {
+  // The store is created once, but always calls the CURRENT `fn`. Capturing `fn` directly would
+  // either recreate the store on every render (losing the state) or hold the first render's closure
+  // (calling a stale one); the ref is what makes "created once" and "never stale" both true.
+  const latest = useRef(fn as ClientServerFn<Input, Output>)
+  latest.current = fn as ClientServerFn<Input, Output>
+  const store = useMemo(() => createServerFnStore((input: Input) => latest.current(input)), [])
+  const state = useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot)
+  return { ...state, call: store.call, reset: store.reset }
+}

package/src/i18n.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/web-react/i18n` — React bindings for `@nifrajs/i18n`. `<I18nProvider locale messages>` builds a
+ * `@nifrajs/web-react/i18n` - React bindings for `@nifrajs/i18n`. `<I18nProvider locale messages>` builds a
  * `Formatter` (memoized) and provides it; `useT()` reads it. Both `locale` + `messages` are
  * serializable, so a loader returns them, the page renders with the negotiated catalog on the server,
  * and the client rebuilds the same formatter from the same props (no mismatch). Imports only `react` +

package/src/image.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/web-react/image` — a CLS-safe responsive React `<Image>`. A thin wrapper over
+ * `@nifrajs/web-react/image` - a CLS-safe responsive React `<Image>`. A thin wrapper over
  * `resolveImage` from `@nifrajs/image`: it computes `src`/`srcSet`/`sizes`/`width`/`height`/`loading`/
  * `decoding`/`fetchpriority` and renders a plain `<img>`, forwarding any extra DOM props
  * (`className`, `style`, `id`, event handlers, `data-*`, …). Resizing is delegated to the `loader`
@@ -8,7 +8,7 @@
 import { type ImageLoader, type ImageProps, resolveImage } from "@nifrajs/image"
 import { type ComponentPropsWithoutRef, createElement, type ReactElement } from "react"
 
-/** Attributes `resolveImage` computes — callers can't override them via DOM passthrough. */
+/** Attributes `resolveImage` computes - callers can't override them via DOM passthrough. */
 type ComputedAttrs =
   | "src"
   | "srcSet"
@@ -23,7 +23,7 @@ type ComputedAttrs =
 export interface ImageComponentProps
   extends ImageProps,
     Omit<ComponentPropsWithoutRef<"img">, ComputedAttrs | keyof ImageProps> {
-  /** CDN URL builder. Defaults to the identity loader (no transform — still CLS-safe + lazy). */
+  /** CDN URL builder. Defaults to the identity loader (no transform - still CLS-safe + lazy). */
   readonly loader?: ImageLoader
   /** `data-*` attributes pass through to the `<img>` (React doesn't auto-allow these on a custom
    * component, so they're declared explicitly). */

package/src/index.ts

@@ -1,21 +1,21 @@
 import type { RenderAdapter } from "@nifrajs/web"
 /**
- * @nifrajs/web-react — the React render adapter for @nifrajs/web (server side). Streaming SSR via
+ * @nifrajs/web-react - the React render adapter for @nifrajs/web (server side). Streaming SSR via
  * `renderToReadableStream`; the layout-chain fold is in `./compose`. Client hydration lives in
- * `@nifrajs/web-react/client`. React's JSX is Bun-native — no build plugin needed.
+ * `@nifrajs/web-react/client`. React's JSX is Bun-native - no build plugin needed.
  */
 import { compose } from "./compose.ts"
 import { reactDomServer } from "./react-dom-server.ts"
 
-/** The React server render adapter — pass to @nifrajs/web's `renderPage`. */
+/** The React server render adapter - pass to @nifrajs/web's `renderPage`. */
 export const reactAdapter: RenderAdapter = {
   // Synchronous one-pass render for non-deferred pages (renderPage's buffered fast path). React's
   // `renderToString` emits the same hydration-compatible markup as the Fizz stream for non-Suspense
-  // content and is markedly cheaper than `renderToReadableStream` — most visibly on Bun, where Fizz's
+  // content and is markedly cheaper than `renderToReadableStream` - most visibly on Bun, where Fizz's
   // streaming machinery is the heaviest. A page that defer()s/Suspends takes `renderToStream` below.
   //
   // Async because the `react-dom/server` module is resolved lazily (from the consumer app's node_modules
-  // under Bun runtime SSR — see ./react-dom-server). `RenderAdapter.renderToString` permits a Promise;
+  // under Bun runtime SSR - see ./react-dom-server). `RenderAdapter.renderToString` permits a Promise;
   // renderPage awaits it.
   async renderToString(chain, props) {
     const { renderToString } = await reactDomServer()
@@ -23,13 +23,13 @@ export const reactAdapter: RenderAdapter = {
   },
   async renderToStream(chain, props) {
     // Resolves a Web `ReadableStream<Uint8Array>` once the shell is renderable; Suspense
-    // boundaries stream as they resolve. No `bootstrapModules` — nifra injects the client entry in
+    // boundaries stream as they resolve. No `bootstrapModules` - nifra injects the client entry in
     // the document tail. React's default `onError` logs to console.error (errors aren't swallowed).
     const { renderToReadableStream } = await reactDomServer()
     return renderToReadableStream(compose(chain, props))
   },
   // React reconciles against the existing DOM on hydrate, so no per-document bootstrap
-  // script is needed (contrast Solid's generateHydrationScript) — the seam allows both.
+  // script is needed (contrast Solid's generateHydrationScript) - the seam allows both.
   hydrationHead() {
     return ""
   },

package/src/island.ts

@@ -1,8 +1,8 @@
 import type { IslandStrategy } from "@nifrajs/web/islands"
 /**
- * `@nifrajs/web-react/island` — the `<Island>` marker for no-framework islands. Server-renders its
+ * `@nifrajs/web-react/island` - the `<Island>` marker for no-framework islands. Server-renders its
  * children inside a `<nifra-island>` element that the framework-agnostic `mountIslands` runtime
- * (`@nifrajs/web/islands`) picks up on the client. Imports only `react` (+ a type) — no `react-dom`,
+ * (`@nifrajs/web/islands`) picks up on the client. Imports only `react` (+ a type) - no `react-dom`,
  * no JSX (the package builds with plain `tsc`).
  *
  * Use on a route with `export const hydrate = false`: the page ships zero framework JS, and only the
@@ -18,7 +18,7 @@ export interface IslandProps {
   readonly props?: unknown
   /** When the enhancer runs (default `load`). `visible` (IntersectionObserver) wins TTI on long pages. */
   readonly strategy?: IslandStrategy
-  /** The island's server-rendered content — real HTML, present with JS off. */
+  /** The island's server-rendered content - real HTML, present with JS off. */
   readonly children?: ReactNode
 }
 

package/src/query.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/web-react/query` — React bindings for the keyed query-cache + mutations: `useQuery`,
+ * `@nifrajs/web-react/query` - React bindings for the keyed query-cache + mutations: `useQuery`,
  * `useInfiniteQuery`, `useMutation`, `useQueryClient`, `QueryClientProvider`, and the SSR
  * `HydrationBoundary` (+ `dehydrate` re-exported). A drop-in for the TanStack Query surface,
  * backed by `@nifrajs/web`'s agnostic engine. Imports only `react` + `@nifrajs/web` (never `react-dom/*`),
@@ -7,7 +7,7 @@
  *
  * Resolution order for the client a hook uses: a `QueryClientProvider` in the tree (required for SSR
  * dehydrate/hydrate and for tests), else a lazily-created **client-side** module singleton (the simple
- * client-only app — the `typeof window` guard means the server has none, so hooks render idle/pending
+ * client-only app - the `typeof window` guard means the server has none, so hooks render idle/pending
  * and the first client render matches for a clean hydration).
  */
 import {
@@ -61,7 +61,7 @@ const NOOP_CLIENT: QueryClient = {
 
 const QueryClientContext = createContext<QueryClient | undefined>(undefined)
 
-/** Provide a {@link QueryClient} to the tree — required for SSR dehydrate/hydrate and for tests; a
+/** Provide a {@link QueryClient} to the tree - required for SSR dehydrate/hydrate and for tests; a
  * client-only app can omit it and rely on the built-in client-side singleton. */
 export function QueryClientProvider(props: {
   readonly client: QueryClient
@@ -113,13 +113,13 @@ const IDLE_INFINITE_HANDLE = {
 
 /** Options for {@link useQuery}. */
 export interface UseQueryOptions extends QueryOptions {
-  /** When `false`, don't fetch (the query stays idle) — for dependent queries. Default `true`. */
+  /** When `false`, don't fetch (the query stays idle) - for dependent queries. Default `true`. */
   readonly enabled?: boolean
 }
 
 /** A query's reactive {@link QueryState} plus `isPending` + `refetch`. */
 export interface UseQueryResult<T> extends QueryState<T> {
-  /** `status === "pending"` — no data yet (initial load). */
+  /** `status === "pending"` - no data yet (initial load). */
   readonly isPending: boolean
   /** `status === "error"`. */
   readonly isError: boolean
@@ -148,7 +148,7 @@ export function useQuery<T>(
   // A disabled query still binds a handle (so it re-renders when re-enabled), but never fetches.
   const handle: QueryHandle<T> = client.query<T>(key, fn, queryOpts)
   // Server snapshot = the handle's own snapshot: without a provider the client is the NOOP one (idle),
-  // but WITH a hydrated provider client it returns the server-seeded data — so a HydrationBoundary-fed
+  // but WITH a hydrated provider client it returns the server-seeded data - so a HydrationBoundary-fed
   // query renders its data during SSR and the first client render matches (no loading flash, no drift).
   const state = useSyncExternalStore<QueryState<T>>(
     handle.subscribe,
@@ -175,7 +175,7 @@ export interface UseMutationResult<TData, TVariables> extends MutationState<TDat
   readonly isSuccess: boolean
   /** Fire-and-forget: runs the mutation and swallows rejection (read `error`/`isError` for failures). */
   readonly mutate: (variables: TVariables) => void
-  /** Run the mutation and return the promise (rejects on failure) — for `await`. */
+  /** Run the mutation and return the promise (rejects on failure) - for `await`. */
   readonly mutateAsync: (variables: TVariables) => Promise<TData>
   /** Reset back to idle. */
   readonly reset: () => void
@@ -210,7 +210,7 @@ export function useMutation<TData, TVariables = void>(
   }
 }
 
-/** Options for {@link useInfiniteQuery} — the engine's {@link InfiniteQueryOptions} plus `enabled`. */
+/** Options for {@link useInfiniteQuery} - the engine's {@link InfiniteQueryOptions} plus `enabled`. */
 export interface UseInfiniteQueryOptions<T, P> extends InfiniteQueryOptions<T, P> {
   readonly enabled?: boolean
 }
@@ -258,7 +258,7 @@ export function useInfiniteQuery<T, P>(
 }
 
 /**
- * Seed the context's {@link QueryClient} from a server {@link dehydrate} snapshot — the SSR data bridge.
+ * Seed the context's {@link QueryClient} from a server {@link dehydrate} snapshot - the SSR data bridge.
  * Wrap the app (inside `QueryClientProvider`) so server-prefetched queries are in the cache before the
  * first client render, avoiding a loading flash. Hydration runs during render (idempotent, fresher-wins),
  * so the data is available synchronously to child `useQuery`s.

package/src/react-dom-server.ts

@@ -1,23 +1,23 @@
 /**
- * Resolve `react-dom/server` so it shares ONE React core with the route components — the fix for the
+ * Resolve `react-dom/server` so it shares ONE React core with the route components - the fix for the
  * dual-React SSR crash (`resolveDispatcher().useState` is null / "Invalid hook call: mismatching versions
  * of React and the renderer").
  *
  * WHY this exists: under Bun **runtime** SSR (`nifra dev`, `nifra start`, `nifra_render`, all in-process),
  * a static `import "react-dom/server"` in this adapter is resolved by Bun from THIS package's own
- * (symlinked) node_modules — which can be a DIFFERENT physical `react` than the one the consumer app's
+ * (symlinked) node_modules - which can be a DIFFERENT physical `react` than the one the consumer app's
  * route components import. Two React cores → two hook dispatchers → the renderer's dispatcher is the wrong
  * (or null) one → the crash. Resolving `react-dom/server` from the consumer **app root** instead makes
  * react-dom pull the app's `react` transitively, matching the components' `react`: a single core, a single
- * dispatcher, no crash. (Empirically verified against a two-copy install fixture — see
+ * dispatcher, no crash. (Empirically verified against a two-copy install fixture - see
  * test/dual-react.test.ts.)
  *
- * Guarding precisely so the BUILT path is untouched: a bundle is detected two ways — `Bun.resolveSync` is
+ * Guarding precisely so the BUILT path is untouched: a bundle is detected two ways - `Bun.resolveSync` is
  * unavailable (Node / Deno / Cloudflare / Vercel), OR `buildServer` tagged the output with
  * `process.env.NIFRA_SSR_BUNDLED` (a `target:"bun"` bundle DOES keep `Bun.resolveSync` under the Bun
  * runtime, so the resolver test alone can't see it). In either case the build already bundled+deduped a
  * single `react-dom` (buildServer's `reactDedupePlugin` pins `react`), so the static `import` is correct.
- * Re-rooting a bundle would instead re-import a SECOND react-dom from disk — a second React core whose hook
+ * Re-rooting a bundle would instead re-import a SECOND react-dom from disk - a second React core whose hook
  * dispatcher is null for the bundled components → the `…H.useRef of null` SSR crash. The app-root re-root
  * therefore runs ONLY under an UNBUNDLED Bun runtime (nifra dev/start, nifra_render), where the duplication
  * can occur, `Bun.resolveSync` exists, and no bundle marker is present.
@@ -26,7 +26,7 @@
 import type { ReactNode } from "react"
 
 /** The slice of `react-dom/server` this adapter uses. Typed locally so the dynamic import (which Bun
- * resolves to an absolute path string) stays strict — no `any` crosses the boundary. */
+ * resolves to an absolute path string) stays strict - no `any` crosses the boundary. */
 export interface ReactDomServer {
   renderToString(node: ReactNode): string
   renderToReadableStream(node: ReactNode): Promise<ReadableStream<Uint8Array>>
@@ -51,7 +51,7 @@ function runtimeRealpath(path: string): string {
 
 // `globalThis.Bun` isn't in the ambient lib types; narrow exactly the one method we need so we never
 // reach for `any`. `resolveSync(specifier, from)` returns the absolute path the specifier resolves to
-// when required from `from` — Bun's runtime resolver, the only lever that re-roots a BARE specifier
+// when required from `from` - Bun's runtime resolver, the only lever that re-roots a BARE specifier
 // (a runtime `Bun.plugin` onResolve does NOT fire for bare specifiers like `react-dom/server`, verified).
 interface BunResolver {
   resolveSync(specifier: string, from: string): string
@@ -150,7 +150,7 @@ export async function loadReactDomServer(
     // Bun runtime SSR: re-root to the app's copy so react-dom shares the components' React. `react-dom`
     // is a PEER dependency of this adapter, so a correct install puts it at the app root and this
     // resolves. If it somehow doesn't (an unusual nested layout), fall through to the bundled specifier
-    // rather than crashing — degraded (possible duplicate) but never a hard failure.
+    // rather than crashing - degraded (possible duplicate) but never a hard failure.
     try {
       const resolved = resolve("react-dom/server", appRoot())
       // Before returning the module, verify the react-dom we just re-rooted shares the components' React.
@@ -173,7 +173,7 @@ export async function loadReactDomServer(
 }
 
 /**
- * The resolver `loadReactDomServer` uses by default, or `undefined` when re-rooting must NOT happen — a
+ * The resolver `loadReactDomServer` uses by default, or `undefined` when re-rooting must NOT happen - a
  * non-Bun host (no `Bun.resolveSync`; the static import is the only path) OR a BUNDLED SSR output.
  * `buildServer` defines `process.env.NIFRA_SSR_BUNDLED` to `"1"` in every bundle, where react-dom is
  * already inlined + deduped to the components' React (reactDedupePlugin); re-rooting there would re-import

package/src/router.ts

@@ -1,16 +1,28 @@
 /**
- * `@nifrajs/web-react/router` — React routing bindings over the agnostic `@nifrajs/web` router:
+ * `@nifrajs/web-react/router` - React routing bindings over the agnostic `@nifrajs/web` router:
  * `<Link>`/`<NavLink>`, `useNavigate`, `useParams`, `useLocation`, `useSearchParams`, and `<Navigate>`.
  *
  * These read the current route from a {@link RouterContext} that `compose` provides on BOTH the SSR
  * render and the client mount (seeded from the request match / router state respectively), so the read
  * hooks (`useParams`/`useLocation`/`useSearchParams`) are SSR-correct and hydrate with no mismatch.
  * Navigation goes through `@nifrajs/web`'s DOM-free navigate bridge (`getBrowserNavigate`, populated by
- * `installHistory`) — so this module imports only `react` (never `react-dom/*`), and a route component
+ * `installHistory`) - so this module imports only `react` (never `react-dom/*`), and a route component
  * can use these on the server and the client without dragging a DOM build into the wrong bundle. No JSX
  * (the package builds with plain `tsc`), so everything is `createElement`.
  */
-import { getBrowserNavigate, type NavigateOptions } from "@nifrajs/web"
+
+import type { InferOutput, StandardSchemaV1 } from "@nifrajs/core/server"
+import {
+  type Blocker,
+  type BlockerFunction,
+  getBrowserNavigate,
+  IDLE_BLOCKER,
+  type NavigateFunction,
+  type NavigateOptions,
+  type NavigateTargetInput,
+  registerBlocker,
+  resolveNavigate,
+} from "@nifrajs/web"
 import {
   type AnchorHTMLAttributes,
   type CSSProperties,
@@ -23,15 +35,23 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
+  useState,
 } from "react"
 
+export type { Blocker, BlockerFunction, BlockerState, NavigateFunction } from "@nifrajs/web"
+
 /** The current route the routing hooks read. Provided by `compose` on SSR + client mount alike. */
 export interface RouterContextValue {
   /** The matched route's decoded path params (`/users/:id` → `{ id: "7" }`). */
   readonly params: Readonly<Record<string, string>>
-  /** The current URL's `pathname + search` (no hash — the router never carries one). */
+  /** The current URL's `pathname + search` (no hash - the router never carries one). */
   readonly path: string
-  /** True while a client navigation (or revalidation) is in flight — the current route stays mounted
+  /** The route's typed, validated search params (the loader's `ctx.search`), derived from the URL via
+   * the shared `searchOf` on SSR + client alike, read by {@link useSearch}. `{}` when the route
+   * declares no `searchSchema` (then it is the raw parsed query) or outside a nifra route tree. */
+  readonly search: Record<string, unknown>
+  /** True while a client navigation (or revalidation) is in flight - the current route stays mounted
    * until the new one is ready. Always `false` on SSR (loaders block before render). Drives loading UI
    * via {@link useNavigation}. */
   readonly pending: boolean
@@ -40,14 +60,17 @@ export interface RouterContextValue {
   readonly pendingPath?: string | undefined
 }
 
-// Frozen empty params so the default context value has a stable reference (no needless re-renders).
+// Frozen empty params/search so the default context value has a stable reference (no needless re-renders).
 const EMPTY_PARAMS: Readonly<Record<string, string>> = Object.freeze({})
+const EMPTY_SEARCH: Readonly<Record<string, unknown>> = Object.freeze({})
 
-/** Router context. The default ({} params, "" path) is what a component sees when rendered outside a
- * nifra route tree — the hooks stay defined (no throw) so a stray `useParams` degrades gracefully. */
+/** Router context. The default ({} params, "" path, {} search) is what a component sees when rendered
+ * outside a nifra route tree (the hooks stay defined, no throw, so a stray `useParams` degrades
+ * gracefully). */
 export const RouterContext = createContext<RouterContextValue>({
   params: EMPTY_PARAMS,
   path: "",
+  search: EMPTY_SEARCH,
   pending: false,
 })
 
@@ -61,7 +84,7 @@ function splitPath(path: string): { readonly pathname: string; readonly search:
 }
 
 /**
- * The matched route's decoded path params — `/users/:id` on `/users/7` → `{ id: "7" }`. SSR-correct:
+ * The matched route's decoded path params - `/users/:id` on `/users/7` → `{ id: "7" }`. SSR-correct:
  * `compose` provides the same value server-side (from the request match) and client-side (from router
  * state), so a param rendered into markup doesn't flash on hydration.
  */
@@ -71,7 +94,30 @@ export function useParams<
   return useContext(RouterContext).params as Readonly<T>
 }
 
-/** The parsed current location. `hash` is always `""` — the fragment is client-only and never reaches
+/**
+ * The route's typed, validated search params: the SAME value the loader received as `ctx.search`.
+ * SSR-correct: `compose` provides it from `searchOf(searchSchema, url.search)` server-side and from the
+ * identical derivation on the client mount, so a value rendered from it doesn't flash on hydration.
+ * Hostile input already failed closed to the schema's defaults at match time, so a component never
+ * parses `window.location.search` or guards against a bad query.
+ *
+ * Pass the route's `searchSchema` as the type argument to get its output type; bare, it's the raw parsed
+ * query (`Record<string, unknown>`), which is also what a route without a `searchSchema` yields.
+ *
+ * ```tsx
+ * export const searchSchema = v.object({ page: v.optional(v.fallback(v.number(), 1), 1) })
+ * const { page } = useSearch<typeof searchSchema>() // page: number
+ * ```
+ */
+export function useSearch<
+  Schema extends StandardSchemaV1 | undefined = undefined,
+>(): Schema extends StandardSchemaV1 ? InferOutput<Schema> : Record<string, unknown> {
+  return useContext(RouterContext).search as Schema extends StandardSchemaV1
+    ? InferOutput<Schema>
+    : Record<string, unknown>
+}
+
+/** The parsed current location. `hash` is always `""` - the fragment is client-only and never reaches
  * the router state / server, so exposing a live hash would hydration-mismatch; read `window.location.hash`
  * directly (in an effect) if you truly need it. */
 export interface Location {
@@ -130,18 +176,62 @@ export function usePending(): boolean {
   return useContext(RouterContext).pending
 }
 
-/** A programmatic navigate: a string path (push, or replace via `{ replace: true }`) or a history delta
- * (`-1`/`1`). A no-op on the server / before hydration (a render-time navigate isn't valid — use
- * {@link Navigate}, which navigates in an effect). */
-export type NavigateFunction = (to: string | number, options?: NavigateOptions) => void
-
-/** Get the {@link NavigateFunction}. Stable across renders; resolves the browser navigate at call time
- * (so it works as soon as `installHistory` has run, and no-ops before then / on the server). */
+/** Get the {@link NavigateFunction} (a string path, a history delta, or a typed `{ to, search }` object;
+ * a render-time navigate isn't valid - use {@link Navigate}, which navigates in an effect). Stable across
+ * renders; resolves the browser navigate at call time (so it works as soon as `installHistory` has run,
+ * and no-ops before then / on the server). */
 export function useNavigate(): NavigateFunction {
-  return useCallback((to, options) => {
+  return useCallback((to: string | number | NavigateTargetInput, options?: NavigateOptions) => {
     const navigate = getBrowserNavigate()
-    if (navigate !== undefined) navigate(to, options)
-  }, [])
+    if (navigate === undefined) return
+    const resolved = resolveNavigate(to, options)
+    navigate(resolved.to, resolved.options)
+  }, []) as NavigateFunction
+}
+
+/**
+ * Guard navigation away from a page with unsaved work, confirming with your OWN async UI. Mirrors
+ * react-router's `useBlocker`: pass a boolean (`useBlocker(isDirty)`) or a predicate
+ * `({ currentLocation, nextLocation }) => boolean`, and get back a {@link Blocker}. When a navigation
+ * (a `<Link>`/anchor click, `useNavigate`, or a browser back/forward) is intercepted, `blocker.state`
+ * becomes `"blocked"` and `proceed`/`reset` go live - render a dialog and call `proceed()` to continue
+ * or `reset()` to stay put. It also arms the browser's native "Leave site?" prompt on tab close / reload.
+ * Idle (never blocks, `proceed`/`reset` are `undefined`) on the server and before hydration, so it's
+ * SSR-safe and hydration-stable.
+ *
+ * ```tsx
+ * const blocker = useBlocker(form.isDirty)
+ * return (
+ *   <>
+ *     <MyForm />
+ *     {blocker.state === "blocked" && (
+ *       <ConfirmDialog
+ *         onCancel={blocker.reset}
+ *         onConfirm={blocker.proceed}
+ *         message="Discard unsaved changes?"
+ *       />
+ *     )}
+ *   </>
+ * )
+ * ```
+ */
+export function useBlocker(shouldBlock: boolean | BlockerFunction): Blocker {
+  const [blocker, setBlocker] = useState<Blocker>(IDLE_BLOCKER)
+  // Track the latest predicate in a ref (updated every render) so the single registration always sees
+  // current component state (the dirty flag) WITHOUT re-registering - re-registering mid-prompt drops it.
+  const shouldBlockRef = useRef(shouldBlock)
+  shouldBlockRef.current = shouldBlock
+  // Register once on mount; the returned unregister is the effect cleanup. A boolean reads as itself, a
+  // function is called. A no-op before `installHistory` has run (blocker stays idle → native navigation).
+  useEffect(
+    () =>
+      registerBlocker((args) => {
+        const current = shouldBlockRef.current
+        return typeof current === "function" ? current(args) : current
+      }, setBlocker),
+    [],
+  )
+  return blocker
 }
 
 /** The value forms `setSearchParams` accepts. */
@@ -185,7 +275,7 @@ export function useSearchParams(): readonly [URLSearchParams, SetSearchParams] {
   return [searchParams, setSearchParams] as const
 }
 
-/** A left-click with no modifier and no new-tab target — the only click a client router should
+/** A left-click with no modifier and no new-tab target - the only click a client router should
  * intercept (Cmd/Ctrl/Shift/Alt or a `_blank` target means the user wants native behavior). */
 function isPlainLeftClick(event: MouseEvent, target: string | undefined): boolean {
   if (event.button !== 0) return false
@@ -205,7 +295,7 @@ export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>,
  * A client-navigating anchor. Renders a real `<a href={to}>` (so it's a working link before hydration
  * and for right-click / open-in-new-tab), and on a plain left-click navigates through the router
  * instead of a full reload. Calling `navigate` + `preventDefault` here means `installHistory`'s
- * document-level click handler sees `defaultPrevented` and stands down — exactly one navigation.
+ * document-level click handler sees `defaultPrevented` and stands down - exactly one navigation.
  */
 export const Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
   { to, replace, onClick, target, ...rest },
@@ -232,7 +322,7 @@ export interface NavLinkRenderProps {
   readonly isPending: boolean
 }
 
-/** {@link NavLink} props — like {@link LinkProps}, but `className`/`style`/`children` may be functions
+/** {@link NavLink} props - like {@link LinkProps}, but `className`/`style`/`children` may be functions
  * of the active state, and `end`/`caseSensitive` tune matching. */
 export interface NavLinkProps extends Omit<LinkProps, "className" | "style" | "children"> {
   /** Match the full path exactly instead of as a prefix (use for `to="/"` so it isn't always active). */
@@ -309,7 +399,7 @@ export interface NavigateProps {
 }
 
 /**
- * Declaratively navigate on mount — the component analogue of `useNavigate` (e.g. a guard that renders
+ * Declaratively navigate on mount - the component analogue of `useNavigate` (e.g. a guard that renders
  * `<Navigate to="/login" replace />`). Navigates in an effect, so it's a safe no-op during SSR (renders
  * `null`); the redirect happens once on the client after hydration.
  */