@nifrajs/web-react 0.1.0-alpha.1

package/dist/island.js

@@ -0,0 +1,23 @@
+/**
+ * `@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`,
+ * 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
+ * island bundle (your enhancers + the tiny runtime) loads via the route's `islandScripts`. The island's
+ * SSR markup is real content (works with JS off); the enhancer upgrades it when it loads.
+ */
+import { createElement } from "react";
+/** Render a `<nifra-island>` marker around server-rendered `children`. The client enhancer mounts the
+ * interactivity (see `mountIslands`). Props are JSON-encoded into `data-props`; React escapes the
+ * attribute value and the client reads the decoded `dataset.props`. */
+export function Island({ id, props, strategy = "load", children }) {
+    return createElement("nifra-island", {
+        "data-id": id,
+        "data-strategy": strategy,
+        // Omit `data-props` entirely when there are no props (keeps markup minimal + parse a no-op).
+        ...(props === undefined ? {} : { "data-props": JSON.stringify(props) }),
+    }, children);
+}
+//# sourceMappingURL=island.js.map

package/dist/island.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"island.js","sourceRoot":"","sources":["../src/island.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAkB,MAAM,OAAO,CAAA;AAarD;;uEAEuE;AACvE,MAAM,UAAU,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,EAAE,QAAQ,EAAe;IAC5E,OAAO,aAAa,CAClB,cAAc,EACd;QACE,SAAS,EAAE,EAAE;QACb,eAAe,EAAE,QAAQ;QACzB,6FAA6F;QAC7F,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;KACxE,EACD,QAAQ,CACT,CAAA;AACH,CAAC"}

package/dist/query.d.ts

@@ -0,0 +1,17 @@
+import { type QueryClient, type QueryState } from "@nifrajs/web";
+/** Access the query client to imperatively `invalidateQueries(keyOrPrefix)` (e.g. after a mutation). */
+export declare function useQueryClient(): Pick<QueryClient, "invalidateQueries">;
+/** 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;
+    /** 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.
+ */
+export declare function useQuery<T>(key: unknown, fn: () => Promise<T>): UseQueryResult<T>;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,UAAU,EAChB,MAAM,cAAc,CAAA;AAqBrB,wGAAwG;AACxG,wBAAgB,cAAc,IAAI,IAAI,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAEvE;AAgBD,0EAA0E;AAC1E,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACtD,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;CACnC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAgBjF"}

package/dist/query.js

