@nifrajs/web-react 2.1.0 → 2.3.0

package/package.json

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

package/src/await.ts

@@ -1,6 +1,6 @@
 import type { Deferred } from "@nifrajs/web"
 /**
- * `@nifrajs/web-react/await` — the `<Await>` primitive for deferred loader data (`defer()`). Isomorphic
+ * `@nifrajs/web-react/await` - the `<Await>` primitive for deferred loader data (`defer()`). Isomorphic
  * and imports only `react` + a type from `@nifrajs/web` (never `react-dom/server`), so route components
  * can use it without dragging server code into the client bundle. No JSX (the package builds with
  * plain `tsc`).
@@ -8,7 +8,7 @@ import type { Deferred } from "@nifrajs/web"
  * The server streams the boundary: `use(promise)` suspends, React flushes the fallback then the
  * resolved content mid-stream. On the client the registry promise is already settled (the core's
  * streamed `__nifraResolve` script tagged it `fulfilled`), so `use()` returns the value synchronously
- * — React hydrates the server-revealed boundary's content directly (no re-fetch, no fallback flash).
+ * - React hydrates the server-revealed boundary's content directly (no re-fetch, no fallback flash).
  */
 import { Component, createElement, type ReactNode, Suspense, use } from "react"
 

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-react/client — React client runtime. `hydrate` hydrates a single SSR'd route;
+ * @nifrajs/web-react/client - React client runtime. `hydrate` hydrates a single SSR'd route;
  * `mountRouter` hydrates a stateful Router that subscribes to the agnostic store (via
  * `useSyncExternalStore`) and re-renders the matched chain on every client navigation (no full
  * reload). Kept in its own entry so server code stays out of the client bundle.
@@ -10,7 +10,7 @@ import { hydrateRoot } from "react-dom/client"
 import { compose } from "./compose.ts"
 import { setMountedRouter } from "./fetcher.ts"
 
-// The `_error` boundary chain element — defined in its own (react-dom-free) module, re-exported here so
+// The `_error` boundary chain element - defined in its own (react-dom-free) module, re-exported here so
 // nifra's client codegen resolves it from `@nifrajs/web-react/client` alongside `mountRouter`.
 export { errorBoundary } from "./error.ts"
 
@@ -21,25 +21,31 @@ export function hydrate(chain: readonly unknown[], props: RenderProps, container
 
 /**
  * Hydrate a stateful React Router. `useSyncExternalStore` subscribes to the agnostic store and
- * re-renders the matched layout chain on each store change — so client navigations swap routes
+ * re-renders the matched layout chain on each store change - so client navigations swap routes
  * without a full reload. `getServerSnapshot` (3rd arg) returns the initial state, matching the
  * SSR markup on hydration.
  */
 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, router.snapshot)
+    // Derive this route's typed `search` from the URL query + the route's schema CHAIN (layout schemas +
+    // page, merged page-wins), 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,
       ...(state.pendingPath !== undefined ? { pendingPath: state.pendingPath } : {}),
-      // `params`/`path` feed the routing hooks (useParams/useLocation) via compose's RouterContext —
+      // `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.
+      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

@@ -5,23 +5,34 @@ 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.
-    node = createElement(chain[i] as FunctionComponent, null, node)
+    // 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.
+    node = createElement(
+      chain[i] as FunctionComponent<{ data: unknown }>,
+      { data: props.layoutData?.[i] ?? null },
+      node,
+    )
   }
   return createElement(
     RouterContext.Provider,
@@ -29,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,15 +26,32 @@
 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>>
 }
 
+interface RuntimeProcess {
+  getBuiltinModule?(specifier: string): unknown
+}
+
+function dirnamePortable(path: string): string {
+  const slash = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"))
+  return slash <= 0 ? "." : path.slice(0, slash)
+}
+
+function runtimeRealpath(path: string): string {
+  const runtimeProcess = (globalThis as { process?: RuntimeProcess }).process
+  const fs = runtimeProcess?.getBuiltinModule?.("node:fs") as
+    | { realpathSync?: (value: string) => string }
+    | undefined
+  return fs?.realpathSync?.(path) ?? path
+}
+
 // `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
