@nifrajs/web-react 3.5.0 → 4.0.0

package/dist/router.js

@@ -13,6 +13,8 @@
 // `/client`, not the root - these are DOM values, and the root's graph carries the
 // server, which Vite's dev server evaluates rather than tree-shakes.
 import { getBrowserNavigate, IDLE_BLOCKER, registerBlocker, resolveNavigate, } from "@nifrajs/web/client";
+// Its own subpath, so an app that never calls `useMatches` bundles none of it.
+import { chainMatches } from "@nifrajs/web/internal/matches-runtime";
 import { createContext, createElement, forwardRef, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 // Frozen empty params/search so the default context value has a stable reference (no needless re-renders).
 const EMPTY_PARAMS = Object.freeze({});
@@ -73,6 +75,24 @@ export function useParams() {
 export function useSearch() {
     return useContext(RouterContext).search;
 }
+const NO_MATCHES = Object.freeze([]);
+/**
+ * The rendered chain, outermost layout first and the page last: each module's `id`, the URL
+ * `pathname` it wraps, its `params` and loader `data`, and its `handle` export. The same list on the
+ * server and in the browser, so a layout can render breadcrumbs or read a flag the page exports:
+ *
+ * ```tsx
+ * export const handle = { crumb: "Settings" } // in a page or a layout
+ * // in a layout above it:
+ * const crumbs = useMatches().flatMap((m) => (m.handle as { crumb?: string } | undefined)?.crumb ?? [])
+ * ```
+ *
+ * Empty outside a nifra route tree.
+ */
+export function useMatches() {
+    const props = useContext(RouterContext).renderProps;
+    return useMemo(() => (props === undefined ? NO_MATCHES : chainMatches(props)), [props]);
+}
 /** The current {@link Location} (`pathname`/`search`/`hash`), derived from the router context. */
 export function useLocation() {
     const { path } = useContext(RouterContext);
@@ -204,7 +224,7 @@ function isPlainLeftClick(event, target) {
  * 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) {
+export const Link = forwardRef(function Link({ to, replace, prefetch, onClick, target, ...rest }, ref) {
     const handleClick = (event) => {
         onClick?.(event);
         if (event.defaultPrevented)
@@ -217,7 +237,14 @@ export const Link = forwardRef(function Link({ to, replace, onClick, target, ...
         event.preventDefault();
         navigate(to, { replace: replace === true });
     };
-    return createElement("a", { ...rest, href: to, target, onClick: handleClick, ref });
+    return createElement("a", {
+        ...rest,
+        href: to,
+        target,
+        onClick: handleClick,
+        ref,
+        ...(prefetch !== undefined ? { "data-nifra-prefetch": prefetch } : {}),
+    });
 });
 /** Normalize a pathname for comparison: optional case-fold + drop a single trailing slash (but keep a
  * bare `"/"`). */

package/dist/router.js.map

@@ -1 +1 @@
-{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,mFAAmF;AACnF,qEAAqE;AACrE,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,eAAe,GAChB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAGL,aAAa,EACb,aAAa,EACb,UAAU,EAGV,WAAW,EACX,UAAU,EACV,SAAS,EACT,OAAO,EACP,MAAM,EACN,QAAQ,GACT,MAAM,OAAO,CAAA;AAuBd,2GAA2G;AAC3G,MAAM,YAAY,GAAqC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AACxE,MAAM,YAAY,GAAsC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AAEzE;;;;;;;;;;;4DAW4D;AAC5D,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAA;AACxE,MAAM,WAAW,GAAG,UAEnB,CAAA;AACD,MAAM,CAAC,MAAM,aAAa,GACxB,WAAW,CAAC,mBAAmB,CAAC;IAChC,aAAa,CAAqB;QAChC,MAAM,EAAE,YAAY;QACpB,IAAI,EAAE,EAAE;QACR,MAAM,EAAE,YAAY;QACpB,OAAO,EAAE,KAAK;KACf,CAAC,CAAA;AACJ,WAAW,CAAC,mBAAmB,CAAC,GAAG,aAAa,CAAA;AAEhD;iCACiC;AACjC,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC3B,OAAO,CAAC,KAAK,CAAC,CAAC;QACb,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE;QAChC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS;IAGvB,OAAO,UAAU,CAAC,aAAa,CAAC,CAAC,MAAqB,CAAA;AACxD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS;IAGvB,OAAO,UAAU,CAAC,aAAa,CAAC,CAAC,MAEN,CAAA;AAC7B,CAAC;AAWD,kGAAkG;AAClG,MAAM,UAAU,WAAW;IACzB,MAAM,EAAE,IAAI,EAAE,GAAG,UAAU,CAAC,aAAa,CAAC,CAAA;IAC1C,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;QAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAA;IACvC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;AACZ,CAAC;AAcD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,aAAa,CAAC,CAAA;IAC1D,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,OAAO;QACP,KAAK,EAAE,OAAO,CAAC,CAAC,CAAE,SAAmB,CAAC,CAAC,CAAE,MAAgB;QACzD,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;KAC5C,CAAC,EACF,CAAC,OAAO,EAAE,WAAW,CAAC,CACvB,CAAA;AACH,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,UAAU;IACxB,OAAO,UAAU,CAAC,aAAa,CAAC,CAAC,OAAO,CAAA;AAC1C,CAAC;AAED;;;8CAG8C;AAC9C,MAAM,UAAU,WAAW;IACzB,OAAO,WAAW,CAAC,CAAC,EAAyC,EAAE,OAAyB,EAAE,EAAE;QAC1F,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAA;QACrC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAM;QAClC,MAAM,QAAQ,GAAG,eAAe,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;QAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IACzC,CAAC,EAAE,EAAE,CAAqB,CAAA;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,UAAU,CAAC,WAAsC;IAC/D,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAU,YAAY,CAAC,CAAA;IAC7D,oGAAoG;IACpG,wGAAwG;IACxG,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC,CAAA;IAC1C,cAAc,CAAC,OAAO,GAAG,WAAW,CAAA;IACpC,sGAAsG;IACtG,wGAAwG;IACxG,SAAS,CACP,GAAG,EAAE,CACH,eAAe,CAAC,CAAC,IAAI,EAAE,EAAE;QACvB,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAA;QACtC,OAAO,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;IAChE,CAAC,EAAE,UAAU,CAAC,EAChB,EAAE,CACH,CAAA;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAKD,SAAS,cAAc,CAAC,IAAsB;IAC5C,IAAI,IAAI,YAAY,eAAe;QAAE,OAAO,IAAI,CAAA;IAChD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,CAAA;IAC9D,MAAM,GAAG,GAAG,IAAI,eAAe,EAAE,CAAA;IACjC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;;YACpE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAe,CAAC,CAAA;IACpC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,EAAE,IAAI,EAAE,GAAG,UAAU,CAAC,aAAa,CAAC,CAAA;IAC1C,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAC5C,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IACzE,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAC9B,MAAM,eAAe,GAAG,WAAW,CACjC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE;QAChB,MAAM,QAAQ,GAAG,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QACtF,MAAM,EAAE,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAA;QAC9C,QAAQ,CAAC,QAAQ,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAA;IAC3D,CAAC,EACD,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAC7B,CAAA;IACD,OAAO,CAAC,YAAY,EAAE,eAAe,CAAU,CAAA;AACjD,CAAC;AAED;+FAC+F;AAC/F,SAAS,gBAAgB,CAAC,KAAiB,EAAE,MAA0B;IACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACpC,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAClF,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,OAAO,CAAA;AACpE,CAAC;AAUD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,UAAU,CAA+B,SAAS,IAAI,CACxE,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,EACzC,GAAG;IAEH,MAAM,WAAW,GAAG,CAAC,KAAoC,EAAQ,EAAE;QACjE,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;QAChB,IAAI,KAAK,CAAC,gBAAgB;YAAE,OAAM,CAAC,0CAA0C;QAC7E,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC;YAAE,OAAM,CAAC,oCAAoC;QACjF,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAA;QACrC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAM,CAAC,oDAAoD;QACvF,KAAK,CAAC,cAAc,EAAE,CAAA;QACtB,QAAQ,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC,CAAA;IAC7C,CAAC,CAAA;IACD,OAAO,aAAa,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAA;AACrF,CAAC,CAAC,CAAA;AAuBF;kBACkB;AAClB,SAAS,aAAa,CAAC,QAAgB,EAAE,aAAsB;IAC7D,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAA;IAC/D,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,UAAU,CAAkC,SAAS,OAAO,CACjF,EAAE,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAC/D,GAAG;IAEH,MAAM,EAAE,QAAQ,EAAE,GAAG,WAAW,EAAE,CAAA;IAClC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,aAAa,CAAC,CAAA;IAC1D,MAAM,EAAE,GAAG,aAAa,KAAK,IAAI,CAAA;IACjC,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;IAC3C,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;IACxD,MAAM,QAAQ,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACnF,kGAAkG;IAClG,uDAAuD;IACvD,MAAM,aAAa,GACjB,OAAO,IAAI,WAAW,KAAK,SAAS;QAClC,CAAC,CAAC,aAAa,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;QACpD,CAAC,CAAC,SAAS,CAAA;IACf,MAAM,SAAS,GACb,aAAa,KAAK,SAAS;QAC3B,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,KAAK,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAA;IAClF,MAAM,WAAW,GAAuB,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;IAC/D,MAAM,iBAAiB,GAAG,OAAO,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAC9F,MAAM,aAAa,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;IAC9E,MAAM,gBAAgB,GAAG,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;IAC1F,OAAO,aAAa,CAClB,IAAI,EACJ;QACE,GAAG,IAAI;QACP,EAAE;QACF,GAAG;QACH,GAAG,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,6FAA6F;QAC7F,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;KAC9C,EACD,gBAAgB,CACjB,CAAA;AACH,CAAC,CAAC,CAAA;AAEF;4GAC4G;AAC5G,SAAS,aAAa,CAAC,OAAe,EAAE,MAAc;IACpD,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,IAAI,CAAA;IACnC,OAAO,OAAO,CAAC,UAAU,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,CAAC,CAAA;AAChE,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,EAAE,EAAE,EAAE,OAAO,EAAiB;IACrD,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAC9B,SAAS,CAAC,GAAG,EAAE;QACb,QAAQ,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC,CAAA;IAC7C,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAA;IAC3B,OAAO,IAAI,CAAA;AACb,CAAC"}
+{"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": "3.5.0",
+  "version": "4.0.0",
   "description": "React render adapter for @nifrajs/web - SSR + hydration (Bun-native JSX, no Babel).",
   "keywords": [
     "bun",
@@ -14,6 +14,9 @@
     "full-stack"
   ],
   "type": "module",
+  "nifra": {
+    "environment": "library"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -58,6 +61,11 @@
       "types": "./dist/i18n.d.ts",
       "default": "./dist/i18n.js"
     },
+    "./auth": {
+      "bun": "./src/auth.ts",
+      "types": "./dist/auth.d.ts",
+      "default": "./dist/auth.js"
+    },
     "./image": {
       "bun": "./src/image.ts",
       "types": "./dist/image.d.ts",
@@ -87,10 +95,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/core": "3.5.0",
-    "@nifrajs/i18n": "3.5.0",
-    "@nifrajs/image": "3.5.0",
-    "@nifrajs/web": "3.5.0"
+    "@nifrajs/core": "4.0.0",
+    "@nifrajs/authjs": "4.0.0",
+    "@nifrajs/i18n": "4.0.0",
+    "@nifrajs/image": "4.0.0",
+    "@nifrajs/web": "4.0.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/auth.ts

@@ -0,0 +1,128 @@
+/**
+ * `@nifrajs/web-react/auth` - React bindings for `@nifrajs/authjs`. `<AuthSessionProvider>`
+ * seeds the subtree with a session (from a loader on the server, refreshed in the browser) and
+ * `useAuthSession()` reads it; `signIn`/`signOut` delegate to the shared client. Imports only
+ * `react` + `@nifrajs/authjs/client`; no JSX (the package builds with plain `tsc`).
+ */
+import {
+  type AuthClient,
+  createAuthClient,
+  type Session,
+  type SignInOptions,
+  type SignOutOptions,
+} from "@nifrajs/authjs/client"
+import {
+  createContext,
+  createElement,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react"
+
+export type { Session }
+export type AuthStatus = "loading" | "authenticated" | "unauthenticated"
+
+export interface AuthSession {
+  readonly status: AuthStatus
+  readonly session: Session | null
+  /** Re-read the session from the server (after an out-of-band change, for example). */
+  readonly refresh: () => Promise<void>
+  readonly signIn: (providerId: string, options?: SignInOptions) => Promise<void>
+  readonly signOut: (options?: SignOutOptions) => Promise<void>
+}
+
+const AuthSessionContext = createContext<AuthSession | null>(null)
+
+export interface AuthSessionProviderProps {
+  /** Shared client (base path, custom fetch). Default `createAuthClient()`. */
+  readonly client?: AuthClient
+  /** SSR seed from a loader (`await getSession(request, config)`). `undefined` (default) fetches
+   * on mount instead - the subtree renders `loading` until it resolves. */
+  readonly initialSession?: Session | null
+  readonly children?: ReactNode
+}
+
+function seededStatus(seed: Session | null | undefined): AuthStatus {
+  return seed === undefined ? "loading" : seed === null ? "unauthenticated" : "authenticated"
+}
+
+/** Provide the Auth.js session to the subtree. Memoized on client + seed; refresh re-reads. A new
+ * `initialSession` (a loader re-run on navigation) replaces the session, as a remount would. */
+export function AuthSessionProvider(props: AuthSessionProviderProps): ReactNode {
+  const client = useMemo(() => props.client ?? createAuthClient(), [props.client])
+  const [seed, setSeed] = useState(props.initialSession)
+  const [status, setStatus] = useState<AuthStatus>(seededStatus(props.initialSession))
+  const [session, setSession] = useState<Session | null>(props.initialSession ?? null)
+  if (seed !== props.initialSession) {
+    // A render-phase update: React re-runs this component before any child sees the old session.
+    setSeed(props.initialSession)
+    setStatus(seededStatus(props.initialSession))
+    setSession(props.initialSession ?? null)
+  }
+  const refresh = useMemo(() => {
+    return async (): Promise<void> => {
+      try {
+        const next = await client.getSession()
+        setSession(next)
+        setStatus(next === null ? "unauthenticated" : "authenticated")
+      } catch {
+        // A failed session read must fail closed as anonymous; leaving "loading" can strand the
+        // subtree in an auth-pending state and make protected UI appear available by omission.
+        setSession(null)
+        setStatus("unauthenticated")
+      }
+    }
+  }, [client])
+  useEffect(() => {
+    let live = true
+    if (props.initialSession === undefined) {
+      void client.getSession().then(
+        (next) => {
+          if (!live) return
+          setSession(next)
+          setStatus(next === null ? "unauthenticated" : "authenticated")
+        },
+        () => {
+          // Treat an unavailable session endpoint as anonymous rather than keeping auth state
+          // pending indefinitely or exposing stale authenticated UI.
+          if (!live) return
+          setSession(null)
+          setStatus("unauthenticated")
+        },
+      )
+    }
+    return () => {
+      live = false
+    }
+  }, [client, props.initialSession])
+  const value = useMemo<AuthSession>(
+    () => ({
+      status,
+      session,
+      refresh,
+      signIn: (providerId, options) => client.signIn(providerId, options),
+      signOut: async (options) => {
+        await client.signOut(options)
+        // The server ended the session: the subtree must not go on showing it, whether a redirect is
+        // pending or `redirect: false` keeps the page.
+        setSession(null)
+        setStatus("unauthenticated")
+      },
+    }),
+    [status, session, refresh, client],
+  )
+  return createElement(AuthSessionContext.Provider, { value }, props.children)
+}
+
+/** Read the Auth.js session (`{ status, session }`). Throws if no `<AuthSessionProvider>` is above. */
+export function useAuthSession(): AuthSession {
+  const session = useContext(AuthSessionContext)
+  if (session === null) {
+    throw new Error(
+      "[nifra/web-react] useAuthSession() must be used within an <AuthSessionProvider>",
+    )
+  }
+  return session
+}

package/src/client.ts

@@ -1,7 +1,4 @@
 import type { MountRouterOptions, RenderProps } from "@nifrajs/web"
-// `/client`, not the root: the root's graph carries the server, and Vite's dev server evaluates it
-// instead of tree-shaking it - which broke hydration before the browser ran a line of app code.
-import { searchOfChain } from "@nifrajs/web/client"
 /**
  * @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
@@ -13,6 +10,7 @@ import { createElement, type FunctionComponent, useSyncExternalStore } from "rea
 import { hydrateRoot } from "react-dom/client"
 import { compose } from "./compose.ts"
 import { setMountedRouter } from "./fetcher.ts"
+import { routeProps } from "./route-props.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`.
@@ -58,29 +56,16 @@ export const hydrationAssuranceHook = Object.freeze({
  * SSR markup on hydration.
  */
 export function mountRouter(options: MountRouterOptions): void {
-  const { router, routes, searchSchemas, container } = options
+  const { router, routes, searchSchemas, matchChains, container } = options
   setMountedRouter(router) // expose it to useFetcher/useFetchers (same page, client-only)
+  // What the server rendered. React hydrates against THIS, whatever the store says by the time it gets
+  // to the component - hydration is scheduled, and a store that moved on first (a client loader that
+  // answered, a held `ssr = false` page released) would otherwise hydrate a tree the markup never had.
+  // React then re-renders with the live snapshot on its own.
+  const hydrated = router.snapshot()
   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 -
-      // sourced from router state here, matching the SSR render's request-derived values on hydration.
-      params: state.params,
-      path: state.path,
-      search: searchOfChain(searchSchemas?.[state.routeId] ?? [], rawSearch),
-      // The in-flight submission (for optimistic UI) - spread only when present.
-      ...(state.submission ? { submission: state.submission } : {}),
-      ...(state.boundaries !== undefined ? { boundaries: state.boundaries } : {}),
-    })
+    const state = useSyncExternalStore(router.subscribe, router.snapshot, () => hydrated)
+    return compose(routes[state.routeId] ?? [], routeProps(state, searchSchemas, matchChains))
   }
   const onRecoverableError = assuranceError()
   hydrateRoot(

package/src/compose.ts

@@ -46,6 +46,7 @@ export function compose(chain: readonly unknown[], props: RenderProps): ReactNod
         search: props.search ?? EMPTY_SEARCH,
         pending: props.pending ?? false,
         pendingPath: props.pendingPath,
+        renderProps: props,
       },
     },
     node,

package/src/i18n.ts

@@ -5,28 +5,40 @@
  * 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"
+import {
+  createFormatter,
+  type Formatter,
+  type FormatterOptions,
+  type MessageKey,
+  type RegisteredMessages,
+  type Translation,
+} from "@nifrajs/i18n"
+import { type RichChunks, type RichRenderer, renderRich } from "@nifrajs/i18n/rich"
+import { createContext, createElement, Fragment, type ReactNode, useContext, useMemo } from "react"
 
 const I18nContext = createContext<Formatter | null>(null)
 
-export interface I18nProviderProps {
+export interface I18nProviderProps extends FormatterOptions {
   readonly locale: string
-  readonly messages: Messages
+  /** The catalog for `locale`, checked against the registered catalog type when one is declared. */
+  readonly messages: Translation
   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. */
+/** Provide a {@link Formatter} (built from `locale` + `messages`, with the optional `fallback`,
+ * `onMissing`, `timeZone` and `numberingSystem` of `createFormatter`) to the subtree. Memoized
+ * on those props, so switching locale rebuilds it and re-renders consumers; formatters are cached by
+ * catalog identity, so an inline `fallback={[en]}` still yields the same instance. */
 export function I18nProvider(props: I18nProviderProps): ReactNode {
+  const { locale, messages, fallback, onMissing, timeZone, numberingSystem } = props
   const formatter = useMemo(
-    () => createFormatter(props.locale, props.messages),
-    [props.locale, props.messages],
+    () => createFormatter(locale, messages, { fallback, onMissing, timeZone, numberingSystem }),
+    [locale, messages, fallback, onMissing, timeZone, numberingSystem],
   )
   return createElement(I18nContext.Provider, { value: formatter }, props.children)
 }
 
-/** Read the current {@link Formatter} (`{ locale, t, n, d }`). Throws if no `<I18nProvider>` is above. */
+/** Read the current {@link Formatter} (`{ locale, t, get, n, d }`). Throws if no `<I18nProvider>` is above. */
 export function useT(): Formatter {
   const formatter = useContext(I18nContext)
   if (formatter === null) {
@@ -34,3 +46,31 @@ export function useT(): Formatter {
   }
   return formatter
 }
+
+/** Tag handlers for {@link rich}, by tag name: each receives its tag's content as one node. */
+export type RichTags = Readonly<Record<string, (content: ReactNode) => ReactNode>>
+
+// Children passed as arguments, not an array, so React asks for no keys.
+const join = (chunks: RichChunks<ReactNode>): ReactNode =>
+  chunks.length === 0
+    ? null
+    : chunks.length === 1
+      ? chunks[0]
+      : createElement(Fragment, null, ...chunks)
+const REACT_RICH: RichRenderer<ReactNode> = { join, lineBreak: () => createElement("br") }
+
+/**
+ * The message at `key` with its tags rendered by `tags`, as React nodes - no HTML, no
+ * `dangerouslySetInnerHTML`. `"Read the <link>terms</link>"` with
+ * `{ link: (content) => <a href="/terms">{content}</a> }` renders the link around "terms"; a tag with
+ * no handler renders its content as text, `<br/>` is a `<br>`, and interpolated values are always
+ * text. See `@nifrajs/i18n/rich`.
+ */
+export function rich<M extends object = RegisteredMessages>(
+  formatter: Formatter<M>,
+  key: MessageKey<M>,
+  tags?: RichTags,
+  vars?: Readonly<Record<string, unknown>>,
+): ReactNode {
+  return renderRich(REACT_RICH, formatter, key, tags, vars)
+}

package/src/index.ts

@@ -6,6 +6,7 @@ import type { RenderAdapter } from "@nifrajs/web"
  */
 import { compose } from "./compose.ts"
 import { reactDomServer } from "./react-dom-server.ts"
+import { explainRenderError } from "./render-error.ts"
 
 /** The React server render adapter - pass to @nifrajs/web's `renderPage`. */
 export const reactAdapter: RenderAdapter = {
@@ -19,14 +20,25 @@ export const reactAdapter: RenderAdapter = {
   // renderPage awaits it.
   async renderToString(chain, props) {
     const { renderToString } = await reactDomServer()
-    return renderToString(compose(chain, props))
+    try {
+      return renderToString(compose(chain, props))
+    } catch (error) {
+      throw explainRenderError(error)
+    }
   },
-  async renderToStream(chain, props) {
+  async renderToStream(chain, props, options) {
     // 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).
+    // The nonce reaches the inline runtime React streams to reveal each resolved boundary.
     const { renderToReadableStream } = await reactDomServer()
-    return renderToReadableStream(compose(chain, props))
+    try {
+      return await (options?.nonce === undefined
+        ? renderToReadableStream(compose(chain, props))
+        : renderToReadableStream(compose(chain, props), { nonce: options.nonce }))
+    } catch (error) {
+      throw explainRenderError(error)
+    }
   },
   // React reconciles against the existing DOM on hydrate, so no per-document bootstrap
   // script is needed (contrast Solid's generateHydrationScript) - the seam allows both.

package/src/react-dom-server.ts

@@ -29,7 +29,10 @@ import type { ReactNode } from "react"
  * 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>>
+  renderToReadableStream(
+    node: ReactNode,
+    options?: { readonly nonce?: string },
+  ): Promise<ReadableStream<Uint8Array>>
 }
 
 interface RuntimeProcess {

package/src/render-error.ts

@@ -0,0 +1,18 @@
+/** A hook read a null dispatcher: the component's React is not the one the renderer set up. JSC and V8
+ * word the null dereference differently; the property read is always a hook. */
+const NO_DISPATCHER =
+  /ReactSharedInternals\.H\.|resolveDispatcher\(\)\.|Cannot read properties of null \(reading 'use[A-Za-z]*'\)/
+
+/** Name the cause of a null-dispatcher crash. The app-root check in ./react-dom-server catches a
+ * renderer on the wrong copy; this covers a component that brings its own (a linked package's). */
+export function explainRenderError(error: unknown): unknown {
+  if (!(error instanceof TypeError) || !NO_DISPATCHER.test(error.message)) return error
+  return new Error(
+    "[nifra/web-react] a component called a React hook with no dispatcher, so two copies of React " +
+      "reached SSR: the one react-dom renders with, and another the component imports (often a linked " +
+      "package's own node_modules). Dedupe react to one physical copy: `nifra check` names the " +
+      "importer of each, and the package.json `nifra.singleCopy` declaration redirects them. " +
+      `See https://nifra.dev/docs/troubleshooting. (${error.message})`,
+    { cause: error },
+  )
+}

package/src/route-props.ts

@@ -0,0 +1,37 @@
+import type { MountRouterOptions, RenderProps, RouterState } from "@nifrajs/web"
+// `/client`, not the root: the root's graph carries the server, and Vite's dev server evaluates it
+// instead of tree-shaking it - which broke hydration before the browser ran a line of app code.
+import { searchOfChain } from "@nifrajs/web/client"
+
+/** The client half of the server's `RenderProps`, so the first render matches the SSR markup. */
+export function routeProps(
+  state: RouterState,
+  searchSchemas: MountRouterOptions["searchSchemas"],
+  matchChains?: MountRouterOptions["matchChains"],
+): RenderProps {
+  const matchChain = matchChains?.[state.routeId]
+  // 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 {
+    data: state.data,
+    // Each layout's own loader data. Without it a layout renders `data: null` on the client while the
+    // server rendered it with its data - a hydration mismatch on the first paint.
+    ...(state.layoutData !== undefined ? { layoutData: state.layoutData } : {}),
+    actionData: state.actionData,
+    pending: state.pending,
+    ...(state.pendingPath !== undefined ? { pendingPath: state.pendingPath } : {}),
+    // `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,
+    search: searchOfChain(searchSchemas?.[state.routeId] ?? [], rawSearch),
+    // The in-flight submission (for optimistic UI) - spread only when present.
+    ...(state.submission ? { submission: state.submission } : {}),
+    ...(state.boundaries !== undefined ? { boundaries: state.boundaries } : {}),
+    // The chain `useMatches` reports - the server passed the same one to the SSR render.
+    ...(matchChain !== undefined ? { matchChain } : {}),
+  }
+}

package/src/router.ts

@@ -22,6 +22,9 @@ import type {
   NavigateFunction,
   NavigateOptions,
   NavigateTargetInput,
+  PrefetchMode,
+  RenderProps,
+  UIMatch,
 } from "@nifrajs/web"
 // `/client`, not the root - these are DOM values, and the root's graph carries the
 // server, which Vite's dev server evaluates rather than tree-shakes.
@@ -31,6 +34,8 @@ import {
   registerBlocker,
   resolveNavigate,
 } from "@nifrajs/web/client"
+// Its own subpath, so an app that never calls `useMatches` bundles none of it.
+import { chainMatches } from "@nifrajs/web/internal/matches-runtime"
 import {
   type AnchorHTMLAttributes,
   type CSSProperties,
@@ -47,7 +52,7 @@ import {
   useState,
 } from "react"
 
-export type { Blocker, BlockerFunction, BlockerState, NavigateFunction }
+export type { Blocker, BlockerFunction, BlockerState, NavigateFunction, PrefetchMode, UIMatch }
 
 /** The current route the routing hooks read. Provided by `compose` on SSR + client mount alike. */
 export interface RouterContextValue {
@@ -66,6 +71,8 @@ export interface RouterContextValue {
   /** The `pathname + search` a navigation is transitioning TO while `pending` (`undefined` when idle or
    * during a same-route revalidation). Powers {@link NavLink}'s per-link `isPending`. */
   readonly pendingPath?: string | undefined
+  /** The render's props, which {@link useMatches} derives the matches from. */
+  readonly renderProps?: RenderProps | undefined
 }
 
 // Frozen empty params/search so the default context value has a stable reference (no needless re-renders).
@@ -141,6 +148,26 @@ export function useSearch<
     : Record<string, unknown>
 }
 
+const NO_MATCHES: readonly UIMatch[] = Object.freeze([])
+
+/**
+ * The rendered chain, outermost layout first and the page last: each module's `id`, the URL
+ * `pathname` it wraps, its `params` and loader `data`, and its `handle` export. The same list on the
+ * server and in the browser, so a layout can render breadcrumbs or read a flag the page exports:
+ *
+ * ```tsx
+ * export const handle = { crumb: "Settings" } // in a page or a layout
+ * // in a layout above it:
+ * const crumbs = useMatches().flatMap((m) => (m.handle as { crumb?: string } | undefined)?.crumb ?? [])
+ * ```
+ *
+ * Empty outside a nifra route tree.
+ */
+export function useMatches(): readonly UIMatch[] {
+  const props = useContext(RouterContext).renderProps
+  return useMemo(() => (props === undefined ? NO_MATCHES : chainMatches(props)), [props])
+}
+
 /** The parsed current location. `hash` is always `""` - the fragment is client-only and never reaches
  * the router state / server, so exposing a live hash would hydration-mismatch; read `window.location.hash`
  * directly (in an effect) if you truly need it. */
@@ -307,12 +334,16 @@ function isPlainLeftClick(event: MouseEvent, target: string | undefined): boolea
   return target === undefined || target === "" || target === "_self"
 }
 
-/** {@link Link} props: every `<a>` attribute except `href` (set from `to`), plus `to` + `replace`. */
+/** {@link Link} props: every `<a>` attribute except `href` (set from `to`), plus `to`, `replace` and
+ * `prefetch`. */
 export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
   /** Same-origin destination path (e.g. `/users/7?tab=posts`). Rendered as the `<a href>`. */
   readonly to: string
   /** Replace the current history entry instead of pushing. */
   readonly replace?: boolean
+  /** When the link warms its route ahead of a click - rendered as `data-nifra-prefetch`. Unset, the
+   * nearest ancestor's `data-nifra-prefetch` decides, else `intent` (hover or focus). */
+  readonly prefetch?: PrefetchMode
 }
 
 /**
@@ -322,7 +353,7 @@ export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>,
  * document-level click handler sees `defaultPrevented` and stands down - exactly one navigation.
  */
 export const Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
-  { to, replace, onClick, target, ...rest },
+  { to, replace, prefetch, onClick, target, ...rest },
   ref,
 ) {
   const handleClick = (event: MouseEvent<HTMLAnchorElement>): void => {
@@ -334,7 +365,14 @@ export const Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
     event.preventDefault()
     navigate(to, { replace: replace === true })
   }
-  return createElement("a", { ...rest, href: to, target, onClick: handleClick, ref })
+  return createElement("a", {
+    ...rest,
+    href: to,
+    target,
+    onClick: handleClick,
+    ref,
+    ...(prefetch !== undefined ? { "data-nifra-prefetch": prefetch } : {}),
+  })
 })
 
 /** The state a {@link NavLink}'s function-form `className`/`style`/`children` receive. */