@@ -0,0 +1,58 @@
+import { createQueryClient, } 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";
+let client;
+function getClient() {
+    if (typeof window === "undefined")
+        return undefined; // SSR → no client (queries render idle)
+    if (client === undefined)
+        client = createQueryClient({ now: () => Date.now() });
+    return client;
+}
+/** Access the query client to imperatively `invalidateQueries(keyOrPrefix)` (e.g. after a mutation). */
+export function useQueryClient() {
+    return getClient() ?? { invalidateQueries: () => { } };
+}
+// Stable idle snapshot for the server / pre-fetch render (stable ref → no loop, no hydration mismatch).
+const IDLE = Object.freeze({
+    status: "pending",
+    data: undefined,
+    error: undefined,
+    isFetching: false,
+    updatedAt: Number.NEGATIVE_INFINITY,
+});
+const idleSnapshot = () => IDLE;
+const noopSubscribe = () => () => { };
+const noopAsync = async () => {
+    throw new Error("[nifra/web-react] useQuery.refetch called with no query client (server?)");
+};
+/**
+ * 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.
+ */
+export function useQuery(key, fn) {
+    const handle = getClient()?.query(key, fn);
+    const state = useSyncExternalStore(handle?.subscribe ?? noopSubscribe, handle ? handle.snapshot : idleSnapshot, idleSnapshot);
+    // 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]);
+    return {
+        ...state,
+        isPending: state.status === "pending",
+        refetch: handle ? handle.refetch : noopAsync,
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAIlB,MAAM,cAAc,CAAA;AACrB;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAEvD,IAAI,MAA+B,CAAA;AACnC,SAAS,SAAS;IAChB,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,SAAS,CAAA,CAAC,wCAAwC;IAC5F,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,GAAG,iBAAiB,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAC/E,OAAO,MAAM,CAAA;AACf,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,cAAc;IAC5B,OAAO,SAAS,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAA;AACvD,CAAC;AAED,wGAAwG;AACxG,MAAM,IAAI,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC5C,MAAM,EAAE,SAAS;IACjB,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,UAAU,EAAE,KAAK;IACjB,SAAS,EAAE,MAAM,CAAC,iBAAiB;CACpC,CAAC,CAAA;AACF,MAAM,YAAY,GAAG,GAAsB,EAAE,CAAC,IAAI,CAAA;AAClD,MAAM,aAAa,GAAG,GAAiB,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC,CAAA;AAClD,MAAM,SAAS,GAAG,KAAK,IAAoB,EAAE;IAC3C,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAA;AAC7F,CAAC,CAAA;AAUD;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAI,GAAY,EAAE,EAAoB;IAC5D,MAAM,MAAM,GAA+B,SAAS,EAAE,EAAE,KAAK,CAAI,GAAG,EAAE,EAAE,CAAC,CAAA;IACzE,MAAM,KAAK,GAAG,oBAAoB,CAChC,MAAM,EAAE,SAAS,IAAI,aAAa,EAClC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,EACvC,YAAY,CACb,CAAA;IACD,wGAAwG;IACxG,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAC1D,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IACZ,OAAO;QACL,GAAG,KAAK;QACR,SAAS,EAAE,KAAK,CAAC,MAAM,KAAK,SAAS;QACrC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAE,SAA8B;KACnE,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@nifrajs/web-react",
+  "version": "0.1.0-alpha.1",
+  "description": "React render adapter for @nifrajs/web — SSR + hydration (Bun-native JSX, no Babel).",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "bun": "./src/client.ts",
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./await": {
+      "bun": "./src/await.ts",
+      "types": "./dist/await.d.ts",
+      "default": "./dist/await.js"
+    },
+    "./island": {
+      "bun": "./src/island.ts",
+      "types": "./dist/island.d.ts",
+      "default": "./dist/island.js"
+    },
+    "./fetcher": {
+      "bun": "./src/fetcher.ts",
+      "types": "./dist/fetcher.d.ts",
+      "default": "./dist/fetcher.js"
+    },
+    "./query": {
+      "bun": "./src/query.ts",
+      "types": "./dist/query.d.ts",
+      "default": "./dist/query.js"
+    },
+    "./i18n": {
+      "bun": "./src/i18n.ts",
+      "types": "./dist/i18n.d.ts",
+      "default": "./dist/i18n.js"
+    },
+    "./image": {
+      "bun": "./src/image.ts",
+      "types": "./dist/image.d.ts",
+      "default": "./dist/image.js"
+    },
+    "./content": {
+      "bun": "./src/content.ts",
+      "types": "./dist/content.d.ts",
+      "default": "./dist/content.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nifrajs/i18n": "workspace:*",
+    "@nifrajs/image": "workspace:*",
+    "@nifrajs/web": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/web-react"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/await.ts

@@ -0,0 +1,75 @@
+import type { Deferred } from "@nifrajs/web"
+/**
+ * `@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`).
+ *
+ * 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).
+ */
+import { Component, createElement, type ReactNode, Suspense, use } from "react"
+
+export interface AwaitProps<T> {
+  /** A `Deferred<T>` from a loader's `defer(...)`, or an already-resolved value (client nav). */
+  readonly resolve: Deferred<T> | T
+  readonly fallback?: ReactNode
+  /** Rendered if the deferred rejects (the streamed `__nifraReject`). Without it the error
+   * propagates to the nearest error boundary. */
+  readonly errorFallback?: (error: unknown) => ReactNode
+  readonly children: (value: T) => ReactNode
+}
+
+// Catches the rejection `use()` throws when the deferred rejects → renders `errorFallback`. A class
+// is required (React error boundaries have no hook form). Local so `<Await>` is self-contained.
+class AwaitBoundary extends Component<
+  { fallback: (error: unknown) => ReactNode; children?: ReactNode },
+  { caught: boolean; error: unknown }
+> {
+  override state: { caught: boolean; error: unknown } = { caught: false, error: undefined }
+  static getDerivedStateFromError(error: unknown): { caught: boolean; error: unknown } {
+    return { caught: true, error }
+  }
+  override render(): ReactNode {
+    return this.state.caught ? this.props.fallback(this.state.error) : this.props.children
+  }
+}
+
+function isDeferred<T>(value: Deferred<T> | T): value is Deferred<T> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __nifra_deferred?: unknown }).__nifra_deferred === true
+  )
+}
+
+// Type-erased (non-generic) so `createElement` infers cleanly; `Await<T>` casts at the call site.
+function Resolved(props: {
+  marker: Deferred<unknown>
+  render: (value: unknown) => ReactNode
+}): ReactNode {
+  return props.render(use(props.marker.promise))
+}
+
+/**
+ * Render deferred loader data: show `fallback` until the `Deferred` settles (streamed in by the
+ * server), then `children(value)`. An already-resolved `resolve` (a client navigation awaited it)
+ * renders immediately. Pairs with a loader's `defer(...)`.
+ */
+export function Await<T>(props: AwaitProps<T>): ReactNode {
+  if (!isDeferred(props.resolve)) return props.children(props.resolve)
+  const suspense = createElement(
+    Suspense,
+    { fallback: props.fallback },
+    createElement(Resolved, {
+      marker: props.resolve,
+      // safe: the registry promise resolves to T; Resolved is type-erased to satisfy createElement.
+      render: props.children as (value: unknown) => ReactNode,
+    }),
+  )
+  return props.errorFallback
+    ? createElement(AwaitBoundary, { fallback: props.errorFallback }, suspense)
+    : suspense
+}

