@nifrajs/web-react 2.11.0 → 2.12.0

package/dist/client.d.ts

@@ -1,7 +1,15 @@
 import type { MountRouterOptions, RenderProps } from "@nifrajs/web";
 export { errorBoundary } from "./error.js";
 /** Hydrate a server-rendered React layout `chain` (with the loader `props`) inside `container`. */
-export declare function hydrate(chain: readonly unknown[], props: RenderProps, container: unknown): void;
+export interface HydrationAssuranceOptions {
+    readonly onRecoverableError?: (error: unknown, info?: unknown) => void;
+}
+export declare function hydrate(chain: readonly unknown[], props: RenderProps, container: unknown, options?: HydrationAssuranceOptions): void;
+/** Testing hook used by verification runners to observe React's recoverable errors and identity. */
+export declare const hydrationAssuranceHook: Readonly<{
+    framework: "react";
+    runtimeIdentity: () => object;
+}>;
 /**
  * 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

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAiBnE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,mGAAmG;AACnG,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAE/F;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAyB7D"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAkBnE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,mGAAmG;AACnG,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CACvE;AAaD,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE,yBAAyB,GAClC,IAAI,CAIN;AAED,oGAAoG;AACpG,eAAO,MAAM,sBAAsB;;2BAEZ,MAAM;EAC3B,CAAA;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CA8B7D"}

package/dist/client.js

@@ -7,6 +7,7 @@ import { searchOfChain } from "@nifrajs/web/client";
  * `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 * as React from "react";
 import { createElement, useSyncExternalStore } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { compose } from "./compose.js";
@@ -14,10 +15,27 @@ import { setMountedRouter } from "./fetcher.js";
 // 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.js";
-/** Hydrate a server-rendered React layout `chain` (with the loader `props`) inside `container`. */
-export function hydrate(chain, props, container) {
-    hydrateRoot(container, compose(chain, props));
+function assuranceError() {
+    const value = globalThis[Symbol.for("nifra.hydration.assurance")];
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const callback = value.onRecoverableError;
+    return typeof callback === "function"
+        ? callback
+        : undefined;
 }
+export function hydrate(chain, props, container, options) {
+    const onRecoverableError = options?.onRecoverableError ?? assuranceError();
+    if (onRecoverableError === undefined)
+        hydrateRoot(container, compose(chain, props));
+    else
+        hydrateRoot(container, compose(chain, props), { onRecoverableError });
+}
+/** Testing hook used by verification runners to observe React's recoverable errors and identity. */
+export const hydrationAssuranceHook = Object.freeze({
+    framework: "react",
+    runtimeIdentity: () => React,
+});
 /**
  * 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
@@ -48,6 +66,7 @@ export function mountRouter(options) {
             ...(state.submission ? { submission: state.submission } : {}),
         });
     };
-    hydrateRoot(container, createElement(Router));
+    const onRecoverableError = assuranceError();
+    hydrateRoot(container, createElement(Router), ...(onRecoverableError === undefined ? [] : [{ onRecoverableError }]));
 }
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,mGAAmG;AACnG,gGAAgG;AAChG,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAA0B,oBAAoB,EAAE,MAAM,OAAO,CAAA;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C,wGAAwG;AACxG,+FAA+F;AAC/F,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,mGAAmG;AACnG,MAAM,UAAU,OAAO,CAAC,KAAyB,EAAE,KAAkB,EAAE,SAAkB;IACvF,WAAW,CAAC,SAAoB,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,OAAO,CAAA;IAC5D,gBAAgB,CAAC,MAAM,CAAC,CAAA,CAAC,+DAA+D;IACxF,MAAM,MAAM,GAAsB,GAAG,EAAE;QACrC,MAAM,KAAK,GAAG,oBAAoB,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;QACtF,qGAAqG;QACrG,sGAAsG;QACtG,oCAAoC;QACpC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QACjC,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACrD,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE;YAC1C,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,+FAA+F;YAC/F,iGAAiG;YACjG,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,aAAa,CAAC,aAAa,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC;YACtE,2EAA2E;YAC3E,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9D,CAAC,CAAA;IACJ,CAAC,CAAA;IACD,WAAW,CAAC,SAAoB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;AAC1D,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@nifrajs/web-react",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "React render adapter for @nifrajs/web - SSR + hydration (Bun-native JSX, no Babel).",
   "keywords": [
     "bun",
     "typescript",
     "nifra",
-    "web-framework",
-    "full-stack",
-    "edge",
-    "ssr"
+    "react",
+    "ssr",
+    "hydration",
+    "streaming-ssr",
+    "render-adapter",
+    "full-stack"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -85,10 +87,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/core": "2.11.0",
-    "@nifrajs/i18n": "2.11.0",
-    "@nifrajs/image": "2.11.0",
-    "@nifrajs/web": "2.11.0"
+    "@nifrajs/core": "2.12.0",
+    "@nifrajs/i18n": "2.12.0",
+    "@nifrajs/image": "2.12.0",
+    "@nifrajs/web": "2.12.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/client.ts

@@ -8,6 +8,7 @@ import { searchOfChain } from "@nifrajs/web/client"
  * `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 * as React from "react"
 import { createElement, type FunctionComponent, useSyncExternalStore } from "react"
 import { hydrateRoot } from "react-dom/client"
 import { compose } from "./compose.ts"
@@ -18,10 +19,38 @@ import { setMountedRouter } from "./fetcher.ts"
 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))
+export interface HydrationAssuranceOptions {
+  readonly onRecoverableError?: (error: unknown, info?: unknown) => void
 }
 
+function assuranceError(): HydrationAssuranceOptions["onRecoverableError"] {
+  const value = (globalThis as unknown as Record<PropertyKey, unknown>)[
+    Symbol.for("nifra.hydration.assurance")
+  ]
+  if (typeof value !== "object" || value === null) return undefined
+  const callback = (value as { onRecoverableError?: unknown }).onRecoverableError
+  return typeof callback === "function"
+    ? (callback as HydrationAssuranceOptions["onRecoverableError"])
+    : undefined
+}
+
+export function hydrate(
+  chain: readonly unknown[],
+  props: RenderProps,
+  container: unknown,
+  options?: HydrationAssuranceOptions,
+): void {
+  const onRecoverableError = options?.onRecoverableError ?? assuranceError()
+  if (onRecoverableError === undefined) hydrateRoot(container as Element, compose(chain, props))
+  else hydrateRoot(container as Element, compose(chain, props), { onRecoverableError })
+}
+
+/** Testing hook used by verification runners to observe React's recoverable errors and identity. */
+export const hydrationAssuranceHook = Object.freeze({
+  framework: "react" as const,
+  runtimeIdentity: (): object => React,
+})
+
 /**
  * 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
@@ -52,5 +81,10 @@ export function mountRouter(options: MountRouterOptions): void {
       ...(state.submission ? { submission: state.submission } : {}),
     })
   }
-  hydrateRoot(container as Element, createElement(Router))
+  const onRecoverableError = assuranceError()
+  hydrateRoot(
+    container as Element,
+    createElement(Router),
+    ...(onRecoverableError === undefined ? [] : [{ onRecoverableError }]),
+  )
 }