@nifrajs/web-react 1.7.0 → 1.9.1

package/dist/router.js

@@ -0,0 +1,165 @@
+/**
+ * `@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
+ * 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 } from "@nifrajs/web";
+import { createContext, createElement, forwardRef, useCallback, useContext, useEffect, useMemo, } from "react";
+// Frozen empty params so the default context value has a stable reference (no needless re-renders).
+const EMPTY_PARAMS = 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. */
+export const RouterContext = createContext({ params: EMPTY_PARAMS, path: "" });
+/** Split a `pathname + search` into its parts. `search` keeps its leading `?` (like `location.search`);
+ * an empty query yields `""`. */
+function splitPath(path) {
+    const q = path.indexOf("?");
+    return q === -1
+        ? { pathname: path, search: "" }
+        : { pathname: path.slice(0, q), search: path.slice(q) };
+}
+/**
+ * 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.
+ */
+export function useParams() {
+    return useContext(RouterContext).params;
+}
+/** The current {@link Location} (`pathname`/`search`/`hash`), derived from the router context. */
+export function useLocation() {
+    const { path } = useContext(RouterContext);
+    return useMemo(() => {
+        const { pathname, search } = splitPath(path);
+        return { pathname, search, hash: "" };
+    }, [path]);
+}
+/** 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). */
+export function useNavigate() {
+    return useCallback((to, options) => {
+        const navigate = getBrowserNavigate();
+        if (navigate !== undefined)
+            navigate(to, options);
+    }, []);
+}
+function toSearchParams(init) {
+    if (init instanceof URLSearchParams)
+        return init;
+    if (typeof init === "string")
+        return new URLSearchParams(init);
+    const usp = new URLSearchParams();
+    for (const [key, value] of Object.entries(init)) {
+        if (Array.isArray(value))
+            for (const item of value)
+                usp.append(key, item);
+        else
+            usp.set(key, value);
+    }
+    return usp;
+}
+/**
+ * The current query as a `URLSearchParams` (SSR-correct via the router context) plus a setter that
+ * navigates to the new query. Mirrors react-router's `useSearchParams` tuple.
+ */
+export function useSearchParams() {
+    const { path } = useContext(RouterContext);
+    const { pathname, search } = splitPath(path);
+    const searchParams = useMemo(() => new URLSearchParams(search), [search]);
+    const navigate = useNavigate();
+    const setSearchParams = useCallback((next, options) => {
+        const resolved = typeof next === "function" ? next(new URLSearchParams(search)) : next;
+        const qs = toSearchParams(resolved).toString();
+        navigate(pathname + (qs !== "" ? `?${qs}` : ""), options);
+    }, [navigate, pathname, search]);
+    return [searchParams, setSearchParams];
+}
+/** 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, target) {
+    if (event.button !== 0)
+        return false;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+        return false;
+    return target === undefined || target === "" || target === "_self";
+}
+/**
+ * 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.
+ */
+export const Link = forwardRef(function Link({ to, replace, onClick, target, ...rest }, ref) {
+    const handleClick = (event) => {
+        onClick?.(event);
+        if (event.defaultPrevented)
+            return; // the app's own handler already took over
+        if (!isPlainLeftClick(event, target))
+            return; // modified / new-tab click → native
+        const navigate = getBrowserNavigate();
+        if (navigate === undefined)
+            return; // pre-hydration → let the native <a href> full-load
+        event.preventDefault();
+        navigate(to, { replace: replace === true });
+    };
+    return createElement("a", { ...rest, href: to, target, onClick: handleClick, ref });
+});
+/** Normalize a pathname for comparison: optional case-fold + drop a single trailing slash (but keep a
+ * bare `"/"`). */
+function normalizePath(pathname, caseSensitive) {
+    const cased = caseSensitive ? pathname : pathname.toLowerCase();
+    return cased !== "/" && cased.endsWith("/") ? cased.slice(0, -1) : cased;
+}
+/**
+ * A {@link Link} that knows whether it points at the current location. Adds `aria-current="page"` when
+ * active and resolves function-form `className`/`style`/`children` with `{ isActive, isPending }`.
+ * Default matching is prefix-on-segment-boundary (so `/users` is active on `/users/7`); pass `end` for
+ * an exact match.
+ */
+export const NavLink = forwardRef(function NavLink({ to, end, caseSensitive, className, style, children, ...rest }, ref) {
+    const { pathname } = useLocation();
+    const cs = caseSensitive === true;
+    const current = normalizePath(pathname, cs);
+    const target = normalizePath(splitPath(to).pathname, cs);
+    const isActive = end === true ? current === target : matchesPrefix(current, target);
+    const renderProps = { isActive, isPending: false };
+    const resolvedClassName = typeof className === "function" ? className(renderProps) : className;
+    const resolvedStyle = typeof style === "function" ? style(renderProps) : style;
+    const resolvedChildren = typeof children === "function" ? children(renderProps) : children;
+    return createElement(Link, {
+        ...rest,
+        to,
+        ref,
+        ...(resolvedClassName !== undefined ? { className: resolvedClassName } : {}),
+        ...(resolvedStyle !== undefined ? { style: resolvedStyle } : {}),
+        // `aria-current="page"` is the accessible active marker; style with `[aria-current="page"]`.
+        "aria-current": isActive ? "page" : undefined,
+    }, resolvedChildren);
+});
+/** Prefix match on a segment boundary: `current` is `target`, or lives under it (`target + "/"`…). A
+ * bare `"/"` target is a prefix of everything (so `<NavLink to="/">` is active everywhere unless `end`). */
+function matchesPrefix(current, target) {
+    if (current === target)
+        return true;
+    return current.startsWith(target === "/" ? "/" : `${target}/`);
+}
+/**
+ * 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.
+ */
+export function Navigate({ to, replace }) {
+    const navigate = useNavigate();
+    useEffect(() => {
+        navigate(to, { replace: replace === true });
+    }, [navigate, to, replace]);
+    return null;
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/web-react",
-  "version": "1.7.0",
+  "version": "1.9.1",
   "description": "React render adapter for @nifrajs/web — SSR + hydration (Bun-native JSX, no Babel).",
   "keywords": [
     "bun",
@@ -41,6 +41,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",
@@ -75,10 +80,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/core": "1.7.0",
-    "@nifrajs/i18n": "1.7.0",
-    "@nifrajs/image": "1.7.0",
-    "@nifrajs/web": "1.7.0"
+    "@nifrajs/core": "1.9.1",
+    "@nifrajs/i18n": "1.9.1",
+    "@nifrajs/image": "1.9.1",
+    "@nifrajs/web": "1.9.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/client.ts

@@ -34,6 +34,10 @@ export function mountRouter(options: MountRouterOptions): void {
       data: state.data,
       actionData: state.actionData,
       pending: state.pending,
+      // `params`/`path` feed the routing hooks (useParams/useLocation) via compose's RouterContext —
+      // sourced from router state here, matching the SSR render's request-derived values on hydration.
+      params: state.params,
+      path: state.path,
       // The in-flight submission (for optimistic UI) — spread only when present.
       ...(state.submission ? { submission: state.submission } : {}),
     })

package/src/compose.ts

@@ -1,10 +1,19 @@
 import type { RenderProps } from "@nifrajs/web"
 import { createElement, type FunctionComponent, type ReactNode } from "react"
+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({})
 
 /**
  * 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` (both threaded through `RenderProps` identically on SSR and client), so the routing
+ * hooks (`useParams`/`useLocation`/`useSearchParams`) read the same value on both sides — no hydration
+ * mismatch. 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
@@ -13,5 +22,9 @@ export function compose(chain: readonly unknown[], props: RenderProps): ReactNod
     // children passed as the 3rd arg (not a `children` prop) — React's canonical form.
     node = createElement(chain[i] as FunctionComponent, null, node)
   }
-  return node
+  return createElement(
+    RouterContext.Provider,
+    { value: { params: props.params ?? EMPTY_PARAMS, path: props.path ?? "" } },
+    node,
+  )
 }

package/src/query.ts

@@ -1,35 +1,83 @@
+/**
+ * `@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/*`),
+ * so route components use it on the server *and* client. No JSX (the package builds with plain `tsc`).
+ *
+ * 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
+ * and the first client render matches for a clean hydration).
+ */
 import {
+  createMutation,
   createQueryClient,
+  type DehydratedState,
+  type InfiniteData,
+  type InfiniteQueryOptions,
+  type MutationCallbacks,
+  type MutationHandle,
+  type MutationState,
   type QueryClient,
   type QueryHandle,
+  type QueryOptions,
   type QueryState,
 } from "@nifrajs/web"
-/**
- * `@nifrajs/web-react/query` — React bindings for the keyed query-cache. `useQuery(key, fn)` subscribes a
- * component to a query (via `useSyncExternalStore`) and fetches on mount / key change; `useQueryClient`
- * exposes `invalidateQueries` for after a mutation. Imports only `react` + `@nifrajs/web` (never
- * `react-dom/*`), so route components use it on the server *and* client. No JSX (the package builds
- * with plain `tsc`).
- *
- * 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 server-snapshot, so no mismatch.
- */
-import { useEffect, useSyncExternalStore } from "react"
+import {
+  createContext,
+  createElement,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from "react"
+
+export type { DehydratedState } from "@nifrajs/web"
+
+// The lazily-created client-side singleton (used when no QueryClientProvider is present). SSR-guarded:
+// the server has no singleton, so provider-less hooks render idle there.
+let singleton: QueryClient | undefined
+function getSingleton(): QueryClient | undefined {
+  if (typeof window === "undefined") return undefined
+  if (singleton === undefined) singleton = createQueryClient({ now: () => Date.now() })
+  return singleton
+}
 
-let client: QueryClient | undefined
-function getClient(): QueryClient | undefined {
-  if (typeof window === "undefined") return undefined // SSR → no client (queries render idle)
-  if (client === undefined) client = createQueryClient({ now: () => Date.now() })
-  return client
+// A no-op client for the server / pre-hydration (all reads empty, all writes ignored). Stable ref so a
+// hook's `useSyncExternalStore` server snapshot is consistent.
+const NOOP_CLIENT: QueryClient = {
+  query: () => IDLE_HANDLE as QueryHandle<never>,
+  infiniteQuery: () => IDLE_INFINITE_HANDLE as never,
+  invalidateQueries: () => {},
+  getQueryData: () => undefined,
+  setQueryData: () => {},
+  prefetchQuery: async () => {},
+  dehydrate: () => ({ queries: [] }),
+  hydrate: () => {},
 }
 
-/** Access the query client to imperatively `invalidateQueries(keyOrPrefix)` (e.g. after a mutation). */
-export function useQueryClient(): Pick<QueryClient, "invalidateQueries"> {
-  return getClient() ?? { invalidateQueries: () => {} }
+const QueryClientContext = createContext<QueryClient | undefined>(undefined)
+
+/** 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
+  readonly children?: ReactNode
+}): ReactNode {
+  return createElement(QueryClientContext.Provider, { value: props.client }, props.children)
 }
 
-// Stable idle snapshot for the server / pre-fetch render (stable ref → no loop, no hydration mismatch).
+/** The active {@link QueryClient}: a `QueryClientProvider`'s client, else the client-side singleton,
+ * else a no-op (server / pre-hydration). Use it to `invalidateQueries`/`setQueryData`/`prefetchQuery`. */
+export function useQueryClient(): QueryClient {
+  const provided = useContext(QueryClientContext)
+  return provided ?? getSingleton() ?? NOOP_CLIENT
+}
+
+// Stable idle snapshots + handles for the server / pre-fetch render (stable refs → no loop, no mismatch).
 const IDLE: QueryState<never> = Object.freeze({
   status: "pending",
   data: undefined,
@@ -38,38 +86,191 @@ const IDLE: QueryState<never> = Object.freeze({
   updatedAt: Number.NEGATIVE_INFINITY,
 })
 const idleSnapshot = (): QueryState<never> => IDLE
+const IDLE_INFINITE: QueryState<InfiniteData<never, never>> = IDLE as QueryState<
+  InfiniteData<never, never>
+>
+const idleInfiniteSnapshot = (): QueryState<InfiniteData<never, never>> => IDLE_INFINITE
 const noopSubscribe = (): (() => void) => () => {}
 const noopAsync = async (): Promise<never> => {
-  throw new Error("[nifra/web-react] useQuery.refetch called with no query client (server?)")
+  throw new Error("[nifra/web-react] query action called with no query client (server?)")
+}
+const IDLE_HANDLE: QueryHandle<never> = {
+  snapshot: idleSnapshot,
+  subscribe: noopSubscribe,
+  fetch: noopAsync,
+  refetch: noopAsync,
+}
+const IDLE_INFINITE_HANDLE = {
+  snapshot: idleInfiniteSnapshot,
+  subscribe: noopSubscribe,
+  fetch: noopAsync,
+  refetch: noopAsync,
+  fetchNextPage: noopAsync,
+  fetchPreviousPage: noopAsync,
+  hasNextPage: () => false,
+  hasPreviousPage: () => false,
+}
+
+/** Options for {@link useQuery}. */
+export interface UseQueryOptions extends QueryOptions {
+  /** 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). */
   readonly isPending: boolean
+  /** `status === "error"`. */
+  readonly isError: boolean
+  /** `status === "success"`. */
+  readonly isSuccess: boolean
   /** Force a refetch (ignores `staleTime`). */
   readonly refetch: () => Promise<T>
 }
 
 /**
  * Subscribe to the keyed query for `key`, fetched via `fn`. Returns `{ status, data, error, isFetching,
- * updatedAt, isPending, refetch }`. Concurrent `useQuery`s with the same key share one cache entry +
- * one in-flight fetch (dedup). Refetches on mount and when the key changes; SSR-idle.
+ * updatedAt, isPending, isError, isSuccess, refetch }`. Concurrent `useQuery`s with the same key share
+ * one cache entry + one in-flight fetch (dedup). Fetches on mount and when the key changes; `enabled:
+ * false` keeps it idle (dependent queries). SSR-idle unless a `QueryClientProvider` supplies a hydrated
+ * client.
  */
-export function useQuery<T>(key: unknown, fn: () => Promise<T>): UseQueryResult<T> {
-  const handle: QueryHandle<T> | undefined = getClient()?.query<T>(key, fn)
+export function useQuery<T>(
+  key: unknown,
+  fn: () => Promise<T>,
+  options?: UseQueryOptions,
+): UseQueryResult<T> {
+  const client = useQueryClient()
+  const enabled = options?.enabled !== false
+  const queryOpts: QueryOptions | undefined =
+    options?.staleTime !== undefined ? { staleTime: options.staleTime } : undefined
+  // 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
+  // query renders its data during SSR and the first client render matches (no loading flash, no drift).
   const state = useSyncExternalStore<QueryState<T>>(
-    handle?.subscribe ?? noopSubscribe,
-    handle ? handle.snapshot : idleSnapshot,
-    idleSnapshot,
+    handle.subscribe,
+    handle.snapshot,
+    handle.snapshot,
   )
-  // Fetch on mount + whenever the key changes (the handle is stable per key, so it changes with the key).
   useEffect(() => {
-    if (handle !== undefined) handle.fetch().catch(() => {})
-  }, [handle])
+    if (enabled) handle.fetch().catch(() => {})
+  }, [handle, enabled])
+  return {
+    ...state,
+    isPending: state.status === "pending",
+    isError: state.status === "error",
+    isSuccess: state.status === "success",
+    refetch: handle.refetch,
+  }
+}
+
+/** A mutation's reactive state + imperative controls (the TanStack `useMutation` shape). */
+export interface UseMutationResult<TData, TVariables> extends MutationState<TData, TVariables> {
+  readonly isIdle: boolean
+  readonly isPending: boolean
+  readonly isError: boolean
+  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`. */
+  readonly mutateAsync: (variables: TVariables) => Promise<TData>
+  /** Reset back to idle. */
+  readonly reset: () => void
+}
+
+/**
+ * A mutation hook (create/update/delete). Returns `{ mutate, mutateAsync, data, error, variables, isIdle,
+ * isPending, isError, isSuccess, reset }`. Invalidate affected queries from `onSuccess` via
+ * `useQueryClient().invalidateQueries(...)`. The handle is stable across renders; the latest `fn`/
+ * callbacks re-bind each render.
+ */
+export function useMutation<TData, TVariables = void>(
+  fn: (variables: TVariables) => Promise<TData>,
+  callbacks: MutationCallbacks<TData, TVariables> = {},
+): UseMutationResult<TData, TVariables> {
+  const ref = useRef<MutationHandle<TData, TVariables> | undefined>(undefined)
+  if (ref.current === undefined) ref.current = createMutation(fn, callbacks)
+  const handle = ref.current
+  handle.rebind(fn, callbacks) // pick up the latest closures each render
+  const state = useSyncExternalStore(handle.subscribe, handle.snapshot, handle.snapshot)
+  return {
+    ...state,
+    isIdle: state.status === "idle",
+    isPending: state.status === "pending",
+    isError: state.status === "error",
+    isSuccess: state.status === "success",
+    mutate: (variables) => {
+      handle.mutate(variables).catch(() => {}) // fire-and-forget: don't surface an unhandled rejection
+    },
+    mutateAsync: handle.mutate,
+    reset: handle.reset,
+  }
+}
+
+/** Options for {@link useInfiniteQuery} — the engine's {@link InfiniteQueryOptions} plus `enabled`. */
+export interface UseInfiniteQueryOptions<T, P> extends InfiniteQueryOptions<T, P> {
+  readonly enabled?: boolean
+}
+
+/** An infinite query's reactive state + paging controls. */
+export interface UseInfiniteQueryResult<T, P> extends QueryState<InfiniteData<T, P>> {
+  readonly isPending: boolean
+  readonly isError: boolean
+  readonly isSuccess: boolean
+  readonly fetchNextPage: () => Promise<InfiniteData<T, P>>
+  readonly fetchPreviousPage: () => Promise<InfiniteData<T, P>>
+  readonly hasNextPage: boolean
+  readonly hasPreviousPage: boolean
+  readonly refetch: () => Promise<InfiniteData<T, P>>
+}
+
+/**
+ * Subscribe to a paged (infinite-scroll) query. Returns the accumulated `data.pages` plus
+ * `fetchNextPage`/`fetchPreviousPage`/`hasNextPage`/`hasPreviousPage`. Fetches the first page on mount.
+ * SSR-idle unless a `QueryClientProvider` supplies a hydrated client.
+ */
+export function useInfiniteQuery<T, P>(
+  key: unknown,
+  fn: (pageParam: P) => Promise<T>,
+  options: UseInfiniteQueryOptions<T, P>,
+): UseInfiniteQueryResult<T, P> {
+  const client = useQueryClient()
+  const enabled = options.enabled !== false
+  const handle = client.infiniteQuery<T, P>(key, fn, options)
+  const state = useSyncExternalStore(handle.subscribe, handle.snapshot, handle.snapshot)
+  useEffect(() => {
+    if (enabled) handle.fetch().catch(() => {})
+  }, [handle, enabled])
   return {
     ...state,
     isPending: state.status === "pending",
-    refetch: handle ? handle.refetch : (noopAsync as () => Promise<T>),
+    isError: state.status === "error",
+    isSuccess: state.status === "success",
+    fetchNextPage: handle.fetchNextPage,
+    fetchPreviousPage: handle.fetchPreviousPage,
+    hasNextPage: handle.hasNextPage(),
+    hasPreviousPage: handle.hasPreviousPage(),
+    refetch: handle.refetch,
   }
 }
+
+/**
+ * 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.
+ */
+export function HydrationBoundary(props: {
+  readonly state: DehydratedState | undefined
+  readonly children?: ReactNode
+}): ReactNode {
+  const client = useQueryClient()
+  const { state } = props
+  useMemo(() => {
+    if (state !== undefined) client.hydrate(state)
+  }, [client, state])
+  return props.children ?? null
+}