package/src/client.ts

@@ -0,0 +1,42 @@
+import type { MountRouterOptions, RenderProps } from "@nifrajs/web"
+/**
+ * @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.
+ */
+import { createElement, type FunctionComponent, useSyncExternalStore } from "react"
+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
+// nifra's client codegen resolves it from `@nifrajs/web-react/client` alongside `mountRouter`.
+export { errorBoundary } from "./error.ts"
+
+/** Hydrate a server-rendered React layout `chain` (with the loader `props`) inside `container`. */
+export function hydrate(chain: readonly unknown[], props: RenderProps, container: unknown): void {
+  hydrateRoot(container as Element, compose(chain, props))
+}
+
+/**
+ * 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
+ * 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
+  setMountedRouter(router) // expose it to useFetcher/useFetchers (same page, client-only)
+  const Router: FunctionComponent = () => {
+    const state = useSyncExternalStore(router.subscribe, router.snapshot, router.snapshot)
+    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.
+      ...(state.submission ? { submission: state.submission } : {}),
+    })
+  }
+  hydrateRoot(container as Element, createElement(Router))
+}

package/src/compose.ts

@@ -0,0 +1,17 @@
+import type { RenderProps } from "@nifrajs/web"
+import { createElement, type FunctionComponent, type ReactNode } from "react"
+
+/**
+ * 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).
+ */
+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)
+  }
+  return node
+}

package/src/content.ts

@@ -0,0 +1,27 @@
+/**
+ * `@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.
+ */
+import {
+  type ComponentPropsWithoutRef,
+  createElement,
+  type ElementType,
+  type ReactElement,
+} from "react"
+
+export interface ContentProps
+  extends Omit<ComponentPropsWithoutRef<"div">, "dangerouslySetInnerHTML" | "children"> {
+  /** Trusted, pre-rendered HTML (e.g. `entry.html`). */
+  readonly html: string
+  /** Wrapper element (default `"div"`). */
+  readonly as?: ElementType
+}
+
+/** Render trusted HTML into a wrapper element. Extra props (`className`, `id`, `style`, …) pass through. */
+export function Content({ html, as, ...rest }: ContentProps): ReactElement {
+  return createElement(as ?? "div", { ...rest, dangerouslySetInnerHTML: { __html: html } })
+}

