@nifrajs/web 2.14.1 → 3.1.0

package/src/index.ts

@@ -13,7 +13,23 @@ import {
   type BackendMountHandler,
   NIFRA_BACKEND_MOUNT,
 } from "@nifrajs/core/mount"
-import { type ServerOptions, server, type UrlParts, urlPartsOf } from "@nifrajs/core/server"
+import {
+  isSameOriginPath,
+  type ResponseResult,
+  type ServerOptions,
+  server,
+  status as statusResult,
+  type UrlParts,
+  urlPartsOf,
+} from "@nifrajs/core/server"
+import type { BoundaryRegistration } from "./boundary.ts"
+import {
+  type BoundaryRequestCtx,
+  type BoundaryStates,
+  boundaryDescriptors,
+  resolveStaticBoundaries,
+  startDynamicBoundaries,
+} from "./boundary.ts"
 import {
   DEFERRED_ERROR_CODE,
   DEFERRED_RUNTIME,
@@ -51,6 +67,7 @@ import type {
 import type { RenderAdapter, RenderProps } from "./render-seam.ts"
 import {
   ACTION_GLOBAL,
+  BOUNDARY_GLOBAL,
   DATA_GLOBAL,
   LAYOUT_DATA_GLOBAL,
   ROOT_ATTRIBUTE,
@@ -69,6 +86,33 @@ import {
 import { searchOf, searchOfChain } from "./search.ts"
 
 // Draft / preview mode - a signed cookie that flips `ctx.draft` for loaders + bypasses ISR for editors.
+export {
+  assertStaticBoundaryImports,
+  type Boundary,
+  type BoundaryDescriptor,
+  type BoundaryError,
+  type BoundaryMode,
+  type BoundaryRegistration,
+  type BoundaryRequestCtx,
+  type BoundaryState,
+  type BoundaryStates,
+  type BoundaryStatus,
+  boundaryDescriptors,
+  boundaryModeKey,
+  type DynamicBoundary,
+  type DynamicBoundaryBatch,
+  type InterceptBoundary,
+  MemoryStaticBoundaryCache,
+  type PendingBoundary,
+  resolveDynamicBoundaries,
+  resolveStaticBoundaries,
+  type StaticBoundary,
+  type StaticBoundaryCache,
+  type StaticBoundaryImportEdge,
+  type StaticBoundaryRoot,
+  type StaticCtx,
+  startDynamicBoundaries,
+} from "./boundary.ts"
 export {
   DRAFT_COOKIE,
   type DraftCookieControls,
@@ -112,6 +156,13 @@ export {
 export {
   type Action,
   buildManifest,
+  type ClientAction,
+  type ClientActionArgs,
+  type ClientActionResult,
+  type ClientLoader,
+  type ClientLoaderArgs,
+  type ClientRequestBody,
+  type ClientRouteHooks,
   enumerateStaticRoutes,
   filePathToPattern,
   filePathToPatterns,
@@ -245,6 +296,7 @@ export {
 } from "./conformance.ts"
 export {
   ACTION_GLOBAL,
+  BOUNDARY_GLOBAL,
   DATA_GLOBAL,
   LAYOUT_DATA_GLOBAL,
   type RenderAdapter,
@@ -312,6 +364,21 @@ const SCRIPT_ESCAPE_MAP: Readonly<Record<string, string>> = {
 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: unknown): value is ResponseResult =>
+  typeof value === "object" &&
+  value !== null &&
+  (value as { readonly [RESPONSE_RESULT]?: unknown })[RESPONSE_RESULT] === true &&
+  typeof (value as { readonly toResponse?: unknown }).toResponse === "function"
+
+/** A returned/thrown value that ends the request as-is: either shape of control-flow signal. */
+const isControlFlow = (value: unknown): value is Response | ResponseResult =>
+  value instanceof Response || isResponseResult(value)
+
 export interface RenderedPage {
   readonly [RESPONSE_RESULT]: true
   toResponse(): Response
@@ -372,6 +439,8 @@ export interface RenderPageOptions {
   /** Per-layout loader data, forwarded to the adapter as `RenderProps.layoutData`. Aligned with the
    * chain's layout prefix; omitted when no layout in the chain has a loader. */
   readonly layoutData?: readonly unknown[]
+  /** Dynamic-boundary states, forwarded to the adapter and serialized for hydration when present. */
+  readonly boundaries?: BoundaryStates
   /** HTTP status for the response (default 200; e.g. 404 for a not-found page). */
   readonly status?: number
   /** Extra response headers - e.g. the `cache-control` a terminal status page wants. `content-type`
@@ -478,6 +547,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     hydrate = true,
     islandScripts = [],
     nonce,
+    boundaries,
     headers: extraHeaders,
   } = options
   if (nonce !== undefined && nonce.trim() === "") {
@@ -512,12 +582,24 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     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
+    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
@@ -529,6 +611,10 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     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
@@ -609,7 +695,7 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // 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 as string)
   const headers: Record<string, string> = { "content-type": "text/html; charset=utf-8" }
   // Caller-supplied headers (a terminal status page's `cache-control`, say). Applied before the
@@ -641,6 +727,9 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     ...(options.layoutData !== undefined
       ? { layoutData: layoutSplits.map((split) => split.forComponent) }
       : {}),
+    ...(boundarySplit !== undefined
+      ? { boundaries: boundarySplit.forComponent as BoundaryStates }
+      : {}),
   }
 
   // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
@@ -817,31 +906,39 @@ export interface RedirectOptions {
    * leading `/`) is permitted, so an action can't be turned into an open redirect by passing
    * attacker-controlled input straight through. Set `true` for a deliberate external redirect. */
   readonly external?: boolean
+  /** Extra response headers. A redirect is no longer a `Response`, so there is no `.headers` to
+   * mutate after the fact - name them here. Cookies still ride `c.set`, as on any other response. */
+  readonly headers?: Readonly<Record<string, string>>
 }
 
 /** 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: string): boolean {
-  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: string, options: RedirectOptions = {}): Response {
+export function redirect(location: string, options: RedirectOptions = {}): ResponseResult {
   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.`,
+      `[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
@@ -853,7 +950,9 @@ export function redirect(location: string, options: RedirectOptions = {}): Respo
       `[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 },
+  })
 }
 
 /**
@@ -913,17 +1012,34 @@ function withDuplicateInstanceHint(err: unknown): unknown {
 }
 
 /**
- * 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: Response, isDataRequest: boolean): Response {
-  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: Response | ResponseResult,
+  isDataRequest: boolean,
+): Response | ResponseResult {
+  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
 }
 
 /** A loaded layout module. `loader`/`gate` are the layout-loader surface; `meta` predates it. */
@@ -936,6 +1052,7 @@ type LoadedLayoutModules = ReadonlyArray<{
   // A layout may declare its own `searchSchema`; the route's effective search merges the layout chain's
   // schemas with the page's (page-wins). Present on the raw module already - typed here so it is readable.
   searchSchema?: RouteModule["searchSchema"]
+  boundaries?: readonly BoundaryRegistration[]
 }>
 
 /**
@@ -1447,6 +1564,9 @@ export interface CreateWebAppOptions<Env = unknown> {
    * `prerenderedPaths` with the 404 page - the unlisted path simply doesn't exist. `"ssr"` (the
    * default for unmapped routes) renders unlisted paths on-demand. */
   readonly staticFallbacks?: Readonly<Record<string, "ssr" | "404">>
+  /** In-memory reference cache for explicitly `static` boundary values. It never persists payloads
+   * across processes; operated/durable cache implementations stay outside the public framework. */
+  readonly staticBoundaryCache?: import("./boundary.ts").StaticBoundaryCache
   /** Observe every loader/action failure - for error-reporting plugins (Sentry-style). Called for
    * real throws (not control-flow `Response`s like `redirect`), **before** the nearest `_error`
    * boundary renders / a soft-nav 500 / a rethrow - so it sees errors that the boundary would
@@ -2038,6 +2158,7 @@ export function createWebApp<Env = unknown>(
       const draft = await draftFlag(c.req)
       let data: unknown
       let layoutData: readonly unknown[] | undefined
+      let boundaryStates: BoundaryStates | undefined
       let layoutModules: LoadedLayoutModules | undefined
       let layoutRetained: readonly number[] = []
       try {
@@ -2064,25 +2185,65 @@ export function createWebApp<Env = unknown>(
         )
         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,
+              } satisfies BoundaryRequestCtx)
+        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
         // that status. Checked BEFORE the pass-through below: a signal IS a `Response`, so the order
         // 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) throw err
+        // 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) {
           try {
@@ -2104,12 +2265,12 @@ export function createWebApp<Env = unknown>(
         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) return data
+      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,
       // then each deferred value as it settles); otherwise one JSON (the fast path). Same loader,
@@ -2124,21 +2285,30 @@ export function createWebApp<Env = unknown>(
           offset += split.deferred.length
         }
         const deferred = [...pageSplit.deferred, ...layoutSplits.flatMap((split) => split.deferred)]
+        const boundarySplit =
+          boundaryStates === undefined
+            ? undefined
+            : prepareDeferred(boundaryStates, deferred.length)
+        const allDeferred = [
+          ...deferred,
+          ...(boundarySplit === undefined ? [] : boundarySplit.deferred),
+        ]
         const payload =
-          layoutData === undefined
+          layoutData === undefined && boundarySplit === undefined
             ? pageSplit.forClient
             : {
                 v: 1 as const,
                 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" },
         })
       }
@@ -2168,6 +2338,7 @@ export function createWebApp<Env = unknown>(
           search: searchChainOf(layoutModules ?? [], mod, c.req),
           hydrate: hydrateRoute,
           ...(layoutData !== undefined ? { layoutData } : {}),
+          ...(boundaryStates !== undefined ? { boundaries: boundaryStates } : {}),
           ...preloadOf(route.id),
           ...stylesOf(route.id),
           prerenderedPaths: options.prerenderedPaths ?? [],
@@ -2180,7 +2351,7 @@ export function createWebApp<Env = unknown>(
       } catch (err) {
         // Same precedence as the loader catch above - a `meta()` may signal too.
         if (isStatusSignal(err)) return renderStatusSignal(c.req, err)
-        if (err instanceof Response) throw err
+        if (isControlFlow(err)) throw err
         // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
         if (options.onLoaderError !== undefined) {
           try {
@@ -2195,7 +2366,7 @@ export function createWebApp<Env = unknown>(
       }
     })
 
-    // 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: RouteContext) => {
@@ -2225,10 +2396,10 @@ export function createWebApp<Env = unknown>(
         layoutModules = await runLayoutGates(route, actionContext)
         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) return actionResponse(err, isDataRequest)
+        // 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
       }
       // An action may wrap its data in `revalidate(paths, data)` to declare which routes it changed.
@@ -2240,7 +2411,7 @@ export function createWebApp<Env = unknown>(
       const revalidateHeader: Record<string, string> = isRevalidate
         ? { [REVALIDATE_HEADER]: (result as RevalidateResult<unknown>).__nifraRevalidate.join(",") }
         : {}
-      if (actionResult instanceof Response) return actionResponse(actionResult, isDataRequest)
+      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.
       if (isDataRequest) {
@@ -2445,6 +2616,9 @@ export function generateClientEntry(
     // 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]()",
@@ -2473,6 +2647,13 @@ export function generateClientEntry(
     "    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,
@@ -2493,6 +2674,7 @@ export function generateClientEntry(
     `  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).
@@ -2500,7 +2682,7 @@ export function generateClientEntry(
     "  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
@@ -2521,6 +2703,10 @@ export function generateClientEntry(
     // 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)",

package/src/internal/fetcher-runtime.ts

@@ -0,0 +1,36 @@
+import type { ClientRouter, Fetcher, FetcherState } from "../router.ts"
+
+/** Stable idle state shared by every framework fetcher binding. */
+export const IDLE_FETCHER_STATE: FetcherState = Object.freeze({
+  pending: false,
+  data: undefined,
+})
+
+/** Stable empty collection used before a router is mounted. */
+export const NO_FETCHERS: readonly Fetcher[] = Object.freeze([])
+
+/** No-op subscription used by SSR and pre-mount snapshots. */
+export const noopSubscribe = (): (() => void) => () => {}
+
+/** No-op fetcher action used before a router is mounted. */
+export const noopAsync = async (): Promise<void> => {}
+
+/** Stable idle fetcher snapshot for external-store bindings. */
+export const idleFetcherSnapshot = (): FetcherState => IDLE_FETCHER_STATE
+
+/** Stable empty fetcher collection snapshot for external-store bindings. */
+export const noFetchers = (): readonly Fetcher[] => NO_FETCHERS
+
+/** Keep mounted-router state local to each adapter package. */
+export function createMountedRouterRef(): {
+  readonly get: () => ClientRouter | undefined
+  readonly set: (router: ClientRouter | undefined) => void
+} {
+  let router: ClientRouter | undefined
+  return {
+    get: () => router,
+    set: (next) => {
+      router = next
+    },
+  }
+}