@nifrajs/web 2.14.1 → 3.1.0

package/dist/index.js

@@ -8,7 +8,8 @@
  * of DOM types: it is pure server orchestration + string building.
  */
 import { NIFRA_BACKEND_MOUNT, } from "@nifrajs/core/mount";
-import { server, urlPartsOf } from "@nifrajs/core/server";
+import { isSameOriginPath, server, status as statusResult, urlPartsOf, } from "@nifrajs/core/server";
+import { boundaryDescriptors, resolveStaticBoundaries, startDynamicBoundaries, } from "./boundary.js";
 import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, defer, MAP_DEFERRED_SOURCE, ndjsonStream, prepareDeferred, } from "./deferred.js";
 import { isDraftEnabled } from "./draft.js";
 import { trustedHeadAttributes } from "./internal/head-attributes.js";
@@ -20,10 +21,11 @@ import { jsStringLiteral } from "./internal/js-string.js";
 import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.js";
 import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "./isr.js";
 import { generateLlmsTxt } from "./llms-txt.js";
-import { ACTION_GLOBAL, DATA_GLOBAL, LAYOUT_DATA_GLOBAL, ROOT_ATTRIBUTE, ROUTE_GLOBAL, } from "./render-seam.js";
+import { ACTION_GLOBAL, BOUNDARY_GLOBAL, DATA_GLOBAL, LAYOUT_DATA_GLOBAL, ROOT_ATTRIBUTE, ROUTE_GLOBAL, } from "./render-seam.js";
 import { createMatcher, DATA_HEADER, NAV_FROM_HEADER, PRERENDERED_GLOBAL, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, STATUS_HEADER, } from "./router.js";
 import { searchOf, searchOfChain } from "./search.js";
 // Draft / preview mode - a signed cookie that flips `ctx.draft` for loaders + bypasses ISR for editors.
+export { assertStaticBoundaryImports, boundaryDescriptors, boundaryModeKey, MemoryStaticBoundaryCache, resolveDynamicBoundaries, resolveStaticBoundaries, startDynamicBoundaries, } from "./boundary.js";
 export { DRAFT_COOKIE, disableDraft, enableDraft, isDraftEnabled, previewEndpoint, } from "./draft.js";
 // Font optimization - a CLS-safe `@font-face` generator + a preload `<link>` for self-hosted fonts.
 export { fontFace, fontPreload, } from "./fonts.js";