package/src/error.ts

@@ -0,0 +1,33 @@
+/**
+ * `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).
+ */
+import { Component, createElement, type FunctionComponent, type ReactNode } from "react"
+
+/**
+ * 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.
+ */
+export function errorBoundary(fallback: unknown): unknown {
+  type Props = { children?: ReactNode }
+  type State = { error: Error | null }
+  return class NifraErrorBoundary extends Component<Props, State> {
+    constructor(props: Props) {
+      super(props)
+      this.state = { error: null }
+    }
+    static getDerivedStateFromError(error: Error): State {
+      return { error }
+    }
+    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.
+      const Fallback = fallback as FunctionComponent<{ data: { name: string; message: string } }>
+      return createElement(Fallback, { data: { name: error.name, message: error.message } })
+    }
+  }
+}

package/src/fetcher.ts

@@ -0,0 +1,66 @@
+import type { ClientRouter, Fetcher, FetcherState } from "@nifrajs/web"
+/**
+ * `@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
+ * `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.
+ */
+import { useSyncExternalStore } from "react"
+
+// The active client router (set by `mountRouter`). Module-scoped: the browser mounts one app per
+// 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. */
+export function setMountedRouter(router: ClientRouter | undefined): void {
+  mountedRouter = router
+}
+
+// Stable idle values for the server / pre-mount snapshot (stable refs → no `useSyncExternalStore`
+// loop, no hydration mismatch).
+const IDLE: FetcherState = { pending: false, data: undefined }
+const NO_FETCHERS: readonly Fetcher[] = []
+const noopSubscribe = (): (() => void) => () => {}
+const noopAsync = async (): Promise<void> => {}
+
+/** A fetcher's reactive {@link FetcherState} plus its imperative `load`/`submit`. */
+export interface FetcherHandle extends FetcherState {
+  /** Load a route path's loader data into this fetcher (concurrent; doesn't touch the active view). */
+  readonly load: (path: string) => Promise<void>
+  /** Submit an action into this fetcher (concurrent); honors `X-Nifra-Revalidate`. */
+  readonly submit: (action: string, body: NonNullable<RequestInit["body"]>) => Promise<void>
+}
+
+/**
+ * Subscribe to the independent fetcher for `key` (created lazily, stable across renders). Returns its
+ * state (`pending`/`data`/`actionData`/`submission`) + `load`/`submit`. Multiple `useFetcher` calls
+ * with different keys run concurrently without disturbing the active route or each other.
+ */
+export function useFetcher(key: string): FetcherHandle {
+  const fetcher = mountedRouter?.fetcher(key)
+  const state = useSyncExternalStore(
+    fetcher?.subscribe ?? noopSubscribe,
+    fetcher?.snapshot ?? (() => IDLE),
+    () => IDLE, // server: fetchers are client-only → idle (matches the first client render)
+  )
+  return { ...state, load: fetcher?.load ?? noopAsync, submit: fetcher?.submit ?? noopAsync }
+}
+
+/**
+ * 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.
+ */
+export function useFetchers(): readonly Fetcher[] {
+  return useSyncExternalStore(
+    mountedRouter?.subscribeFetchers ?? noopSubscribe,
+    mountedRouter?.fetchers ?? (() => NO_FETCHERS),
+    () => NO_FETCHERS,
+  )
+}

package/src/i18n.ts