@@ -72,6 +89,54 @@ export function reactDomServer(): Promise<ReactDomServer> {
 /** A `Bun.resolveSync`-shaped function (specifier, from) → absolute path. */
 type ResolveSync = (specifier: string, from: string) => string
 
+/**
+ * The dual-React crash, caught on the RESOLVED graph instead of after it detonates.
+ *
+ * The re-root above makes `react-dom/server` load from the app root, which is right almost always. What it
+ * cannot guarantee is that react-dom then pulls in the SAME physical `react` the route components import -
+ * a nested `react` under react-dom, or a components tree resolving react elsewhere, still yields two cores.
+ * Two cores is two hook dispatchers, and the renderer sees a null (or foreign) one: the SSR throws
+ * `resolveDispatcher().useState is null` from deep inside react-dom-server, naming a React internal and
+ * nothing about the two directories that actually caused it. That is hours of inference from a message
+ * that points nowhere useful.
+ *
+ * `nifra doctor` checks what is INSTALLED; this checks what SSR actually RESOLVED, which is the only thing
+ * that can catch a duplicate the two dev pipelines introduce (Bun for SSR, Vite for the client) rather
+ * than the install. It compares the realpath of the `react` react-dom will render with against the
+ * `react` the components import, and if they differ throws with BOTH paths - turning a five-hour hunt into
+ * a five-second read. Silent when they agree, which is the single-copy common case.
+ *
+ * Never manufactures a failure: if either side cannot be resolved it returns, because a resolver that
+ * cannot answer is not evidence of a duplicate. Exported for direct unit testing.
+ */
+export function assertSingleReactCore(
+  reactDomServerPath: string,
+  resolve: ResolveSync,
+  realpath: (path: string) => string = runtimeRealpath,
+): void {
+  let rendererReact: string
+  let componentsReact: string
+  try {
+    // The `react` react-dom/server itself resolves - the core whose dispatcher the renderer sets.
+    rendererReact = realpath(resolve("react", dirnamePortable(reactDomServerPath)))
+    // The `react` the app's route components import - the core they call hooks on.
+    componentsReact = realpath(resolve("react", appRoot()))
+  } catch {
+    return
+  }
+  if (rendererReact === componentsReact) return
+  throw new Error(
+    "[nifra/web-react] two copies of React reached SSR, so hooks render against a null dispatcher " +
+      "(the `resolveDispatcher().useState is null` crash). react-dom renders with a DIFFERENT React " +
+      "than your components import:\n" +
+      `  react-dom's react:  ${rendererReact}\n` +
+      `  components' react:  ${componentsReact}\n` +
+      "Module identity is path-based, so two copies fail even at the same version. Dedupe react to one " +
+      "physical copy - usually a single hoisted install at the workspace root (`nifra doctor` locates " +
+      "the duplicate). A Vite `resolve.dedupe`/alias fixes only the client bundle, not this SSR path.",
+  )
+}
+
 /**
  * Load `react-dom/server`, preferring the app-root-resolved copy under the Bun runtime. Exported for unit
  * tests: `resolve` defaults to the ambient `Bun.resolveSync` (undefined on non-Bun hosts), and a test can
@@ -85,11 +150,19 @@ 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.
+      // The re-root fixes the common case; this catches the residual duplicate loudly, with both paths,
+      // instead of leaving it to throw a dispatcher-null error on the first hook render. Runs once (this
+      // whole function is cached), dev/unbundled Bun only (the branch `resolve` gates).
+      assertSingleReactCore(resolved, resolve)
       return (await import(resolved)) as ReactDomServer
-    } catch {
+    } catch (err) {
+      // A genuine duplicate is surfaced (re-thrown with both paths); any other failure (react-dom not at
+      // the app root, an odd nested layout) falls through to the bundled specifier rather than crashing.
+      if (err instanceof Error && err.message.includes("two copies of React")) throw err
       // App-root resolution failed; use the specifier resolved from this module's own location below.
     }
   }
@@ -100,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