@nifrajs/web-preact 2.2.0 → 2.3.0

package/dist/router.js

@@ -0,0 +1,64 @@
+import { getBrowserNavigate, IDLE_BLOCKER, registerBlocker, resolveNavigate, } from "@nifrajs/web";
+/**
+ * `@nifrajs/web-preact/router` - Preact routing bindings over the agnostic `@nifrajs/web` history layer:
+ * `useNavigate` (programmatic navigation), `useBlocker` (the unsaved-changes guard), and `useSearch`
+ * (the route's typed, validated search). Navigation goes through `@nifrajs/web`'s DOM-free bridges
+ * (`getBrowserNavigate` / `registerBlocker`, populated by `installHistory`); `useSearch` reads the value
+ * `compose` provides on SSR + client mount alike. Client-safe (no `preact-render-to-string`). No JSX.
+ */
+import { createContext } from "preact";
+import { useCallback, useContext, useEffect, useRef, useState } from "preact/compat";
+// Frozen empty search so the default context value has a stable reference.
+const EMPTY_SEARCH = Object.freeze({});
+/** The current route's validated search, provided by `compose` on SSR + client mount alike (derived from
+ * the URL via the shared `searchOfChain`). `{}` outside a nifra route tree. Read via {@link useSearch}. */
+export const SearchContext = createContext(EMPTY_SEARCH);
+/**
+ * The route's typed, validated search params - the SAME value the loader received as `ctx.search`.
+ * SSR-correct: `compose` provides it from the URL 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. Pass the route's `searchSchema` as the type argument to
+ * get its output type; bare, it's the raw parsed query (`Record<string, unknown>`).
+ *
+ * ```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() {
+    return useContext(SearchContext);
+}
+/** Get the {@link NavigateFunction} (a string path, a history delta, or a typed `{ to, search }` object).
+ * 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() {
+    return useCallback((to, options) => {
+        const navigate = getBrowserNavigate();
+        if (navigate === undefined)
+            return;
+        const resolved = resolveNavigate(to, options);
+        navigate(resolved.to, resolved.options);
+    }, []);
+}
+/**
+ * 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
+ * (an 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) on the server and before hydration.
+ */
+export function useBlocker(shouldBlock) {
+    const [blocker, setBlocker] = useState(IDLE_BLOCKER);
+    // Track the latest predicate in a ref (updated every render) so the single registration always sees
+    // current component state without re-registering (which would drop an open prompt).
+    const shouldBlockRef = useRef(shouldBlock);
+    shouldBlockRef.current = shouldBlock;
+    useEffect(() => registerBlocker((args) => {
+        const current = shouldBlockRef.current;
+        return typeof current === "function" ? current(args) : current;
+    }, setBlocker), []);
+    return blocker;
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,kBAAkB,EAClB,YAAY,EAIZ,eAAe,EACf,eAAe,GAChB,MAAM,cAAc,CAAA;AACrB;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAIpF,2EAA2E;AAC3E,MAAM,YAAY,GAAsC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AAEzE;2GAC2G;AAC3G,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAA0B,YAAY,CAAC,CAAA;AAEjF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS;IAGvB,OAAO,UAAU,CAAC,aAAa,CAEJ,CAAA;AAC7B,CAAC;AAED;;sEAEsE;AACtE,MAAM,UAAU,WAAW;IACzB,OAAO,WAAW,CAAC,CAAC,EAAyC,EAAE,OAAyB,EAAE,EAAE;QAC1F,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAA;QACrC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAM;QAClC,MAAM,QAAQ,GAAG,eAAe,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;QAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IACzC,CAAC,EAAE,EAAE,CAAqB,CAAA;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,WAAsC;IAC/D,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAU,YAAY,CAAC,CAAA;IAC7D,oGAAoG;IACpG,oFAAoF;IACpF,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC,CAAA;IAC1C,cAAc,CAAC,OAAO,GAAG,WAAW,CAAA;IACpC,SAAS,CACP,GAAG,EAAE,CACH,eAAe,CAAC,CAAC,IAAI,EAAE,EAAE;QACvB,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAA;QACtC,OAAO,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;IAChE,CAAC,EAAE,UAAU,CAAC,EAChB,EAAE,CACH,CAAA;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/web-preact",
-  "version": "2.2.0",
-  "description": "Preact render adapter for @nifrajs/web — streaming SSR + hydration (no build plugin).",
+  "version": "2.3.0",
+  "description": "Preact render adapter for @nifrajs/web - streaming SSR + hydration (no build plugin).",
   "keywords": [
     "bun",
     "typescript",
@@ -36,6 +36,11 @@
       "types": "./dist/fetcher.d.ts",
       "default": "./dist/fetcher.js"
     },
+    "./router": {
+      "bun": "./src/router.ts",
+      "types": "./dist/router.d.ts",
+      "default": "./dist/router.js"
+    },
     "./query": {
       "bun": "./src/query.ts",
       "types": "./dist/query.d.ts",
@@ -55,6 +60,11 @@
       "bun": "./src/content.ts",
       "types": "./dist/content.d.ts",
       "default": "./dist/content.js"
+    },
+    "./fn": {
+      "bun": "./src/fn.ts",
+      "types": "./dist/fn.d.ts",
+      "default": "./dist/fn.js"
     }
   },
   "files": [
@@ -70,9 +80,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/i18n": "2.2.0",
-    "@nifrajs/image": "2.2.0",
-    "@nifrajs/web": "2.2.0",
+    "@nifrajs/core": "2.3.0",
+    "@nifrajs/i18n": "2.3.0",
+    "@nifrajs/image": "2.3.0",
+    "@nifrajs/web": "2.3.0",
     "preact-render-to-string": "^6.5.0"
   },
   "peerDependencies": {

package/src/await.ts

@@ -1,7 +1,7 @@
 import type { Deferred } from "@nifrajs/web"
 import type { ComponentChildren, VNode } from "preact"
 /**
- * `@nifrajs/web-preact/await` — the `<Await>` primitive for deferred loader data (`defer()`). Isomorphic
+ * `@nifrajs/web-preact/await` - the `<Await>` primitive for deferred loader data (`defer()`). Isomorphic
  * and imports only `preact`/`preact/compat` + a type from `@nifrajs/web` (never the server renderer), so
  * route components can use it without dragging server code into the client bundle. No JSX (the package
  * builds with plain `tsc`).

package/src/client.ts

@@ -1,6 +1,6 @@
-import type { MountRouterOptions, RenderProps } from "@nifrajs/web"
+import { type MountRouterOptions, type RenderProps, searchOfChain } from "@nifrajs/web"
 /**
- * @nifrajs/web-preact/client — Preact client runtime. `hydrate` hydrates a single SSR'd route;
+ * @nifrajs/web-preact/client - Preact client runtime. `hydrate` hydrates a single SSR'd route;
  * `mountRouter` hydrates a stateful Router that subscribes to the agnostic store (via
  * `useSyncExternalStore` from preact/compat) and re-renders the matched chain on every client
  * navigation (no full reload). Kept in its own entry so server code (preact-render-to-string) stays
@@ -11,7 +11,7 @@ import { useSyncExternalStore } from "preact/compat"
 import { compose } from "./compose.ts"
 import { setMountedRouter } from "./fetcher.ts"
 
-// The `_error` boundary chain element — defined in its own (DOM-free) module, re-exported here so
+// The `_error` boundary chain element - defined in its own (DOM-free) module, re-exported here so
 // nifra's client codegen resolves it from `@nifrajs/web-preact/client` alongside `mountRouter`.
 export { errorBoundary } from "./error.ts"
 
@@ -22,20 +22,25 @@ export function hydrate(chain: readonly unknown[], props: RenderProps, container
 
 /**
  * Hydrate a stateful Preact Router. `useSyncExternalStore` (preact/compat) subscribes to the
- * agnostic store and re-renders the matched layout chain on each store change — so client
+ * agnostic store and re-renders the matched layout chain on each store change - so client
  * navigations swap routes without a full reload. Preact's compat `useSyncExternalStore` is 2-arg
  * (no `getServerSnapshot`); `router.snapshot` is deterministic, so hydration matches the SSR markup.
  */
 export function mountRouter(options: MountRouterOptions): void {
-  const { router, routes, container } = options
+  const { router, routes, searchSchemas, container } = options
   setMountedRouter(router) // expose it to useFetcher/useFetchers (same page, client-only)
   const Router: FunctionComponent = () => {
     const state = useSyncExternalStore(router.subscribe, router.snapshot)
+    // Derive this route's typed `search` from the URL + the route's schema chain (the SAME `searchOfChain`
+    // the server ran), so `useSearch` reads an identical value and hydrates with no drift.
+    const q = state.path.indexOf("?")
+    const rawSearch = q === -1 ? "" : state.path.slice(q)
     return compose(routes[state.routeId] ?? [], {
       data: state.data,
       actionData: state.actionData,
       pending: state.pending,
-      // The in-flight submission (for optimistic UI) — spread only when present.
+      search: searchOfChain(searchSchemas?.[state.routeId] ?? [], rawSearch),
+      // The in-flight submission (for optimistic UI) - spread only when present.
       ...(state.submission ? { submission: state.submission } : {}),
     })
   }

package/src/compose.ts

@@ -1,11 +1,26 @@
 import type { RenderProps } from "@nifrajs/web"
-import { type ComponentType, h, type VNode } from "preact"
+import { type ComponentChildren, type ComponentType, createElement, h, type VNode } from "preact"
+import { SearchContext } from "./router.ts"
+
+// Frozen empty search so a render with no search context has a stable provider value.
+const EMPTY_SEARCH: Readonly<Record<string, unknown>> = Object.freeze({})
+
+// Preact's `createElement` overloads drop a typed `Context.Provider`'s required `value` under
+// exactOptionalPropertyTypes (same issue i18n's provider hits); invoke it through a precisely-typed
+// factory that states the real `{ value }` + children contract rather than scatter `any`.
+const createSearchProvider = createElement as (
+  type: typeof SearchContext.Provider,
+  props: { value: Record<string, unknown> },
+  children?: ComponentChildren,
+) => VNode
 
 /**
  * Fold a layout chain (outermost layout → page) into a single Preact tree: the page (innermost)
  * receives `props` (the loader data); each layout wraps the child via its `children` (Preact passes
- * the 3rd `h` arg as `props.children`). Shared by the server adapter (renderToReadableStream) and
- * the client (hydrate / mountRouter) — the Preact analogue of the React adapter's `compose`.
+ * the 3rd `h` arg as `props.children`). The whole tree is wrapped in a {@link SearchContext} provider
+ * carrying the validated `search` (threaded through `RenderProps` identically on SSR + client), so
+ * `useSearch` reads the same value on both sides - no hydration mismatch. Shared by the server adapter
+ * (renderToReadableStream) and the client (hydrate / mountRouter) - the Preact analogue of React's `compose`.
  */
 export function compose(chain: readonly unknown[], props: RenderProps): VNode {
   const last = chain.length - 1
@@ -13,10 +28,10 @@ export function compose(chain: readonly unknown[], props: RenderProps): VNode {
   // loader props (typed via ComponentType<RenderProps>), then we widen `h`'s VNode<Attributes &
   // RenderProps> to the uniform VNode the fold accumulates into. Preact's VNode<P> is invariant in P
   // under exactOptionalPropertyTypes, so the widen needs the explicit `as VNode` (a comparability
-  // cast — Attributes & RenderProps is assignable to {}, so this is not an unsafe coercion).
+  // cast - Attributes & RenderProps is assignable to {}, so this is not an unsafe coercion).
   let node: VNode = h(chain[last] as ComponentType<RenderProps>, props) as VNode
   for (let i = last - 1; i >= 0; i--) {
-    // children passed as the 3rd arg — Preact's canonical form (mirrors the React adapter).
+    // children passed as the 3rd arg - Preact's canonical form (mirrors the React adapter).
     // 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.
@@ -26,5 +41,5 @@ export function compose(chain: readonly unknown[], props: RenderProps): VNode {
       node,
     ) as VNode
   }
-  return node
+  return createSearchProvider(SearchContext.Provider, { value: props.search ?? EMPTY_SEARCH }, node)
 }

package/src/content.ts

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

package/src/error.ts

@@ -1,5 +1,5 @@
 /**
- * `errorBoundary` — the Preact error-boundary chain element for nifra's `_error.tsx`. Its own module
+ * `errorBoundary` - the Preact error-boundary chain element for nifra's `_error.tsx`. Its own module
  * (imports only `preact`) so it's unit-testable off the DOM and the client codegen can import it from
  * `@nifrajs/web-preact/client` (which re-exports it).
  */
@@ -9,7 +9,7 @@ import { Component, type ComponentChildren, createElement, type FunctionComponen
  * 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?: ComponentChildren }
@@ -25,7 +25,7 @@ export function errorBoundary(fallback: unknown): unknown {
     override render(): ComponentChildren {
       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,16 +1,16 @@
 import type { ClientRouter, Fetcher, FetcherState } from "@nifrajs/web"
 /**
- * `@nifrajs/web-preact/fetcher` — Preact bindings for concurrent fetchers. `useFetcher(key)` subscribes a
+ * `@nifrajs/web-preact/fetcher` - Preact bindings for concurrent fetchers. `useFetcher(key)` subscribes a
  * component to an independent {@link Fetcher} (via `useSyncExternalStore` from preact/compat) and
  * returns its reactive state plus `load`/`submit`; `useFetchers()` subscribes to the whole live
  * collection. Imports only `preact/compat` + `@nifrajs/web` types, so route components can use it on the
  * server *and* client. 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). Preact's compat `useSyncExternalStore` is 2-arg (no `getServerSnapshot`);
  * with no router the `getSnapshot` already returns idle, so the first client render after `mountRouter`
- * matches the SSR markup — no hydration mismatch.
+ * matches the SSR markup - no hydration mismatch.
  */
 import { useSyncExternalStore } from "preact/compat"
 
@@ -18,7 +18,7 @@ import { useSyncExternalStore } from "preact/compat"
 // 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
 }
@@ -55,7 +55,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,40 @@
+/**
+ * `@nifrajs/web-preact/fn` - Preact 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 "preact/compat"
+
+/** 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.
+ *
+ * Preact's compat `useSyncExternalStore` takes two arguments (no server snapshot); the store's idle
+ * state is shared by reference anyway, so a server render and the first client render agree.
+ */
+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)
+  return { ...state, call: store.call, reset: store.reset }
+}

package/src/i18n.ts

@@ -1,9 +1,9 @@
 /**
- * `@nifrajs/web-preact/i18n` — Preact bindings for `@nifrajs/i18n`. `<I18nProvider locale messages>` builds a
+ * `@nifrajs/web-preact/i18n` - Preact 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). Uses `preact` +
- * `preact/hooks` — no JSX.
+ * `preact/hooks` - no JSX.
  */
 import { createFormatter, type Formatter, type Messages } from "@nifrajs/i18n"
 import { type ComponentChildren, createContext, createElement, type VNode } from "preact"
@@ -12,7 +12,7 @@ import { useContext, useMemo } from "preact/hooks"
 const I18nContext = createContext<Formatter | null>(null)
 
 // Preact's `createElement` overloads don't reconcile a typed `Context.Provider` (required `value`)
-// under `exactOptionalPropertyTypes` — overload resolution drops `value` and infers the props as `{}`.
+// under `exactOptionalPropertyTypes` - overload resolution drops `value` and infers the props as `{}`.
 // The call is correct at runtime (proven by the tests), so invoke it through a precisely-typed element
 // factory that states the real contract (`{ value }` + children), rather than scatter `any`.
 const createProvider = createElement as (

package/src/image.ts

@@ -1,14 +1,14 @@
 /**
- * `@nifrajs/web-preact/image` — a CLS-safe responsive Preact `<Image>`. A thin wrapper over `resolveImage`
+ * `@nifrajs/web-preact/image` - a CLS-safe responsive Preact `<Image>`. A thin wrapper over `resolveImage`
  * from `@nifrajs/image`: it computes the responsive `<img>` attributes (`src`/`srcset`/`sizes`/`width`/
- * `height`/`loading`/`decoding`/`fetchpriority` — Preact uses lowercase HTML attribute names, so it
+ * `height`/`loading`/`decoding`/`fetchpriority` - Preact uses lowercase HTML attribute names, so it
  * spreads `toHtmlAttrs`) and forwards any extra DOM props (`class`, `style`, `id`, `data-*`, handlers).
  * Resizing is delegated to the `loader` (an image CDN); nifra bundles no codec. No JSX (`h`).
  */
 import { type ImageLoader, type ImageProps, resolveImage, toHtmlAttrs } from "@nifrajs/image"
 import { h, type JSX, type VNode } from "preact"
 
-/** 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<JSX.IntrinsicElements["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
 }
 

package/src/index.ts

@@ -1,6 +1,6 @@
 import type { RenderAdapter } from "@nifrajs/web"
 /**
- * @nifrajs/web-preact — the Preact render adapter for @nifrajs/web (server side). Streaming SSR via
+ * @nifrajs/web-preact - the Preact render adapter for @nifrajs/web (server side). Streaming SSR via
  * `renderToReadableStream` from `preact-render-to-string/stream` (a Web `ReadableStream<Uint8Array>`,
  * the seam's native shape); the layout-chain fold is in `./compose`. Client hydration lives in
  * `@nifrajs/web-preact/client`. Preact uses `h()` render functions, so no JSX/build plugin is needed
@@ -9,13 +9,13 @@ import type { RenderAdapter } from "@nifrajs/web"
 import { compose } from "./compose.ts"
 import { preactRenderToStream, preactRenderToString } from "./preact-render.ts"
 
-/** The Preact server render adapter — pass to @nifrajs/web's `renderPage`. */
+/** The Preact server render adapter - pass to @nifrajs/web's `renderPage`. */
 export const preactAdapter: RenderAdapter = {
   // Synchronous one-pass render for non-deferred pages (renderPage's buffered fast path). The sync
   // `renderToString` emits the same markup as the stream renderer without the chunking machinery.
   //
   // Async because the renderer module is resolved lazily (from the consumer app's node_modules under Bun
-  // runtime SSR — see ./preact-render). `RenderAdapter.renderToString` permits a Promise; renderPage awaits.
+  // runtime SSR - see ./preact-render). `RenderAdapter.renderToString` permits a Promise; renderPage awaits.
   async renderToString(chain, props) {
     const { renderToString } = await preactRenderToString()
     return renderToString(compose(chain, props))
@@ -27,7 +27,7 @@ export const preactAdapter: RenderAdapter = {
     return renderToReadableStream(compose(chain, props))
   },
   // Preact reconciles against the existing DOM on hydrate (like React), so there's no per-document
-  // bootstrap script — the seam allows the empty string (contrast Solid's generateHydrationScript).
+  // bootstrap script - the seam allows the empty string (contrast Solid's generateHydrationScript).
   hydrationHead() {
     return ""
   },

package/src/preact-render.ts

@@ -1,17 +1,17 @@
 /**
  * Resolve `preact-render-to-string` (+ its `/stream` subpath) so the renderer shares ONE `preact`
- * module-global with the route components — the fix for the dual-Preact SSR crash (`undefined is not an
+ * module-global with the route components - the fix for the dual-Preact SSR crash (`undefined is not an
  * object (evaluating '…__H')` / silently-empty hook output).
  *
  * WHY this exists: `preact-render-to-string` imports `options` and `h` from `preact` and mutates the
  * shared `options` hooks; `preact/hooks` registers its render hook on the SAME `options` global. Under Bun
  * **runtime** SSR (`nifra dev`, `nifra start`, `nifra_render`, all in-process), a static
  * `import "preact-render-to-string"` in this adapter is resolved from THIS package's own (symlinked)
- * node_modules — which can be a DIFFERENT physical `preact` than the consumer app's components import. Two
+ * node_modules - which can be a DIFFERENT physical `preact` than the consumer app's components import. Two
  * `preact` copies → two `options` globals → the renderer walks one while `preact/hooks` wrote the other →
  * the vnode never gets its hook-state list → the crash. Resolving the renderer from the consumer **app
  * root** makes it pull the app's `preact` transitively, matching the components: one `options`, one core,
- * no crash. (Empirically verified against a two-copy install fixture — see test/dual-preact.test.ts.)
+ * no crash. (Empirically verified against a two-copy install fixture - see test/dual-preact.test.ts.)
  *
  * Guarding precisely so the PRODUCTION/BUILT path is untouched: when `Bun.resolveSync` is unavailable
  * (Node / Deno / Cloudflare / Vercel / any bundled output), the build has already bundled a single
@@ -31,7 +31,7 @@ export interface PreactRenderToStream {
 }
 
 // Narrow only the one Bun method we need (it isn't in the ambient lib types) so no `any` is introduced.
-// `resolveSync(specifier, from)` is the only lever that re-roots a BARE specifier — a runtime
+// `resolveSync(specifier, from)` is the only lever that re-roots a BARE specifier - a runtime
 // `Bun.plugin` onResolve does NOT fire for bare specifiers like `preact-render-to-string` (verified).
 interface BunResolver {
   resolveSync(specifier: string, from: string): string

package/src/query.ts

@@ -5,12 +5,12 @@ import {
   type QueryState,
 } from "@nifrajs/web"
 /**
- * `@nifrajs/web-preact/query` — Preact bindings for the keyed query-cache. `useQuery(key, fn)` subscribes a
+ * `@nifrajs/web-preact/query` - Preact bindings for the keyed query-cache. `useQuery(key, fn)` subscribes a
  * component to a query (via `useSyncExternalStore` from preact/compat) and fetches on mount / key change;
  * `useQueryClient` exposes `invalidateQueries` for after a mutation. Imports only `preact/compat` +
  * `preact/hooks` + `@nifrajs/web`, so route components use it on the server *and* client. No JSX.
  *
- * The query client is created lazily **client-side only** (the `typeof window` guard) — on the server
+ * The query client is created lazily **client-side only** (the `typeof window` guard) - on the server
  * there is none, so `useQuery` renders the idle/pending state (queries are client-first; loaders are
  * the SSR data source). The first client render uses the same idle snapshot, so no mismatch.
  */
@@ -45,7 +45,7 @@ const noopAsync = async (): Promise<never> => {
 
 /** 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
   /** Force a refetch (ignores `staleTime`). */
   readonly refetch: () => Promise<T>

package/src/read-deferred.ts

@@ -1,10 +1,10 @@
 /**
- * `readDeferred` — Preact's analogue of React 19's `use()` for a deferred promise (preact/compat has
+ * `readDeferred` - Preact's analogue of React 19's `use()` for a deferred promise (preact/compat has
  * no `use`). Reads a React-style tagged thenable synchronously: returns the value if fulfilled, throws
  * the reason if rejected, else throws the promise so `<Suspense>` awaits it. The core tags
  * `status`/`value`/`reason` via the streamed `__nifraResolve`/`__nifraReject`; this also self-tags on
  * settle so a server re-render (which has no `__nifraResolve`) reads "fulfilled" and stops re-throwing
- * the already-resolved promise. Pure + isomorphic — no `preact` import, so it unit-tests directly.
+ * the already-resolved promise. Pure + isomorphic - no `preact` import, so it unit-tests directly.
  */
 export type Thenable<T> = Promise<T> & {
   status?: "pending" | "fulfilled" | "rejected"
@@ -28,5 +28,5 @@ export function readDeferred<T>(promise: Thenable<T>): T {
       },
     )
   }
-  throw promise // pending — <Suspense> awaits it; the self-tag above wakes the re-render.
+  throw promise // pending - <Suspense> awaits it; the self-tag above wakes the re-render.
 }

package/src/router.ts

@@ -0,0 +1,88 @@
+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"
+/**
+ * `@nifrajs/web-preact/router` - Preact routing bindings over the agnostic `@nifrajs/web` history layer:
+ * `useNavigate` (programmatic navigation), `useBlocker` (the unsaved-changes guard), and `useSearch`
+ * (the route's typed, validated search). Navigation goes through `@nifrajs/web`'s DOM-free bridges
+ * (`getBrowserNavigate` / `registerBlocker`, populated by `installHistory`); `useSearch` reads the value
+ * `compose` provides on SSR + client mount alike. Client-safe (no `preact-render-to-string`). No JSX.
+ */
+import { createContext } from "preact"
+import { useCallback, useContext, useEffect, useRef, useState } from "preact/compat"
+
+export type { Blocker, BlockerFunction, BlockerState, NavigateFunction } from "@nifrajs/web"
+
+// Frozen empty search so the default context value has a stable reference.
+const EMPTY_SEARCH: Readonly<Record<string, unknown>> = Object.freeze({})
+
+/** The current route's validated search, provided by `compose` on SSR + client mount alike (derived from
+ * the URL via the shared `searchOfChain`). `{}` outside a nifra route tree. Read via {@link useSearch}. */
+export const SearchContext = createContext<Record<string, unknown>>(EMPTY_SEARCH)
+
+/**
+ * The route's typed, validated search params - the SAME value the loader received as `ctx.search`.
+ * SSR-correct: `compose` provides it from the URL 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. Pass the route's `searchSchema` as the type argument to
+ * get its output type; bare, it's the raw parsed query (`Record<string, unknown>`).
+ *
+ * ```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(SearchContext) as Schema extends StandardSchemaV1
+    ? InferOutput<Schema>
+    : Record<string, unknown>
+}
+
+/** Get the {@link NavigateFunction} (a string path, a history delta, or a typed `{ to, search }` object).
+ * 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: string | number | NavigateTargetInput, options?: NavigateOptions) => {
+    const navigate = getBrowserNavigate()
+    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
+ * (an 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) on the server and before hydration.
+ */
+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 without re-registering (which would drop an open prompt).
+  const shouldBlockRef = useRef(shouldBlock)
+  shouldBlockRef.current = shouldBlock
+  useEffect(
+    () =>
+      registerBlocker((args) => {
+        const current = shouldBlockRef.current
+        return typeof current === "function" ? current(args) : current
+      }, setBlocker),
+    [],
+  )
+  return blocker
+}