@@ -0,0 +1,36 @@
+/**
+ * `@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` +
+ * `@nifrajs/i18n`; no JSX (the package builds with plain `tsc`).
+ */
+import { createFormatter, type Formatter, type Messages } from "@nifrajs/i18n"
+import { createContext, createElement, type ReactNode, useContext, useMemo } from "react"
+
+const I18nContext = createContext<Formatter | null>(null)
+
+export interface I18nProviderProps {
+  readonly locale: string
+  readonly messages: Messages
+  readonly children?: ReactNode
+}
+
+/** Provide a {@link Formatter} (built from `locale` + `messages`) to the subtree. Memoized on
+ * `locale`/`messages`, so switching locale rebuilds it and re-renders consumers. */
+export function I18nProvider(props: I18nProviderProps): ReactNode {
+  const formatter = useMemo(
+    () => createFormatter(props.locale, props.messages),
+    [props.locale, props.messages],
+  )
+  return createElement(I18nContext.Provider, { value: formatter }, props.children)
+}
+
+/** Read the current {@link Formatter} (`{ locale, t, n, d }`). Throws if no `<I18nProvider>` is above. */
+export function useT(): Formatter {
+  const formatter = useContext(I18nContext)
+  if (formatter === null) {
+    throw new Error("[nifra/web-react] useT() must be used within an <I18nProvider>")
+  }
+  return formatter
+}

package/src/image.ts

@@ -0,0 +1,43 @@
+/**
+ * `@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`
+ * (an image CDN); nifra bundles no codec. Imports only `react` + `@nifrajs/image`; no JSX.
+ */
+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. */
+type ComputedAttrs =
+  | "src"
+  | "srcSet"
+  | "sizes"
+  | "width"
+  | "height"
+  | "alt"
+  | "loading"
+  | "decoding"
+  | "fetchPriority"
+
+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). */
+  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). */
+  readonly [key: `data-${string}`]: string | number | boolean | undefined
+}
+
+/**
+ * Render a responsive, CLS-safe `<img>`. `width`+`height` are required (reserve layout space);
+ * `priority` marks the LCP image (`eager` + `fetchpriority="high"`). Extra DOM props pass through.
+ */
+export function Image(props: ImageComponentProps): ReactElement {
+  // Strip the nifra-only props (not valid DOM attributes) before forwarding the rest to <img>.
+  const { loader, widths, quality, priority, ...rest } = props
+  const resolved = resolveImage(props, loader)
+  // `resolved` wins over the raw src/width/height/alt/sizes/loading still present in `rest`.
+  return createElement("img", { ...rest, ...resolved })
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+import type { RenderAdapter } from "@nifrajs/web"
+/**
+ * @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.
+ */
+import { renderToString as reactRenderToString, renderToReadableStream } from "react-dom/server"
+import { compose } from "./compose.ts"
+
+/** 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
+  // streaming machinery is the heaviest. A page that defer()s/Suspends takes `renderToStream` below.
+  renderToString(chain, props) {
+    return reactRenderToString(compose(chain, props))
+  },
+  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
+    // the document tail. React's default `onError` logs to console.error (errors aren't swallowed).
+    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.
+  hydrationHead() {
+    return ""
+  },
+}

package/src/island.ts

@@ -0,0 +1,39 @@
+import type { IslandStrategy } from "@nifrajs/web/islands"
+/**
+ * `@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`,
+ * 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
+ * island bundle (your enhancers + the tiny runtime) loads via the route's `islandScripts`. The island's
+ * SSR markup is real content (works with JS off); the enhancer upgrades it when it loads.
+ */
+import { createElement, type ReactNode } from "react"
+
+export interface IslandProps {
+  /** Stable id matching the key in the client's `mountIslands({ <id>: enhancer })`. */
+  readonly id: string
+  /** Serializable props handed to the enhancer (JSON-encoded inline in `data-props`; no closures). */
+  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. */
+  readonly children?: ReactNode
+}
+
+/** Render a `<nifra-island>` marker around server-rendered `children`. The client enhancer mounts the
+ * interactivity (see `mountIslands`). Props are JSON-encoded into `data-props`; React escapes the
+ * attribute value and the client reads the decoded `dataset.props`. */
+export function Island({ id, props, strategy = "load", children }: IslandProps): ReactNode {
+  return createElement(
+    "nifra-island",
+    {
+      "data-id": id,
+      "data-strategy": strategy,
+      // Omit `data-props` entirely when there are no props (keeps markup minimal + parse a no-op).
+      ...(props === undefined ? {} : { "data-props": JSON.stringify(props) }),
+    },
+    children,
+  )
+}