@@ -46,7 +48,7 @@ export { createClientRouter, createMatcher, DATA_HEADER, NAV_FROM_HEADER, REDIRE
 // Deferred loader data (`defer()` + the `Deferred<T>` type) - consumed by the adapter's `<Await>`.
 export { defer, mergeHeads, resolveMeta };
 export { assertRenderAdapterConformance, RenderAdapterConformanceError, } from "./conformance.js";
-export { ACTION_GLOBAL, DATA_GLOBAL, LAYOUT_DATA_GLOBAL, ROOT_ATTRIBUTE, ROUTE_GLOBAL, setSsrModuleLoader, ssrModuleLoader, } from "./render-seam.js";
+export { ACTION_GLOBAL, BOUNDARY_GLOBAL, DATA_GLOBAL, LAYOUT_DATA_GLOBAL, ROOT_ATTRIBUTE, ROUTE_GLOBAL, setSsrModuleLoader, ssrModuleLoader, } from "./render-seam.js";
 // The search-derivation primitive: parse a URL query, validate it against a route's `searchSchema`
 // (fail-closed to defaults), or return the raw parsed query when there is none. Both the server (loader
 // ctx + `renderPage`) and a client adapter mount call this with the same URL + schema, so the two sides
@@ -95,6 +97,17 @@ const SCRIPT_ESCAPE_MAP = {
 };
 const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body");
 const RESPONSE_RESULT = Symbol.for("nifra.response.result");
+/**
+ * A control-flow value that renders as plain data - what `redirect()` returns, and what core's
+ * `status(...)` returns. Recognized here rather than imported: core keeps its own predicate internal,
+ * and the registry symbol is the contract between them (two copies of core must still agree).
+ */
+const isResponseResult = (value) => typeof value === "object" &&
+    value !== null &&
+    value[RESPONSE_RESULT] === true &&
+    typeof value.toResponse === "function";
+/** A returned/thrown value that ends the request as-is: either shape of control-flow signal. */
+const isControlFlow = (value) => value instanceof Response || isResponseResult(value);
 /**
  * Server: render a full HTML document for a page - the adapter's hydration head + the SSR
  * markup (**streamed**) + the serialized loader data + the client module - as a `Response`.
@@ -107,7 +120,7 @@ export function renderPage(options) {
     return page instanceof Promise ? page.then((p) => p.toResponse()) : page.toResponse();
 }
 export function renderPageResult(options) {
-    const { adapter, chain, data, actionData, clientEntry, preload = [], styles = [], prerenderedPaths = [], revalidate, revalidateTags = [], routeId, status = 200, title = "nifra", head, rootId = "root", hydrate = true, islandScripts = [], nonce, headers: extraHeaders, } = options;
+    const { adapter, chain, data, actionData, clientEntry, preload = [], styles = [], prerenderedPaths = [], revalidate, revalidateTags = [], routeId, status = 200, title = "nifra", head, rootId = "root", hydrate = true, islandScripts = [], nonce, boundaries, headers: extraHeaders, } = options;
     if (nonce !== undefined && nonce.trim() === "") {
         throw new TypeError("[nifra/web] renderPage nonce must be non-empty when provided");
     }
@@ -138,11 +151,19 @@ export function renderPageResult(options) {
     const actionSplit = actionData === undefined
         ? undefined
         : prepareDeferred(actionData, deferred.length + layoutDeferred.length);
+    const boundarySplit = boundaries === undefined
+        ? undefined
+        : prepareDeferred(boundaries, deferred.length + layoutDeferred.length + (actionSplit?.deferred.length ?? 0));
     // On the common page-only path (no layout loader, no action) reuse `deferred` directly instead of
     // allocating a fresh spread array every request.
-    const allDeferred = layoutDeferred.length === 0 && actionSplit === undefined
+    const allDeferred = layoutDeferred.length === 0 && actionSplit === undefined && boundarySplit === undefined
         ? deferred
-        : [...deferred, ...layoutDeferred, ...(actionSplit ? actionSplit.deferred : [])];
+        : [
+            ...deferred,
+            ...layoutDeferred,
+            ...(actionSplit ? actionSplit.deferred : []),
+            ...(boundarySplit ? boundarySplit.deferred : []),
+        ];
     // Omitted entirely when no layout has a loader - a page-only app emits exactly what it did before.
     const layoutTail = options.layoutData === undefined
         ? ""
@@ -151,6 +172,9 @@ export function renderPageResult(options) {
     const action = actionSplit === undefined
         ? ""
         : `window.${ACTION_GLOBAL}=${serializeData(actionSplit.forClient)};`;
+    const boundaryTail = boundarySplit === undefined
+        ? ""
+        : `window.${BOUNDARY_GLOBAL}=${serializeData(boundarySplit.forClient)};`;
     const deferredRuntime = allDeferred.length > 0 ? `<script${nonceAttr}>${DEFERRED_RUNTIME}</script>` : "";
     // The regex only injects the CSP nonce into the (constant) hydration head; with no nonce it's a
     // no-op that still scans the whole script every request. Skip it on the common no-nonce path.
@@ -230,7 +254,7 @@ export function renderPageResult(options) {
     // Tail - the loader-data globals + the client module. Module scripts defer (run after parse), so
     // the data global + every streamed deferred resolution are set before the entry hydrates.
     const tailHtml = hydrate
-        ? `${slot.tailPre}${action}${slot.tailMid}${layoutTail}${slot.tailData}${serializeData(forClient)}${slot.tailPost}`
+        ? `${slot.tailPre}${action}${slot.tailMid}${layoutTail}${boundaryTail}${slot.tailData}${serializeData(forClient)}${slot.tailPost}`
         : slot.tailPost;
     const headers = { "content-type": "text/html; charset=utf-8" };
     // Caller-supplied headers (a terminal status page's `cache-control`, say). Applied before the
@@ -265,6 +289,9 @@ export function renderPageResult(options) {
         ...(options.layoutData !== undefined
             ? { layoutData: layoutSplits.map((split) => split.forComponent) }
             : {}),
+        ...(boundarySplit !== undefined
+            ? { boundaries: boundarySplit.forComponent }
+            : {}),
     };
     // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
     // whole document in one pass. Progressive streaming only benefits pages with deferred boundaries
@@ -376,26 +403,31 @@ function streamDocument(shell, stream, closeRoot, deferred, tail, enc, nonceAttr
     });
 }
 /** A same-origin destination is an absolute path: one leading `/`, but NOT `//` (protocol-relative →
- * another origin). Everything else (absolute URL with a scheme, `//host`, `javascript:`, a bare
- * relative `foo`) is treated as off-origin and requires `external: true`. */
-function isSameOriginPath(location) {
-    return location.startsWith("/") && !location.startsWith("//");
-}
+ * another origin), and nothing a URL parser resolves off-origin. Everything else (absolute URL with
+ * a scheme, `//host`, `javascript:`, a bare relative `foo`) requires `external: true`. The predicate
+ * lives in the kernel - see `isSameOriginPath` - so this gate and the auth guards' `redirectTo`
+ * cannot drift apart. */
 /**
- * Build a redirect `Response` - return it from a route `action` for the Post/Redirect/Get
- * pattern (POST mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit).
- * Defaults to 303 (See Other); pass `{ status: 307 }` or `{ status: 308 }` to preserve the method.
+ * Build a redirect - return it from a route `action` for the Post/Redirect/Get pattern (POST
+ * mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit). Defaults to 303
+ * (See Other); pass `{ status: 307 }` or `{ status: 308 }` to preserve the method.
  *
  * **Secure by default:** `location` must be a same-origin path (begins with `/`, not `//`). An
  * off-origin/absolute destination throws unless you pass `{ external: true }` - this closes the
  * open-redirect footgun of `return redirect(formData.get("next"))` on the no-JS (native-form) path,
- * which returns the action's `Response` verbatim.
+ * which serves the action's control-flow value verbatim.
+ *
+ * Returns a plain render, not a `Response`. A redirect is a status line and one header - the most
+ * body-less response there is - and building a `Response` for it costs the whole Web object plus, on
+ * Node, a stream drained back out. As data it renders on the same lane a handler's return takes.
+ * `redirect(...)` is still returned or thrown from exactly the same places; only `.status` /
+ * `.headers` are gone from the value, replaced by `options.headers` and the request's `c.set`.
  *
- * @param options redirect status and whether an off-origin destination is intentional.
+ * @param options redirect status, extra headers, and whether an off-origin destination is intentional.
  */
 export function redirect(location, options = {}) {
     if (options.external !== true && !isSameOriginPath(location)) {
-        throw new Error(`[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//"), or redirect(location, { external: true }) for a deliberate off-origin redirect. This guards against open redirects from unvalidated input.`);
+        throw new Error(`[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//", no backslash or control character), or redirect(location, { external: true }) for a deliberate off-origin redirect. This guards against open redirects from unvalidated input.`);
     }
     // Reject CR/LF in the Location explicitly - defense-in-depth (response splitting / header
     // injection). Spec-correct runtimes' Headers setter throws on CR/LF, but `external: true` lets
@@ -404,7 +436,9 @@ export function redirect(location, options = {}) {
     if (/[\r\n]/.test(location)) {
         throw new Error(`[nifra/web] redirect location contains a CR/LF character - refusing to emit a header-injecting redirect.`);
     }
-    return new Response(null, { status: options.status ?? 303, headers: { location } });
+    return statusResult(options.status ?? 303, undefined, {
+        headers: options.headers === undefined ? { location } : { ...options.headers, location },
+    });
 }
 /**
  * The signatures a **duplicate module instance** produces during SSR, across engines.
@@ -443,17 +477,34 @@ function withDuplicateInstanceHint(err) {
     return augmented;
 }
 /**
- * An action's `Response` passes straight through - except a redirect on a client-submit data
+ * An action's control-flow value passes straight through - except a redirect on a client-submit data
  * request: fetch would follow the 3xx into HTML the client can't use, so the redirect rides the
- * X-Nifra-Redirect header on a 204 and the client navigates. One conversion shared by the
- * returned- and thrown-Response paths, so `return redirect()` and `throw redirect()` agree.
+ * X-Nifra-Redirect header on a 204 and the client navigates. One conversion shared by the returned-
+ * and thrown- paths, so `return redirect()` and `throw redirect()` agree.
+ *
+ * Takes either shape: `redirect()` is a plain render, while a hand-rolled `new Response(...)` from an
+ * action still arrives as a `Response`. The rewrite stays on the lane its input was on - a plain
+ * redirect converts to a plain 204, and never materializes the `Response` it is replacing.
  */
-function actionResponse(response, isDataRequest) {
-    if (isDataRequest && response.status >= 300 && response.status < 400) {
-        const location = response.headers.get("location") ?? "/";
-        return new Response(null, { status: 204, headers: { [REDIRECT_HEADER]: location } });
+function actionResponse(result, isDataRequest) {
+    if (!isDataRequest)
+        return result;
+    if (isResponseResult(result)) {
+        const plain = result.plain;
+        // No `plain` means a carrier that only knows how to build a `Response` (not one of ours) - fall
+        // back rather than guess at its status.
+        if (plain === undefined)
+            return actionResponse(result.toResponse(), isDataRequest);
+        if (plain.status < 300 || plain.status >= 400)
+            return result;
+        const location = plain.headers?.location ?? "/";
+        return statusResult(204, undefined, { headers: { [REDIRECT_HEADER]: location } });
     }
-    return response;
+    if (result.status >= 300 && result.status < 400) {
+        const location = result.headers.get("location") ?? "/";
+        return statusResult(204, undefined, { headers: { [REDIRECT_HEADER]: location } });
+    }
+    return result;
 }
 /**
  * Narrow the route's params to the ones a layout owns.
@@ -1264,6 +1315,7 @@ export function createWebApp(options) {
             const draft = await draftFlag(c.req);
             let data;
             let layoutData;
+            let boundaryStates;
             let layoutModules;
             let layoutRetained = [];
             try {
@@ -1286,16 +1338,51 @@ export function createWebApp(options) {
                 const run = await runLayoutChain(route, ctx, validatedRetainedIndices(c.req, route, c.params));
                 layoutModules = run.modules;
                 layoutRetained = run.retained;
+                const boundaryDefinitions = [
+                    ...run.modules.flatMap((layout) => layout.boundaries ?? []),
+                    ...(mod.boundaries ?? []),
+                ];
+                if (boundaryDefinitions.length > 0)
+                    boundaryDescriptors(boundaryDefinitions);
+                const effectiveSearch = searchChainOf(run.modules, mod, c.req);
+                const boundaryBatch = boundaryDefinitions.length === 0
+                    ? undefined
+                    : startDynamicBoundaries(boundaryDefinitions, {
+                        request: c.req,
+                        params: c.params,
+                        api,
+                        env: c.env,
+                        draft,
+                        search: effectiveSearch,
+                        signal: c.req.signal,
+                    });
+                const staticBoundaryPromise = boundaryDefinitions.length === 0
+                    ? Promise.resolve(undefined)
+                    : resolveStaticBoundaries(boundaryDefinitions, { phase: "build", origin: originOf(c.req) }, options.staticBoundaryCache);
+                // Boundary data is attached as one Deferred marker per slot. The shell can render
+                // immediately with each slot pending, while the existing deferred protocol emits the first
+                // completed sibling independently instead of waiting for the slowest boundary.
                 // The page loader gets the EFFECTIVE search (layout chain + page, page-wins), now that the layout
                 // modules are loaded - so `ctx.search` includes a layout's shared keys (`?org`), matching `useSearch`.
-                const [pageData] = await Promise.all([
-                    mod.loader
-                        ? mod.loader({ ...ctx, search: searchChainOf(run.modules, mod, c.req) })
-                        : null,
+                const [pageData, , staticBoundaries] = await Promise.all([
+                    mod.loader ? mod.loader({ ...ctx, search: effectiveSearch }) : null,
                     run.pending, // a non-gate layout loader that rejects must still surface, not go unhandled
+                    staticBoundaryPromise,
                 ]);
                 data = pageData;
                 layoutData = run.layoutData;
+                if (boundaryBatch !== undefined) {
+                    const streamed = { ...boundaryBatch.initial, ...(staticBoundaries ?? {}) };
+                    for (const entry of boundaryBatch.pending) {
+                        const initial = streamed[entry.name];
+                        if (initial !== undefined)
+                            streamed[entry.name] = { ...initial, data: defer(entry.promise) };
+                    }
+                    boundaryStates = streamed;
+                }
+                else if (staticBoundaries !== undefined) {
+                    boundaryStates = staticBoundaries;
+                }
             }
             catch (err) {
                 // A terminal-status signal (`notFound()` / `gone()` / `statusPage(n)`) renders a boundary at
@@ -1303,10 +1390,11 @@ export function createWebApp(options) {
                 // is what keeps a hand-rolled `throw new Response(...)` served verbatim, as it always was.
                 if (isStatusSignal(err))
                     return renderStatusSignal(c.req, err);
-                // A thrown `Response` is a control-flow signal (a guard's `redirect(...)`, an explicit error
-                // response) - let it propagate to core, which returns it as-is. Real errors render the nearest
-                // `_error` boundary, if any; with none, rethrow (unchanged 500 behavior).
-                if (err instanceof Response)
+                // A thrown control-flow signal (a guard's `redirect(...)`, an explicit error response) - let
+                // it propagate to core, which renders it as-is, whether it is a plain render or a
+                // hand-rolled `Response`. Real errors render the nearest `_error` boundary, if any; with
+                // none, rethrow (unchanged 500 behavior).
+                if (isControlFlow(err))
                     throw err;
                 // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
                 if (options.onLoaderError !== undefined) {
@@ -1331,13 +1419,13 @@ export function createWebApp(options) {
                 return renderError(route, errorId, withDuplicateInstanceHint(err));
             }
             // A loader may RETURN its control-flow signal instead of throwing it - `return redirect(...)`
-            // reads naturally and must not silently serialize the `Response` as loader data. Mirror the
-            // catch above exactly: a status signal renders its boundary, any other `Response` (a
-            // redirect, a hand-rolled response) passes through to core verbatim - so return and throw
-            // are interchangeable.
+            // reads naturally and must not silently serialize the signal as loader data. Mirror the catch
+            // above exactly: a status signal renders its boundary, any other signal (a redirect, a
+            // hand-rolled response) passes through to core verbatim - so return and throw are
+            // interchangeable.
             if (isStatusSignal(data))
                 return renderStatusSignal(c.req, data);
-            if (data instanceof Response)
+            if (isControlFlow(data))
                 return data;
             // Client-side navigation asks (via the X-Nifra-Data header) for just the loader data - no full
             // document, no layout chain. A route with deferred data streams NDJSON (critical data first,
@@ -1353,20 +1441,28 @@ export function createWebApp(options) {
                     offset += split.deferred.length;
                 }
                 const deferred = [...pageSplit.deferred, ...layoutSplits.flatMap((split) => split.deferred)];
-                const payload = layoutData === undefined
+                const boundarySplit = boundaryStates === undefined
+                    ? undefined
+                    : prepareDeferred(boundaryStates, deferred.length);
+                const allDeferred = [
+                    ...deferred,
+                    ...(boundarySplit === undefined ? [] : boundarySplit.deferred),
+                ];
+                const payload = layoutData === undefined && boundarySplit === undefined
                     ? pageSplit.forClient
                     : {
                         v: 1,
                         data: pageSplit.forClient,
                         layoutData: layoutSplits.map((split) => split.forClient),
                         retained: layoutRetained,
+                        ...(boundarySplit === undefined ? {} : { boundaries: boundarySplit.forClient }),
                     };
                 // Bare value when there is no layout data - the pre-envelope shape, so a client running older
                 // code against a newer server keeps working.
-                if (deferred.length === 0) {
+                if (allDeferred.length === 0) {
                     return Response.json(payload ?? null);
                 }
-                return new Response(ndjsonStream(payload, deferred), {
+                return new Response(ndjsonStream(payload, allDeferred), {
                     headers: { "content-type": "application/x-ndjson; charset=utf-8" },
                 });
             }
@@ -1396,6 +1492,7 @@ export function createWebApp(options) {
                     search: searchChainOf(layoutModules ?? [], mod, c.req),
                     hydrate: hydrateRoute,
                     ...(layoutData !== undefined ? { layoutData } : {}),
+                    ...(boundaryStates !== undefined ? { boundaries: boundaryStates } : {}),
                     ...preloadOf(route.id),
                     ...stylesOf(route.id),
                     prerenderedPaths: options.prerenderedPaths ?? [],
@@ -1410,7 +1507,7 @@ export function createWebApp(options) {
                 // Same precedence as the loader catch above - a `meta()` may signal too.
                 if (isStatusSignal(err))
                     return renderStatusSignal(c.req, err);
-                if (err instanceof Response)
+                if (isControlFlow(err))
                     throw err;
                 // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
                 if (options.onLoaderError !== undefined) {
@@ -1427,7 +1524,7 @@ export function createWebApp(options) {
                 return renderError(route, errorId, withDuplicateInstanceHint(err));
             }
         });
-        // POST runs the route's `action` (mutation). A `Response` return (e.g. a `redirect(...)`)
+        // POST runs the route's `action` (mutation). A control-flow return (e.g. a `redirect(...)`)
         // passes straight through; a data return re-renders the page (the loader re-runs for fresh
         // data) with `actionData`. Routes without an action reject POST with 405 - not a stray 404.
         app.register("POST", route.pattern, undefined, async (c) => {
@@ -1458,10 +1555,10 @@ export function createWebApp(options) {
                 result = await mod.action(actionContext);
             }
             catch (err) {
-                // A THROWN Response is the same control-flow signal as a returned one (`throw redirect()`
-                // in a gate or an action) - route it through the same conversion as the returned-Response
-                // branch below, so throw and return are interchangeable on the mutation path too.
-                if (err instanceof Response)
+                // A THROWN signal is the same control flow as a returned one (`throw redirect()` in a gate
+                // or an action) - route it through the same conversion as the returned branch below, so
+                // throw and return are interchangeable on the mutation path too.
+                if (isControlFlow(err))
                     return actionResponse(err, isDataRequest);
                 throw err;
             }
@@ -1473,7 +1570,7 @@ export function createWebApp(options) {
             const revalidateHeader = isRevalidate
                 ? { [REVALIDATE_HEADER]: result.__nifraRevalidate.join(",") }
                 : {};
-            if (actionResult instanceof Response)
+            if (isControlFlow(actionResult))
                 return actionResponse(actionResult, isDataRequest);
             // Client submit wants just the action's data (it revalidates the loader itself); a native
             // form POST re-renders the full page (loader re-runs) with the action data.
@@ -1648,6 +1745,9 @@ export function generateClientEntry(manifest, options) {
         // routeId → the page's client-only search keys (`searchClientKeys`, or `[]`). The router reads this
         // by reference to decide when a same-route search change can skip the loader fetch (re-render only).
         "const searchClientKeys = {}",
+        // routeId → the page's optional post-hydration client loader/action hooks. Hooks are populated only
+        // after the route chunk loads, so routes that do not declare them remain ordinary route modules.
+        "const routeHooks = {}",
         "const loadModule = async (id) => {",
         "  if (chains[id]) return",
         "  const mods = await loaders[id]()",
@@ -1676,6 +1776,13 @@ export function generateClientEntry(manifest, options) {
         "    searchSchemas[id] = mods.map((m) => m.searchSchema)",
         "    searchClientKeys[id] = mods[mods.length - 1].searchClientKeys ?? []",
         "  }",
+        "  const page = errorRouteIds.has(id) ? mods[mods.length - 2] : mods[mods.length - 1]",
+        // Keep interception client-safe: only neutral name/mode metadata crosses into the router. The
+        // server-side boundary load function (which may close over secrets) is never stored in the client
+        // hook table or serialized into a browser bundle by this wiring.
+        "  const boundaryMods = errorRouteIds.has(id) ? mods.slice(0, -1) : mods",
+        "  const boundaries = boundaryMods.flatMap((m) => (m.boundaries ?? []).map((b) => ({ name: b.name, mode: b.mode, hasLoad: b.load !== undefined, ...(b.errorId === undefined ? {} : { errorId: b.errorId }) })))",
+        "  routeHooks[id] = { clientLoader: page.clientLoader, clientAction: page.clientAction, boundaries }",
         "}",
         "const patterns = [",
         ...patternRows,
@@ -1696,6 +1803,7 @@ export function generateClientEntry(manifest, options) {
         `  data: mapDeferred(window.${DATA_GLOBAL}),`,
         // Undefined on a page-only app, which is exactly what the router treats as "no layout data".
         `  layoutData: window.${LAYOUT_DATA_GLOBAL} && window.${LAYOUT_DATA_GLOBAL}.map(mapDeferred),`,
+        `  boundaries: mapDeferred(window.${BOUNDARY_GLOBAL}),`,
         // actionData (only set after a form POST) is in the initial state so the binding hydrates
         // consistently with the server-rendered markup; mapped through `mapDeferred` too so a deferred
         // action's placeholders become registry markers (a no-op when the action didn't defer).
@@ -1703,7 +1811,7 @@ export function generateClientEntry(manifest, options) {
         "  pending: false,",
         "}",
         `const statusRoutes = ${JSON.stringify(statusRoutes)}`,
-        "const router = createClientRouter({ patterns, initial, loadModule, statusRoutes, searchClientKeys })",
+        "const router = createClientRouter({ patterns, initial, loadModule, statusRoutes, searchClientKeys, routeHooks })",
         "installHistory(router)",
         "installForms(router)",
         // The container is found in the DOM, not baked in. `rootId` is a per-render option and this entry
@@ -1722,6 +1830,10 @@ export function generateClientEntry(manifest, options) {
         // is server-rendered; subsequent navigations update it from the matched route's meta + data.
         "loadModule(initial.routeId).then(() => {",
         "  mountRouter({ router, routes: chains, searchSchemas, container: root })",
+        // Run the optional client loader only after the adapter has mounted the SSR tree. The initial
+        // server data is already in `window.__NIFRA_DATA__`, so `serverLoader()` reuses it and cannot
+        // duplicate the first request.
+        "  router.hydrate().catch((error) => console.error('[nifra/web] clientLoader failed:', error))",
         // Next frame: the adapter has committed its initial hydration, so handlers are attached. Flip the
         // document to interactive (`data-nifra-hydrated` + `nifra:hydrated`) for apps to gate pre-hydration UI.
         "  requestAnimationFrame(signalHydrated)",