@nifrajs/web 2.1.0 → 2.2.0

package/src/index.ts

@@ -28,7 +28,9 @@ import { ISR_REVALIDATE_HEADER } from "./isr.ts"
 import { generateLlmsTxt } from "./llms-txt.ts"
 import type {
   LayoutEntry,
+  Loader as LayoutLoader,
   LinkDescriptor,
+  LoaderContext,
   Manifest,
   Meta,
   MetaArgs,
@@ -38,10 +40,14 @@ import type {
   ScriptDescriptor,
 } from "./manifest.ts"
 import {
+  createMatcher,
   DATA_HEADER,
+  NAV_FROM_HEADER,
   PRERENDERED_GLOBAL,
   REDIRECT_HEADER,
+  RETAIN_HEADER,
   REVALIDATE_HEADER,
+  STATUS_HEADER,
   type Submission,
 } from "./router.ts"
 
@@ -53,6 +59,8 @@ export {
   type EnableDraftOptions,
   enableDraft,
   isDraftEnabled,
+  type PreviewEndpointOptions,
+  previewEndpoint,
 } from "./draft.ts"
 // Font optimization — a CLS-safe `@font-face` generator + a preload `<link>` for self-hosted fonts.
 export {
@@ -82,7 +90,6 @@ export {
   revalidateEndpoint,
   withISR,
 } from "./isr.ts"
-
 // File-based routing manifest — pure + fs-free. `discoverRoutes` (fs) lives in `@nifrajs/web/fs`.
 export {
   type Action,
@@ -114,6 +121,13 @@ export {
   type NavigateOptions,
   setBrowserNavigate,
 } from "./navigation.ts"
+// public/ — user-authored static files, served identically in dev and production by one handler.
+export {
+  type PublicDirCache,
+  resolvePublicPath,
+  type ServePublicDirOptions,
+  servePublicDir,
+} from "./public-dir.ts"
 // Keyed query-cache (agnostic) — a `query(key, fn)` primitive (dedup + staleness + invalidation + GC)
 // consumed by the per-adapter `useQuery`/`createQuery` bindings.
 export {
@@ -147,11 +161,14 @@ export {
   type FetcherState,
   type FetchRouteData,
   type MountRouterOptions,
+  NAV_FROM_HEADER,
   REDIRECT_HEADER,
+  RETAIN_HEADER,
   REVALIDATE_HEADER,
   type RouteMatch,
   type RoutePattern,
   type RouterState,
+  STATUS_HEADER,
   type Submission,
   type SubmitOptions,
 } from "./router.ts"
@@ -198,6 +215,14 @@ export {
  * (absent on SSR): they drive **optimistic UI** — render from `submission.formData` while `pending`. */
 export interface RenderProps {
   readonly data: unknown
+  /**
+   * Per-layout loader data, aligned index-for-index with the layout prefix of `chain`.
+   *
+   * Absent when no layout in the chain exports a `loader`, so a page-only app is byte-identical to
+   * before. An adapter that does not read it renders exactly as it did; one that does passes
+   * `layoutData[i]` to `chain[i]`.
+   */
+  readonly layoutData?: readonly unknown[]
   readonly actionData?: unknown
   /** True while a client navigation or submit is in flight (client-only; absent/false on SSR). */
   readonly pending?: boolean
@@ -255,6 +280,9 @@ export interface RenderAdapter {
 
 /** Global the server serializes loader data into; the client reads it to hydrate. */
 export const DATA_GLOBAL = "__NIFRA_DATA__"
+/** Per-layout loader data for hydration. Emitted ONLY when some layout in the chain has a loader, so
+ * a page-only app's HTML is byte-identical to before layout loaders existed. */
+export const LAYOUT_DATA_GLOBAL = "__NIFRA_LAYOUT_DATA__"
 
 /** Global the server writes the matched route id into; the client uses it to pick the chain. */
 export const ROUTE_GLOBAL = "__NIFRA_ROUTE__"
@@ -358,8 +386,15 @@ export interface RenderPageOptions {
    * `useLocation`/`useSearchParams` render the right URL server-side and hydrate without drift. Omit ⇒
    * `""`. */
   readonly path?: string
+  /** 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[]
   /** 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`
+   * is ignored (the document is always HTML) and the ISR freshness header is applied after these,
+   * so neither can be overridden from here. */
+  readonly headers?: HeadersLike
   /** Document title (fallback when `head.title` is unset). */
   readonly title?: string
   /** Resolved route head — `title` overrides `title` above; `meta`/`link` render as managed
@@ -418,6 +453,7 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
     rootId = "root",
     hydrate = true,
     islandScripts = [],
+    headers: extraHeaders,
   } = options
   const route = routeId === undefined ? "" : `window.${ROUTE_GLOBAL}=${serializeData(routeId)};`
   // The SSG prerendered-path set (when an app declares it) — the client reads it to fetch a static
@@ -431,9 +467,29 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
   // also `defer()` — split it too, continuing the id space so a single registry settles both. The
   // inline registry runtime is emitted only when something defers, so non-deferred output is unchanged.
   const { forComponent, forClient, deferred } = prepareDeferred(data)
+  // Each layout's data is split in turn, each continuing the id space, so a `defer()` in a layout
+  // settles through the SAME registry as the page's rather than colliding on ids.
+  const layoutSplits: Array<ReturnType<typeof prepareDeferred>> = []
+  if (options.layoutData !== undefined) {
+    let offset = deferred.length
+    for (const entry of options.layoutData) {
+      const split = prepareDeferred(entry, offset)
+      offset += split.deferred.length
+      layoutSplits.push(split)
+    }
+  }
+  const layoutDeferred = layoutSplits.flatMap((split) => split.deferred)
   const actionSplit =
-    actionData === undefined ? undefined : prepareDeferred(actionData, deferred.length)
-  const allDeferred = actionSplit ? [...deferred, ...actionSplit.deferred] : deferred
+    actionData === undefined
+      ? undefined
+      : prepareDeferred(actionData, deferred.length + layoutDeferred.length)
+  const allDeferred = [...deferred, ...layoutDeferred, ...(actionSplit ? actionSplit.deferred : [])]
+  // Omitted entirely when no layout has a loader — a page-only app emits exactly what it did before.
+  const layoutTail =
+    options.layoutData === undefined
+      ? ""
+      : `window.${LAYOUT_DATA_GLOBAL}=${serializeData(layoutSplits.map((split) => split.forClient))};`
+
   // Only emit the action global when an action actually ran, so plain GET output is unchanged.
   const action =
     actionSplit === undefined
@@ -476,7 +532,13 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
   // Runs in the first-paint→hydration window to swallow a JS-only form's broken native submit. Only on a
   // hydrating page (a static/_error page has no client handlers, so no footgun).
   const hydrationGuard = hydrate ? `<script>${PRE_HYDRATION_GUARD}</script>` : ""
-  const shellHtml = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${hydrationGuard}<title>${escapeHtml(head?.title ?? title)}</title>${headTags(head)}${styleLinks}${hydrationLinks}${islandPreloads}${adapter.hydrationHead()}</head><body><div id="${escapeAttr(rootId)}">`
+  // `<html>` attributes. `lang` defaults to `"en"` (so an app that never sets it is byte-identical to
+  // before); `dir` is omitted entirely when unset, which IS HTML's `ltr` default — emitting it
+  // unconditionally would change every existing app's output for no gain. Both attribute-escaped.
+  // `client.ts`'s `applyHead` mirrors this exact defaulting on soft-nav, so a hard load and a client
+  // navigation to the same URL produce the same `<html>` (no drift on a multilingual site).
+  const htmlAttrs = ` lang="${escapeAttr(head?.lang ?? "en")}"${head?.dir === undefined ? "" : ` dir="${escapeAttr(head.dir)}"`}`
+  const shellHtml = `<!doctype html><html${htmlAttrs}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${hydrationGuard}<title>${escapeHtml(head?.title ?? title)}</title>${headTags(head)}${styleLinks}${hydrationLinks}${islandPreloads}${adapter.hydrationHead()}</head><body><div id="${escapeAttr(rootId)}">`
   // Closes the hydration container; deferred resolve scripts go AFTER it (outside `#root`) so they
   // aren't part of the adapter's hydrated tree (an inline script inside it breaks hydration).
   const closeRootHtml = "</div>"
@@ -489,10 +551,18 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
     islandTags += `<script type="module" src="${escapeAttr(src)}"></script>`
   const tailHtml = `${
     hydrate
-      ? `<script>${route}${action}${prerendered}window.${DATA_GLOBAL}=${serializeData(forClient)}</script><script type="module" src="${escapeAttr(clientEntry)}"></script>`
+      ? `<script>${route}${action}${prerendered}${layoutTail}window.${DATA_GLOBAL}=${serializeData(forClient)}</script><script type="module" src="${escapeAttr(clientEntry)}"></script>`
       : ""
   }${islandTags}</body></html>`
   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
+  // framework's own below, so `content-type` and the ISR channel stay authoritative - a caller must
+  // not be able to mislabel the document or forge the freshness header by passing them here.
+  if (extraHeaders !== undefined) {
+    for (const [name, value] of new Headers(extraHeaders)) {
+      if (name !== "content-type") headers[name] = value
+    }
+  }
   // ISR: advertise the route's freshness so a `withISR` wrapper can set this page's cache TTL. A
   // dedicated header (not the action-revalidation `x-nifra-revalidate`) so the TTL channel never aliases
   // the client's path-list channel.
@@ -505,6 +575,10 @@ export function renderPageResult(options: RenderPageOptions): MaybePromise<Rende
     // router bindings simply never reads them.
     ...(options.params !== undefined ? { params: options.params } : {}),
     ...(options.path !== undefined ? { path: options.path } : {}),
+    // Spread only when present, so a page-only render produces exactly the props it did before.
+    ...(options.layoutData !== undefined
+      ? { layoutData: layoutSplits.map((split) => split.forComponent) }
+      : {}),
   }
 
   // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
@@ -717,6 +791,205 @@ export function redirect(location: string, options: RedirectOptions = {}): Respo
   return new Response(null, { status: options.status ?? 303, headers: { location } })
 }
 
+/**
+ * Brand marking a `Response` as a **terminal-status signal** rather than a response to serve verbatim.
+ *
+ * A loader that throws a bare `Response` has always been passed straight through - that is how
+ * `throw redirect(...)` works, and apps rely on it. So "render the `_404` boundary at 404" cannot be
+ * expressed by throwing a plain `Response`: the framework would have no way to tell it apart from a
+ * hand-rolled body the app wants served exactly as written. The brand is that distinction, and
+ * checking it *before* the pass-through is what keeps every existing throw working unchanged.
+ *
+ * `Symbol.for` matches `RESPONSE_RESULT` above: a registry symbol survives two copies of this module,
+ * which a `unique symbol` would not - and a duplicate-install turning a 404 into a raw 404 body would
+ * be a maddening bug to trace.
+ */
+/** Derived from the `Headers` constructor rather than the DOM lib's `HeadersInit`: `@nifrajs/web`
+ * is consumed from DOM-free programs (the root tsconfig runs `types: ["bun"]`), and naming the DOM
+ * type here would break their build. Same workaround as `SSEInit.headers` in core. */
+type HeadersLike = ConstructorParameters<typeof Headers>[0]
+
+/**
+ * The signatures a **duplicate module instance** produces during SSR, across engines.
+ *
+ * Two copies of React (or of `@nifrajs/core`) at the SAME version still fail, because module identity
+ * is path-based: hooks read a dispatcher off the copy that rendered, and the component imported the
+ * other one. The error that surfaces names a React internal, so it reads as a React bug and the actual
+ * cause - two directories - is a long inference away. Naming the cause at the point of failure is the
+ * difference between that and a five-second read.
+ */
+const DUPLICATE_INSTANCE_SIGNATURES: readonly RegExp[] = [
+  /resolveDispatcher\(\)/,
+  /Invalid hook call/,
+  /Cannot read propert(?:y|ies) of null \(reading '(?:use[A-Z]\w*)'\)/,
+  /null is not an object \(evaluating '.*\.use[A-Z]\w*'\)/,
+]
+
+/**
+ * Append the likely cause to an SSR error that carries a duplicate-instance signature.
+ *
+ * Deliberately does NOT claim the resolved paths: `@nifrajs/web` is framework-agnostic and does not
+ * depend on React, so it cannot resolve the copies without guessing. It names the condition and the
+ * command that reports the paths, which is the actionable part. Returns the error untouched when the
+ * signature does not match, so an ordinary render error reads exactly as before.
+ */
+function withDuplicateInstanceHint(err: unknown): unknown {
+  if (!(err instanceof Error)) return err
+  if (!DUPLICATE_INSTANCE_SIGNATURES.some((rx) => rx.test(err.message))) return err
+  const augmented = new Error(
+    `${err.message}\n\n[nifra/web] This signature usually means TWO COPIES of an identity-sensitive package (react, react-dom, or @nifrajs/core) are installed at different paths. Module identity is path-based, so matching versions do NOT fix it - the copies must resolve to the same directory. Run \`nifra check\` to list the paths.`,
+    { cause: err },
+  )
+  augmented.name = err.name
+  // `stack` is optional under exactOptionalPropertyTypes; assigning `undefined` would replace a real
+  // stack with nothing on engines that always populate it.
+  if (err.stack !== undefined) augmented.stack = err.stack
+  return augmented
+}
+
+/** A loaded layout module. `loader`/`gate` are the layout-loader surface; `meta` predates it. */
+type LoadedLayoutModules = ReadonlyArray<{
+  default: unknown
+  meta?: MetaInput
+  loader?: LayoutLoader
+  action?: unknown
+  gate?: boolean
+}>
+
+/**
+ * Narrow the route's params to the ones a layout owns.
+ *
+ * A layout wraps a URL prefix, so anything deeper belongs to a route beneath it. Handing it the full
+ * set would let a layout read a param it does not own - which reads fine until the layout is reused
+ * under a route that has no such param and the value silently becomes `undefined`.
+ */
+function scopeParams(
+  params: Record<string, string>,
+  owned: readonly string[] | undefined,
+): Record<string, string> {
+  if (owned === undefined) return params // hand-built manifest with no scope info: unchanged behaviour
+  if (owned.length === 0) return EMPTY_LAYOUT_PARAMS
+  const scoped: Record<string, string> = {}
+  for (const name of owned) {
+    const value = params[name]
+    if (value !== undefined) scoped[name] = value
+  }
+  return scoped
+}
+
+const EMPTY_LAYOUT_PARAMS: Record<string, string> = Object.freeze({})
+
+const EMPTY_RETAIN: ReadonlySet<number> = new Set<number>()
+
+/**
+ * Marks an error as coming from a LAYOUT loader, carrying that layout's id.
+ *
+ * The boundary that catches it must be at or above the failing layout's own segment. The route's
+ * innermost `_error` may live BELOW the layout that failed, and rendering there would wrap the
+ * boundary in a layout whose data never arrived - so the page would render inside a component that
+ * threw. A registry symbol, matching the other cross-module brands here.
+ */
+const LAYOUT_ERROR_ID = Symbol.for("nifra.web.layout-error-id")
+
+const tagLayoutError = (err: unknown, layoutId: string): unknown => {
+  if (typeof err === "object" && err !== null && !(LAYOUT_ERROR_ID in err)) {
+    Object.defineProperty(err, LAYOUT_ERROR_ID, { value: layoutId, enumerable: false })
+  }
+  return err
+}
+
+const layoutErrorId = (err: unknown): string | undefined =>
+  typeof err === "object" && err !== null
+    ? ((err as Record<symbol, unknown>)[LAYOUT_ERROR_ID] as string | undefined)
+    : undefined
+
+const STATUS_SIGNAL = Symbol.for("nifra.web.status-signal")
+
+/** Reason phrases for the plain-text fallback, used only when the app authored no `_<status>` and no
+ * `_404` page. Deliberately not exhaustive - anything unlisted falls back to "Error", which is more
+ * useful than shipping a table of every RFC status for a body almost nobody will see. */
+const STATUS_TEXT: Readonly<Record<number, string>> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  410: "Gone",
+  451: "Unavailable For Legal Reasons",
+  500: "Internal Server Error",
+}
+
+interface StatusSignal extends Response {
+  readonly [STATUS_SIGNAL]: { readonly status: number; readonly headers?: HeadersLike }
+}
+
+function isStatusSignal(value: unknown): value is StatusSignal {
+  return value instanceof Response && STATUS_SIGNAL in value
+}
+
+function statusSignal(status: number, options: StatusPageOptions): never {
+  if (!Number.isInteger(status) || status < 400 || status > 599) {
+    throw new Error(
+      `[nifra/web] statusPage(${JSON.stringify(status)}) must be an integer 4xx or 5xx status. Use redirect() for 3xx, and return data for a successful render.`,
+    )
+  }
+  const response = new Response(null, { status })
+  // Non-enumerable so the brand never lands in a structured clone or a JSON log of the response.
+  Object.defineProperty(response, STATUS_SIGNAL, {
+    value: { status, ...(options.headers !== undefined ? { headers: options.headers } : {}) },
+    enumerable: false,
+  })
+  throw response
+}
+
+/** Options shared by {@link notFound}, {@link gone}, and {@link statusPage}. */
+export interface StatusPageOptions {
+  /**
+   * Extra headers for the rendered response - `cache-control` above all.
+   *
+   * The defaults differ by status for a reason: a 404 may be a race with publication, so it wants a
+   * short TTL, while a 410 is a promise that the URL is permanently gone and can be cached hard.
+   * Getting this wrong is the difference between a crawler dropping a dead URL and re-fetching it
+   * for weeks.
+   */
+  readonly headers?: HeadersLike
+}
+
+/**
+ * Render the nearest `_404` page at status **404**. `throw` it from a loader when the record does not
+ * exist.
+ *
+ * This is the fix for the soft 404: a matched route whose loader finds nothing has otherwise no way to
+ * answer 404, so the path of least resistance is to return empty data and render "not found" inside a
+ * **200**. That looks correct in a browser and is invisible in review, which is why it ships and stays
+ * shipped - while search engines penalise it and keep the dead URL indexed.
+ *
+ * Returns `never`: these throw, so a loader narrows without a redundant `return`, and the type states
+ * the thing the "loaders `throw` redirect, actions `return` it" rule already trips people on.
+ */
+export function notFound(options: StatusPageOptions = {}): never {
+  return statusSignal(404, options)
+}
+
+/**
+ * Render a terminal page at status **410 Gone**. `throw` it from a loader for a record that existed and
+ * was deliberately removed - a withdrawn listing, a deleted post.
+ *
+ * 410 is not a pedantic 404: it tells a crawler to **drop** the URL rather than re-fetch it for weeks
+ * on the assumption the 404 was transient. Uses `_410.tsx` if the app has one, otherwise `_404`.
+ */
+export function gone(options: StatusPageOptions = {}): never {
+  return statusSignal(410, options)
+}
+
+/**
+ * Render a terminal page at any 4xx/5xx status - the escape hatch behind {@link notFound} and
+ * {@link gone} (402, 451, …). Uses `_<status>.tsx` if present, otherwise `_404`.
+ */
+export function statusPage(status: number, options: StatusPageOptions = {}): never {
+  return statusSignal(status, options)
+}
+
 /** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
  * shape (not a class) so `@nifrajs/client`'s `ActionData` can unwrap it structurally without importing
  * from `@nifrajs/web`. `createWebApp` strips the wrapper — the client receives `data` as the body and
@@ -926,11 +1199,15 @@ export function mergeHeads(heads: readonly Meta[]): Meta {
   // resolved object by reference so headTags' identity-keyed memo hits across requests for static meta.
   if (heads.length === 1) return heads[0] as Meta
   let title: string | undefined
+  let lang: string | undefined
+  let dir: Meta["dir"]
   const meta: Array<Record<string, string>> = []
   const link: LinkDescriptor[] = []
   const script: ScriptDescriptor[] = []
   for (const h of heads) {
     if (h.title !== undefined) title = h.title // nearest-wins: later (more specific) overrides
+    if (h.lang !== undefined) lang = h.lang // nearest-wins, like title
+    if (h.dir !== undefined) dir = h.dir
     if (h.meta !== undefined) meta.push(...h.meta)
     if (h.link !== undefined) link.push(...h.link)
     if (h.script !== undefined) script.push(...h.script) // concatenated like meta/link (outermost first)
@@ -944,11 +1221,15 @@ export function mergeHeads(heads: readonly Meta[]): Meta {
     meta?: Meta["meta"]
     link?: Meta["link"]
     script?: Meta["script"]
+    lang?: string
+    dir?: Meta["dir"]
   } = {}
   if (title !== undefined) merged.title = title
   if (meta.length > 0) merged.meta = meta
   if (link.length > 0) merged.link = link
   if (script.length > 0) merged.script = script
+  if (lang !== undefined) merged.lang = lang
+  if (dir !== undefined) merged.dir = dir
   return merged as Meta
 }
 
@@ -975,6 +1256,33 @@ export interface CreateWebAppOptions {
    * auto-mount entirely (the app serves pages only and `api` stays a loader-only `ctx.api`). Mounting
    * is also a no-op when `api` does not expose the symbol mount. */
   readonly apiPrefix?: string
+  /**
+   * Strip {@link apiPrefix} from the pathname before dispatching to `api` (default `false`).
+   *
+   * The default suits a backend that declares FULL paths (`server().post("/api/sync", …)`), which is
+   * right when it is only ever mounted here. Set this when the backend declares its routes WITHOUT the
+   * prefix because it also runs standalone behind its own shell, so its paths cannot carry a prefix that
+   * only exists when it is mounted. Without it every request 404s inside the backend, and the workaround
+   * is a `Proxy` that rewrites each URL.
+   */
+  readonly apiStrip?: boolean
+  /**
+   * Sub-apps mounted ahead of page routing - an auth handler, a webhook receiver, a stack's routes.
+   *
+   * Structural on purpose: anything with `{ path, app: { fetch } }` fits, so a library that exposes its
+   * routes as such a list mounts as `mounts: theirRoutes` without `@nifrajs/web` taking a dependency on
+   * it. `better-auth` is the motivating case - it is not a `backend` route, so `/api/auth/*` used to 404
+   * silently.
+   *
+   * Tried longest-path-first and BEFORE the `api` mount, so a mount at `/api/auth` wins over a backend
+   * at `/api` no matter which was declared first. `stripPrefix` is the per-mount form of {@link apiStrip}:
+   * leave it off to pass the full path through.
+   */
+  readonly mounts?: ReadonlyArray<{
+    readonly path: string
+    readonly app: { fetch(request: Request): Response | Promise<Response> }
+    readonly stripPrefix?: boolean
+  }>
   /** Secret for **draft / preview mode** (see `enableDraft`). When set, a request carrying a valid
    * signed `__nifra_draft` cookie gets `ctx.draft === true` in loaders/actions (else always `false`).
    * Pair with `withISR({ draftSecret })` so editors bypass the cache. Omit to disable draft mode. */
@@ -1025,6 +1333,27 @@ interface RouteContext {
   readonly env: unknown
 }
 
+/**
+ * Re-issue `request` with `prefix` removed from its pathname.
+ *
+ * Needed because two conventions exist and both are reasonable. `createWebApp`'s auto-mount assumes a
+ * backend that declares FULL paths (`server().post("/api/sync")`), which is right when the backend is
+ * only ever mounted here. A backend that also runs standalone declares paths WITHOUT the prefix and
+ * lets its own shell supply it - and mounting one of those here used to require the caller to wrap it
+ * in a `Proxy` that rewrote every URL. Two apps wrote that same wrapper independently, which is the
+ * signal that it belonged in the framework.
+ *
+ * The `Request` is rebuilt rather than mutated (`url` is read-only), preserving method, headers, body,
+ * and duplex streaming - the body is passed through unread, so a large or streamed upload is untouched.
+ */
+function stripMountPrefix(request: Request, prefix: string): Request {
+  const url = new URL(request.url)
+  const rest = url.pathname.slice(prefix.length)
+  url.pathname = rest === "" ? "/" : rest
+  // `url.href`, not the `URL`: this type set only declares the string and Request overloads.
+  return new Request(url.href, request)
+}
+
 /**
  * Resolve the explicit symbol-keyed backend mount interface. The symbol seam forwards platform
  * context without making web depend on client.
@@ -1087,14 +1416,27 @@ export function createWebApp<Env = unknown>(
   // sites. `apiPrefix: ""` opts out; a non-mountable `api` (no symbol mount) is left pages-only. The hook
   // is registered ONLY when both hold, so a pages-only app keeps core's synchronous no-hook fast path.
   const apiPrefix = options.apiPrefix ?? "/api"
+  const apiStrip = options.apiStrip === true
   const mountedApi = backendMountOf(api)
-  if (apiPrefix !== "" && mountedApi !== undefined) {
+  // Longest path first, so a more specific mount (`/api/auth`) is tried before a broader one (`/api`)
+  // regardless of the order they were declared in.
+  const mounts = [...(options.mounts ?? [])].sort((a, b) => b.path.length - a.path.length)
+  const underPrefix = (pathname: string, prefix: string): boolean =>
+    pathname === prefix || pathname.startsWith(`${prefix}/`)
+
+  if (mounts.length > 0 || (apiPrefix !== "" && mountedApi !== undefined)) {
     app.onRequest((req, platform) => {
       const { pathname } = new URL(req.url)
+      // Sub-app mounts win over the backend prefix: they are the more specific declaration, and an
+      // auth handler mounted at `/api/auth` must not be swallowed by the backend mounted at `/api`.
+      for (const mount of mounts) {
+        if (!underPrefix(pathname, mount.path)) continue
+        return mount.app.fetch(mount.stripPrefix === true ? stripMountPrefix(req, mount.path) : req)
+      }
       // Exactly the prefix (`/api`) or a sub-path (`/api/…`) — NOT a sibling like `/apixyz` that merely
       // shares the prefix as a string head. Dispatch the original `req` (body intact) to the backend.
-      if (pathname === apiPrefix || pathname.startsWith(`${apiPrefix}/`)) {
-        return mountedApi(req, platform)
+      if (mountedApi !== undefined && apiPrefix !== "" && underPrefix(pathname, apiPrefix)) {
+        return mountedApi(apiStrip ? stripMountPrefix(req, apiPrefix) : req, platform)
       }
       return undefined // not an API path → continue to page routing
     })
@@ -1103,24 +1445,201 @@ export function createWebApp<Env = unknown>(
   // path under a `"404"` route is rejected (it isn't a static file, and the route declared it shouldn't
   // SSR on demand). O(1) membership via a Set.
   const prerenderedSet = new Set(options.prerenderedPaths ?? [])
+  const matchManifestRoute = createMatcher(
+    manifest.routes.map((route) => ({ routeId: route.id, pattern: route.pattern })),
+  )
+  const routeById = new Map(manifest.routes.map((route) => [route.id, route]))
 
   // Load a route's layout modules (outermost layout → innermost), keeping each module whole so the
   // render path can take both its `default` (the component chain) AND its `meta` (the sitewide head it
   // contributes). Loaded lazily — the data-only and 405 branches return before any layout is needed.
-  const loadLayoutModules = (
-    route: RouteEntry,
-  ): Promise<ReadonlyArray<{ default: unknown; meta?: MetaInput }>> =>
-    Promise.all(
+  const loadLayoutModules = async (route: RouteEntry): Promise<LoadedLayoutModules> => {
+    const modules = await Promise.all(
       // layoutIds only reference layouts present in the manifest (buildManifest invariant).
       route.layoutIds.map((id) => (manifest.layouts[id] as LayoutEntry).load()),
     )
+    // A layout is not a form target, so an `action` there is a mistake with no meaning to give it.
+    // A `loader`, by contrast, now runs (see `runLayoutChain`).
+    for (let i = 0; i < modules.length; i++) {
+      if ((modules[i] as { action?: unknown }).action === undefined) continue
+      const id = route.layoutIds[i] as string
+      throw new Error(
+        `[nifra/web] "${(manifest.layouts[id] as LayoutEntry).file}" exports an \`action\`, but layouts do not run one — only route files do. Move the mutation into the route that submits to it.`,
+      )
+    }
+    return modules
+  }
+
+  /**
+   * Run a route's layout-chain loaders, honouring declared gates.
+   *
+   * Returns once every **gate** has resolved, with the non-gate loaders still in flight, so the caller
+   * can start the page loader at exactly the right moment: after anything that might reject the
+   * request, alongside anything that merely fetches.
+   *
+   * The ordering is the security-relevant part. Parallel loaders are NOT an authorization boundary -
+   * a page loader running concurrently with a guard has already queried by the time the guard says no.
+   * Remix documents that as a footgun; here it is a declaration instead. `export const gate = true`
+   * makes a layout blocking for everything beneath it, and nothing beneath a rejected gate runs.
+   *
+   * Each layout receives only the params it OWNS ({@link RouteEntry.layoutParams}), not the route's
+   * full set, so a layout at `orgs/[org]/` cannot read a param belonging to a route below it.
+   */
+  /**
+   * Layout indices a client navigation asked to keep, from {@link RETAIN_HEADER}.
+   *
+   * The CLIENT decides retainability: it knows each layout's scoped params (shipped in the bootstrap)
+   * and both the old and new match, so it can tell whether a layout's own prefix changed - without the
+   * server re-matching a path the client already matched.
+   *
+   * It is a HINT, not an instruction. The client is asking to keep data it already holds, which is
+   * harmless for data and unacceptable for a guard, so `runLayoutChain` refuses to skip a gate no
+   * matter what arrives here. Anything unparseable is ignored rather than rejected: the worst case of
+   * a bad hint is a loader that runs when it need not.
+   */
+  const retainedIndices = (header: string | null): ReadonlySet<number> => {
+    if (header === null || header === "") return EMPTY_RETAIN
+    const out = new Set<number>()
+    for (const part of header.split(",")) {
+      // Digits only. `Number("")` is 0 and `Number(" ")` is 0, so a stray comma would otherwise read
+      // as "retain index 0" and silently skip the outermost layout.
+      if (!/^\d+$/.test(part)) continue
+      out.add(Number(part))
+    }
+    return out
+  }
+
+  /**
+   * Validate a data-navigation's retain request against the manifest and its declared source path.
+   * A client may ask to retain every slot it currently has; the server only honours indices whose
+   * layout identity and owned params are unchanged. Hard document GETs never retain anything.
+   */
+  const validatedRetainedIndices = (
+    req: Request,
+    route: RouteEntry,
+    params: Readonly<Record<string, string>>,
+  ): ReadonlySet<number> => {
+    if (req.headers.get(DATA_HEADER) === null) return EMPTY_RETAIN
+    const requested = retainedIndices(req.headers.get(RETAIN_HEADER))
+    const from = req.headers.get(NAV_FROM_HEADER)
+    if (requested.size === 0 || from === null) return EMPTY_RETAIN
+    let fromPath: string
+    try {
+      const current = new URL(req.url)
+      const source = new URL(from, current)
+      if (source.origin !== current.origin) return EMPTY_RETAIN
+      fromPath = source.pathname + source.search
+    } catch {
+      return EMPTY_RETAIN
+    }
+    const previousMatch = matchManifestRoute(fromPath)
+    if (previousMatch === null) return EMPTY_RETAIN
+    const previous = routeById.get(previousMatch.routeId)
+    if (previous === undefined) return EMPTY_RETAIN
+    const valid = new Set<number>()
+    for (const index of requested) {
+      if (route.layoutIds[index] !== previous.layoutIds[index]) continue
+      const owned = route.layoutParams?.[index] ?? []
+      const previouslyOwned = previous.layoutParams?.[index] ?? []
+      if (
+        owned.length !== previouslyOwned.length ||
+        owned.some((name, i) => name !== previouslyOwned[i]) ||
+        owned.some((name) => params[name] !== previousMatch.params[name])
+      ) {
+        continue
+      }
+      valid.add(index)
+    }
+    return valid
+  }
+
+  const runLayoutChain = async (
+    route: RouteEntry,
+    ctx: LoaderContext,
+    retain: ReadonlySet<number> = new Set(),
+  ): Promise<{
+    readonly modules: LoadedLayoutModules
+    readonly layoutData: readonly unknown[] | undefined
+    readonly retained: readonly number[]
+    readonly pending: Promise<unknown>
+  }> => {
+    const modules = await loadLayoutModules(route)
+    if (!modules.some((m) => m.loader !== undefined)) {
+      // Nothing to run: no array is produced, so a page-only app serializes nothing extra and its
+      // HTML is byte-identical to before this feature.
+      return { modules, layoutData: undefined, retained: [], pending: Promise.resolve() }
+    }
+    const results: unknown[] = new Array(modules.length).fill(null)
+    const retained: number[] = []
+    const pending: Array<Promise<void>> = []
+    for (let i = 0; i < modules.length; i++) {
+      const loader = modules[i]?.loader
+      if (loader === undefined) continue
+      // Unchanged scope: the client keeps what it has. A GATE is never skipped - it is a guard, and a
+      // guard that only runs when the URL prefix changed is not a guard.
+      if (retain.has(i) && modules[i]?.gate !== true) {
+        retained.push(i)
+        continue
+      }
+      const scoped: LoaderContext = {
+        ...ctx,
+        params: scopeParams(ctx.params, route.layoutParams?.[i]),
+      }
+      if (modules[i]?.gate === true) {
+        // Blocking: awaited here, so a throw propagates before anything deeper is started.
+        try {
+          results[i] = await loader(scoped)
+        } catch (err) {
+          throw tagLayoutError(err, route.layoutIds[i] as string)
+        }
+        continue
+      }
+      const layoutId = route.layoutIds[i] as string
+      const index = i
+      // The loader is invoked INSIDE the async function, not before it. `Promise.resolve(loader(x))`
+      // would let a synchronously-throwing loader escape past the rejection handler entirely - the
+      // exception happens while evaluating the argument, before any promise exists to reject.
+      pending.push(
+        (async () => {
+          try {
+            results[index] = await loader(scoped)
+          } catch (err) {
+            throw tagLayoutError(err, layoutId)
+          }
+        })(),
+      )
+    }
+    return { modules, layoutData: results, retained, pending: Promise.all(pending) }
+  }
+
+  /** Run only blocking layout gates before a route action. Non-gate loaders fetch render data and
+   * therefore run after the mutation when a native POST needs a fresh document. */
+  const runLayoutGates = async (
+    route: RouteEntry,
+    ctx: LoaderContext,
+  ): Promise<LoadedLayoutModules> => {
+    const modules = await loadLayoutModules(route)
+    for (let i = 0; i < modules.length; i++) {
+      const mod = modules[i]
+      if (mod?.gate !== true || mod.loader === undefined) continue
+      try {
+        await mod.loader({
+          ...ctx,
+          params: scopeParams(ctx.params, route.layoutParams?.[i]),
+        })
+      } catch (err) {
+        throw tagLayoutError(err, route.layoutIds[i] as string)
+      }
+    }
+    return modules
+  }
 
   // Build a route's render chain + its merged `<head>` from the already-loaded layout modules + the
   // page module. The chain is `[…layout components, page]`; the head merges each layout's `meta`
   // export (outermost→innermost) with the page's (last), so a `head`/`meta` on `_layout.tsx`
   // contributes sitewide tags. `metaArgs` (loader data + params) feed function-form `meta`s.
   const resolveChainAndHead = (
-    layoutModules: ReadonlyArray<{ default: unknown; meta?: MetaInput }>,
+    layoutModules: LoadedLayoutModules,
     page: RouteModule,
     metaArgs: MetaArgs,
   ): { chain: unknown[]; head: Meta } => {
@@ -1136,6 +1655,26 @@ export function createWebApp<Env = unknown>(
   const dirOfId = (id: string, suffix: string): string =>
     id === suffix ? "" : id.slice(0, id.length - suffix.length - 1)
 
+  /**
+   * Choose the `_error` boundary for a failure, respecting where a LAYOUT loader failed.
+   *
+   * A route error uses the nearest boundary, as it always has. A layout error must not: the nearest
+   * boundary can sit BELOW the layout that threw, and rendering there would wrap the boundary in that
+   * very layout - the one whose loader just failed and whose data therefore never arrived.
+   */
+  const boundaryFor = (route: RouteEntry, err: unknown): string | undefined => {
+    const ids = route.errorIds ?? []
+    const failing = layoutErrorId(err)
+    if (failing === undefined) return ids.at(-1)
+    const layoutDir = dirOfId(failing, "_layout")
+    // Deepest boundary at or ABOVE the failing layout's directory.
+    for (let i = ids.length - 1; i >= 0; i--) {
+      const errDir = dirOfId(ids[i] as string, "_error")
+      if (errDir === "" || errDir === layoutDir || layoutDir.startsWith(`${errDir}/`)) return ids[i]
+    }
+    return undefined
+  }
+
   // The request's origin (scheme + host + port, NO trailing slash) — the one server fact `meta()` needs
   // for absolute `canonical`/`og:url`/`og:image` but can't otherwise see (it also runs on the client).
   // `URL.origin` is exactly that shape; it matches the browser's `location.origin` for the same URL, so
@@ -1203,31 +1742,76 @@ export function createWebApp<Env = unknown>(
   // The 404 response — the `_404` page (status 404) or a plain-text fallback. Shared by the wildcard
   // catch-all (unmatched paths) and the `fallback: "404"` enforcement (unlisted paths under a route
   // that opted out of on-demand SSR).
-  const renderNotFound = async (path?: string): Promise<Response | RenderedPage> => {
-    if (manifest.notFound === undefined) {
-      return new Response("Not Found", {
-        status: 404,
-        headers: { "content-type": "text/plain; charset=utf-8" },
-      })
+  const renderNotFound = (path?: string): Promise<Response | RenderedPage> =>
+    renderTerminalStatus(404, path)
+
+  /**
+   * Render a terminal-status page: the `_<status>` page if the app authored one, else `_404`, else
+   * plain text. Shared by the wildcard catch-all, `fallback: "404"` enforcement, and a loader's
+   * `notFound()` / `gone()` / `statusPage()`, so all of them resolve the page and set the status
+   * through one path rather than forking.
+   *
+   * Hydrates, following the `_404` precedent rather than `_error`'s non-hydrated 500: these are
+   * ordinary pages the client router can own, and a 404 arrived at by clicking a link should behave
+   * like any other route.
+   */
+  const renderTerminalStatus = async (
+    status: number,
+    path?: string,
+    extraHeaders?: HeadersLike,
+  ): Promise<Response | RenderedPage> => {
+    const page = manifest.statusPages?.[String(status)] ?? manifest.notFound
+    if (page === undefined) {
+      const headers = new Headers(extraHeaders)
+      headers.set("content-type", "text/plain; charset=utf-8")
+      return new Response(STATUS_TEXT[status] ?? "Error", { status, headers })
     }
-    const { default: notFound } = await manifest.notFound.load()
+    // The routeId decides which preload/style bundle and which client component this maps to, so it
+    // must name the page actually rendered - `_410` when `_410.tsx` exists, `_404` when it fell back.
+    const routeId = manifest.statusPages?.[String(status)] !== undefined ? `_${status}` : "_404"
+    const { default: component } = await page.load()
     return renderPageResult({
       adapter,
-      chain: [notFound],
+      chain: [component],
       data: null,
       clientEntry,
-      routeId: "_404",
-      // `_404` hydrates, so its SSR `path` must equal the client's initial `location.pathname+search`
-      // (an unmatched path yields no params → `{}`), or a `useLocation` on the 404 page would drift.
+      routeId,
+      // The page hydrates, so its SSR `path` must equal the client's initial
+      // `location.pathname+search` (an unmatched path yields no params → `{}`), or a `useLocation`
+      // on it would drift.
       ...(path !== undefined ? { path } : {}),
-      status: 404,
-      ...preloadOf("_404"),
-      ...stylesOf("_404"),
+      status,
+      ...(extraHeaders !== undefined ? { headers: extraHeaders } : {}),
+      ...preloadOf(routeId),
+      ...stylesOf(routeId),
       prerenderedPaths: options.prerenderedPaths ?? [],
       ...titleOption,
     })
   }
 
+  /**
+   * Answer a loader's terminal-status signal, in whichever form the caller asked for.
+   *
+   * A hard navigation wants the document, so it gets the rendered boundary. A client-side navigation
+   * fetched DATA, not a document, so it gets an empty body plus the status on `X-Nifra-Status`, and
+   * the client router renders the same boundary from its own manifest. Sending the HTML back to a
+   * soft-nav would be answering a different question than the one asked - and skipping the header
+   * entirely is what leaves a crawler seeing a correct 404 while a user who clicked a link sees a
+   * blank page.
+   */
+  const renderStatusSignal = (
+    req: Request,
+    signal: StatusSignal,
+  ): Promise<Response | RenderedPage> | Response => {
+    const { status, headers } = signal[STATUS_SIGNAL]
+    if (req.headers.get(DATA_HEADER) !== null) {
+      const responseHeaders = new Headers(headers)
+      responseHeaders.set(STATUS_HEADER, String(status))
+      return new Response(null, { status, headers: responseHeaders })
+    }
+    return renderTerminalStatus(status, pathOf(req), headers)
+  }
+
   for (const route of manifest.routes) {
     // A dynamic route whose `getStaticPaths` declared `fallback: "404"` — only its prerendered paths
     // exist; anything else 404s (computed once per route, not per request).
@@ -1242,18 +1826,43 @@ export function createWebApp<Env = unknown>(
       const mod = await route.load()
       const draft = await draftFlag(c.req)
       let data: unknown
+      let layoutData: readonly unknown[] | undefined
+      let layoutModules: LoadedLayoutModules | undefined
+      let layoutRetained: readonly number[] = []
       try {
-        data = mod.loader
-          ? await mod.loader({
-              params: c.params,
-              request: c.req,
-              req: c.req,
-              api,
-              env: c.env,
-              draft,
-            })
-          : null
+        const ctx = {
+          params: c.params,
+          request: c.req,
+          req: c.req,
+          api,
+          env: c.env,
+          draft,
+        }
+        // Layout loaders run for BOTH the document and the data-only request. A gate that only ran on
+        // the document path would be bypassed by adding the data header, which is exactly the request
+        // a client navigation makes - a guard has to hold on the path an attacker can pick.
+        //
+        // `runLayoutChain` returns once every GATE has resolved, with the non-gate loaders still in
+        // flight. So the page loader starts as late as correctness requires and as early as speed
+        // allows, and both are awaited together below.
+        const run = await runLayoutChain(
+          route,
+          ctx,
+          validatedRetainedIndices(c.req, route, c.params),
+        )
+        layoutModules = run.modules
+        layoutRetained = run.retained
+        const [pageData] = await Promise.all([
+          mod.loader ? mod.loader(ctx) : null,
+          run.pending, // a non-gate layout loader that rejects must still surface, not go unhandled
+        ])
+        data = pageData
+        layoutData = run.layoutData
       } 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).
@@ -1266,7 +1875,7 @@ export function createWebApp<Env = unknown>(
             // A faulty reporter must never break error rendering.
           }
         }
-        const errorId = route.errorIds?.at(-1)
+        const errorId = boundaryFor(route, err)
         if (errorId === undefined) throw err
         // A soft-nav data fetch can't render a boundary — 500 so the client falls back to a full-page
         // navigation, which lands here as a document and renders the `_error` page.
@@ -1276,24 +1885,49 @@ export function createWebApp<Env = unknown>(
             headers: { "content-type": "text/plain; charset=utf-8" },
           })
         }
-        return renderError(route, errorId, err)
+        return renderError(route, errorId, withDuplicateInstanceHint(err))
       }
       // 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,
       // same auth — only the transport differs.
       if (c.req.headers.get(DATA_HEADER) !== null) {
-        const { forClient, deferred } = prepareDeferred(data)
-        if (deferred.length === 0) return Response.json(data ?? null)
-        return new Response(ndjsonStream(forClient, deferred), {
+        const pageSplit = prepareDeferred(data)
+        const layoutSplits: Array<ReturnType<typeof prepareDeferred>> = []
+        let offset = pageSplit.deferred.length
+        for (const entry of layoutData ?? []) {
+          const split = prepareDeferred(entry, offset)
+          layoutSplits.push(split)
+          offset += split.deferred.length
+        }
+        const deferred = [...pageSplit.deferred, ...layoutSplits.flatMap((split) => split.deferred)]
+        const payload =
+          layoutData === undefined
+            ? pageSplit.forClient
+            : {
+                v: 1 as const,
+                data: pageSplit.forClient,
+                layoutData: layoutSplits.map((split) => split.forClient),
+                retained: layoutRetained,
+              }
+        // 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) {
+          return Response.json(payload ?? null)
+        }
+        return new Response(ndjsonStream(payload, deferred), {
           headers: { "content-type": "application/x-ndjson; charset=utf-8" },
         })
       }
-      const { chain, head } = resolveChainAndHead(await loadLayoutModules(route), mod, {
-        data,
-        params: c.params,
-        origin: originOf(c.req),
-      })
+      const { chain, head } = resolveChainAndHead(
+        layoutModules ?? (await loadLayoutModules(route)),
+        mod,
+        {
+          data,
+          params: c.params,
+          origin: originOf(c.req),
+        },
+      )
       const hydrateRoute = mod.hydrate !== false
       try {
         // `await` so a shell-render throw (renderToStream rejects before any byte) is caught here and
@@ -1309,6 +1943,7 @@ export function createWebApp<Env = unknown>(
           params: c.params,
           path: pathOf(c.req),
           hydrate: hydrateRoute,
+          ...(layoutData !== undefined ? { layoutData } : {}),
           ...preloadOf(route.id),
           ...stylesOf(route.id),
           prerenderedPaths: options.prerenderedPaths ?? [],
@@ -1317,6 +1952,8 @@ export function createWebApp<Env = unknown>(
           ...titleOption,
         })
       } 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
         // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
         if (options.onLoaderError !== undefined) {
@@ -1326,9 +1963,9 @@ export function createWebApp<Env = unknown>(
             // A faulty reporter must never break error rendering.
           }
         }
-        const errorId = route.errorIds?.at(-1)
+        const errorId = boundaryFor(route, err)
         if (errorId === undefined) throw err
-        return renderError(route, errorId, err)
+        return renderError(route, errorId, withDuplicateInstanceHint(err))
       }
     })
 
@@ -1344,14 +1981,18 @@ export function createWebApp<Env = unknown>(
           headers: { allow: "GET", "content-type": "text/plain; charset=utf-8" },
         })
       }
-      const result = await mod.action({
+      const actionContext = {
         params: c.params,
         request: c.req,
         req: c.req,
         api,
         env: c.env,
         draft,
-      })
+      }
+      // A gate is an authorization boundary for everything beneath its layout, mutations included.
+      // Run only gates before the action; ordinary layout data loaders run after a native mutation.
+      const layoutModules = await runLayoutGates(route, actionContext)
+      const result = await mod.action(actionContext)
       const isDataRequest = c.req.headers.get(DATA_HEADER) !== null
       // An action may wrap its data in `revalidate(paths, data)` to declare which routes it changed.
       // Unwrap to the inner data; the paths ride the `X-Nifra-Revalidate` header on the data-mode
@@ -1386,7 +2027,7 @@ export function createWebApp<Env = unknown>(
       const data = mod.loader
         ? await mod.loader({ params: c.params, request: c.req, req: c.req, api, env: c.env, draft })
         : null
-      const { chain, head } = resolveChainAndHead(await loadLayoutModules(route), mod, {
+      const { chain, head } = resolveChainAndHead(layoutModules, mod, {
         data,
         params: c.params,
         origin: originOf(c.req),
@@ -1435,8 +2076,16 @@ export function createWebApp<Env = unknown>(
 }
 
 export interface GenerateClientEntryOptions {
-  /** Module specifier for the adapter's client runtime (exports `mountRouter`), e.g.
-   * `"@nifrajs/web-solid/client"`. */
+  /**
+   * Module specifier for the adapter's client runtime, e.g. `"@nifrajs/web-solid/client"`.
+   *
+   * **Contract:** the module MUST export `mountRouter({ router, routes, container })`. The generated
+   * bootstrap imports the specifier and calls it — so a self-executing entry that mounts on import
+   * builds cleanly and then does nothing, which is the trap this contract exists to name. The type is
+   * a bare `string` because a specifier is resolved by the bundler, not the type system, so the
+   * requirement is enforced by the bootstrap instead: it throws immediately, naming this module and
+   * the missing export, rather than failing later as `mountRouter is not a function`.
+   */
   readonly clientModule: string
   /** Turn a route/layout source file (relative to the routes dir) into an import specifier. */
   readonly resolve: (file: string) => string
@@ -1460,6 +2109,7 @@ export function generateClientEntry(
 
   const loaderRows: string[] = []
   const patternRows: string[] = []
+  const statusRoutes: Record<number, string> = {}
   // Routes whose loader appends a nearest `_error` module (LAST) — the client wraps the page in the
   // adapter's `errorBoundary(fallback)` for these, so a client render error shows the `_error` UI.
   const errorRouteIds: string[] = []
@@ -1489,6 +2139,12 @@ export function generateClientEntry(
   }
   if (manifest.notFound !== undefined) {
     loaderRows.push(`  "_404": ${lazyLoader([manifest.notFound.file])},`)
+    statusRoutes[404] = "_404"
+  }
+  for (const [status, entry] of Object.entries(manifest.statusPages ?? {})) {
+    const routeId = `_${status}`
+    loaderRows.push(`  ${JSON.stringify(routeId)}: ${lazyLoader([entry.file])},`)
+    statusRoutes[Number(status)] = routeId
   }
 
   return `${[
@@ -1498,6 +2154,16 @@ export function generateClientEntry(
     // access yields `undefined` if absent — unlike a named import, which would be a link error.
     `import * as __adapter from ${JSON.stringify(clientModule)}`,
     "const { mountRouter } = __adapter",
+    // The `clientModule` contract is a string specifier, so nothing type-checks that the module it
+    // names actually exports `mountRouter`. Without this the miss surfaces as
+    // "mountRouter is not a function" from inside a bundled chunk, at first paint, naming neither the
+    // module nor the requirement - a self-executing entry passes every build and fails only here.
+    `if (typeof mountRouter !== "function") throw new Error(${JSON.stringify(
+      `[nifra/web] clientModule ${JSON.stringify(clientModule)} does not export \`mountRouter\`. ` +
+        "A client module must export `mountRouter({ router, routes, container })` — it is called by " +
+        "the generated bootstrap, so a self-executing entry will not work. Use your adapter's " +
+        '`/client` entry (e.g. "@nifrajs/web-react/client"), or re-export mountRouter from it.',
+    )})`,
     "const errorBoundary = __adapter.errorBoundary",
     `const errorRouteIds = new Set(${JSON.stringify(errorRouteIds)})`,
     // Each route is a lazy loader: dynamic imports → Bun.build (splitting) emits one chunk per
@@ -1547,13 +2213,16 @@ export function generateClientEntry(
     // page reading the search string would hydrate-mismatch. The #hash is client-only (never SSR'd).
     "  path: location.pathname + location.search,",
     `  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),`,
     // 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).
     `  actionData: mapDeferred(window.${ACTION_GLOBAL}),`,
     "  pending: false,",
     "}",
-    "const router = createClientRouter({ patterns, initial, loadModule })",
+    `const statusRoutes = ${JSON.stringify(statusRoutes)}`,
+    "const router = createClientRouter({ patterns, initial, loadModule, statusRoutes })",
     "installHistory(router)",
     "installForms(router)",
     'const root = document.getElementById("root")',
@@ -1603,7 +2272,7 @@ export interface GenerateServerManifestOptions {
  * Codegen: emit a **server manifest** module (as source) for disk-less edge runtimes (Cloudflare
  * Workers, …) — and, with a `target`, any portable server bundle. `discoverRoutes` scans `node:fs`
  * and dynamic-imports each route by a *runtime* path — neither exists on workerd. This instead emits
- * **statically-analyzable** imports of every route/layout/`_error`/`_404` (so the bundler includes them) and
+ * **statically-analyzable** imports of every route/layout/`_error`/terminal status page (so the bundler includes them) and
  * rebuilds the manifest with `buildManifest` — the SAME pure logic `discoverRoutes` feeds, so patterns
  * + layout chains are identical. Eager (`import * as`) by default; `lazy` emits `() => import(...)` so
  * a code-splitting bundler chunks per route. The emitted module exports `manifest` (consumed by
@@ -1615,13 +2284,14 @@ export function generateServerManifest(
   options: GenerateServerManifestOptions,
 ): string {
   const { resolve, clientEntry, styles, routeStyles, lazy = false } = options
-  // Every unique source file in the manifest (routes + layouts + `_error` + `_404`), sorted for stable output.
+  // Every unique source file in the manifest (routes + layouts + error/status pages), sorted for stable output.
   const files = [
     ...new Set([
       ...manifest.routes.map((r) => r.file),
       ...Object.values(manifest.layouts).map((l) => l.file),
       ...Object.values(manifest.errors ?? {}).map((e) => e.file),
       ...(manifest.notFound ? [manifest.notFound.file] : []),
+      ...Object.values(manifest.statusPages ?? {}).map((page) => page.file),
     ]),
   ].sort()
   const header = [