@nifrajs/web 2.0.0 → 2.2.0

package/dist/index.js

@@ -13,9 +13,9 @@ import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, defer, MAP_DEFERRED_SOURCE, ndjs
 import { isDraftEnabled } from "./draft.js";
 import { ISR_REVALIDATE_HEADER } from "./isr.js";
 import { generateLlmsTxt } from "./llms-txt.js";
-import { DATA_HEADER, PRERENDERED_GLOBAL, REDIRECT_HEADER, REVALIDATE_HEADER, } from "./router.js";
+import { createMatcher, DATA_HEADER, NAV_FROM_HEADER, PRERENDERED_GLOBAL, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, STATUS_HEADER, } from "./router.js";
 // Draft / preview mode — a signed cookie that flips `ctx.draft` for loaders + bypasses ISR for editors.
-export { DRAFT_COOKIE, disableDraft, enableDraft, isDraftEnabled, } from "./draft.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";
 // ISR (incremental static regeneration): a pluggable cache store + the `withISR` stale-while-revalidate
@@ -26,17 +26,22 @@ export { buildManifest, enumerateStaticRoutes, filePathToPattern, filePathToPatt
 // Navigation bridge — a DOM-free seam the browser layer (`installHistory`) populates so an adapter's
 // `useNavigate` (a route component, importing only this agnostic entry) reaches history-aware nav.
 export { getBrowserNavigate, setBrowserNavigate, } from "./navigation.js";
+// public/ — user-authored static files, served identically in dev and production by one handler.
+export { resolvePublicPath, servePublicDir, } from "./public-dir.js";
 // Keyed query-cache (agnostic) — a `query(key, fn)` primitive (dedup + staleness + invalidation + GC)
 // consumed by the per-adapter `useQuery`/`createQuery` bindings.
 export { createMutation, createQueryClient, hashQueryKey, } from "./query.js";
 // Agnostic client-side router core (pure + DOM-free) — consumed by per-adapter Router bindings.
 // `DATA_HEADER` marks a navigation's data-only GET; `createWebApp` answers it with loader JSON.
-export { createClientRouter, createMatcher, DATA_HEADER, REDIRECT_HEADER, REVALIDATE_HEADER, } from "./router.js";
+export { createClientRouter, createMatcher, DATA_HEADER, NAV_FROM_HEADER, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, STATUS_HEADER, } from "./router.js";
 // Deferred loader data (`defer()` + the `Deferred<T>` type) — consumed by the adapter's `<Await>`.
 export { defer };
 export { assertRenderAdapterConformance, RenderAdapterConformanceError, } from "./conformance.js";
 /** 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__";
 /** Global the server serializes an action's data return into (absent on GETs); the client
@@ -97,7 +102,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, routeId, status = 200, title = "nifra", head, rootId = "root", hydrate = true, islandScripts = [], } = options;
+    const { adapter, chain, data, actionData, clientEntry, preload = [], styles = [], prerenderedPaths = [], revalidate, routeId, status = 200, title = "nifra", head, 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
     // `_data.json` on soft-nav into a prerendered route instead of hitting the worker. Empty ⇒ omitted.
@@ -109,8 +114,26 @@ export function renderPageResult(options) {
     // 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);
-    const actionSplit = actionData === undefined ? undefined : prepareDeferred(actionData, deferred.length);
-    const allDeferred = actionSplit ? [...deferred, ...actionSplit.deferred] : deferred;
+    // 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 = [];
+    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 + 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
         ? ""
@@ -153,7 +176,13 @@ export function renderPageResult(options) {
     // 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>";
@@ -165,9 +194,18 @@ export function renderPageResult(options) {
     for (const src of islandScripts)
         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 = { "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.
@@ -181,6 +219,10 @@ export function renderPageResult(options) {
         // 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
     // whole document in one pass. Progressive streaming only benefits pages with deferred boundaries
@@ -322,6 +364,143 @@ export function redirect(location, options = {}) {
     }
     return new Response(null, { status: options.status ?? 303, headers: { location } });
 }
+/**
+ * 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 = [
+    /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) {
+    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;
+}
+/**
+ * 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, owned) {
+    if (owned === undefined)
+        return params; // hand-built manifest with no scope info: unchanged behaviour
+    if (owned.length === 0)
+        return EMPTY_LAYOUT_PARAMS;
+    const scoped = {};
+    for (const name of owned) {
+        const value = params[name];
+        if (value !== undefined)
+            scoped[name] = value;
+    }
+    return scoped;
+}
+const EMPTY_LAYOUT_PARAMS = Object.freeze({});
+const EMPTY_RETAIN = new Set();
+/**
+ * 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, layoutId) => {
+    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) => typeof err === "object" && err !== null
+    ? err[LAYOUT_ERROR_ID]
+    : 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 = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    410: "Gone",
+    451: "Unavailable For Legal Reasons",
+    500: "Internal Server Error",
+};
+function isStatusSignal(value) {
+    return value instanceof Response && STATUS_SIGNAL in value;
+}
+function statusSignal(status, options) {
+    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;
+}
+/**
+ * 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 = {}) {
+    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 = {}) {
+    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, options = {}) {
+    return statusSignal(status, options);
+}
 /**
  * Return this from an action to declare which routes the mutation changed (alongside the action's
  * `data`). `createWebApp` sets the `X-Nifra-Revalidate` response header; after the submit the client
@@ -508,12 +687,18 @@ export function mergeHeads(heads) {
     if (heads.length === 1)
         return heads[0];
     let title;
+    let lang;
+    let dir;
     const meta = [];
     const link = [];
     const script = [];
     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)
@@ -534,8 +719,32 @@ export function mergeHeads(heads) {
         merged.link = link;
     if (script.length > 0)
         merged.script = script;
+    if (lang !== undefined)
+        merged.lang = lang;
+    if (dir !== undefined)
+        merged.dir = dir;
     return merged;
 }
+/**
+ * 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, prefix) {
+    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.
@@ -597,14 +806,26 @@ export function createWebApp(options) {
     // 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, prefix) => 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
         });
@@ -613,12 +834,179 @@ export function createWebApp(options) {
     // 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) => Promise.all(
-    // layoutIds only reference layouts present in the manifest (buildManifest invariant).
-    route.layoutIds.map((id) => manifest.layouts[id].load()));
+    const loadLayoutModules = async (route) => {
+        const modules = await Promise.all(
+        // layoutIds only reference layouts present in the manifest (buildManifest invariant).
+        route.layoutIds.map((id) => manifest.layouts[id].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].action === undefined)
+                continue;
+            const id = route.layoutIds[i];
+            throw new Error(`[nifra/web] "${manifest.layouts[id].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) => {
+        if (header === null || header === "")
+            return EMPTY_RETAIN;
+        const out = new Set();
+        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, route, params) => {
+        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;
+        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();
+        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, ctx, retain = new Set()) => {
+        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 = new Array(modules.length).fill(null);
+        const retained = [];
+        const pending = [];
+        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 = {
+                ...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]);
+                }
+                continue;
+            }
+            const layoutId = route.layoutIds[i];
+            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, ctx) => {
+        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]);
+            }
+        }
+        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`
@@ -633,6 +1021,27 @@ export function createWebApp(options) {
     };
     // Dir a special-file id lives in: `_error`→"" , `a/b/_error`→"a/b" (and likewise for `_layout`).
     const dirOfId = (id, suffix) => 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, err) => {
+        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], "_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
@@ -691,30 +1100,65 @@ export function createWebApp(options) {
     // 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) => {
-        if (manifest.notFound === undefined) {
-            return new Response("Not Found", {
-                status: 404,
-                headers: { "content-type": "text/plain; charset=utf-8" },
-            });
+    const renderNotFound = (path) => 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, path, extraHeaders) => {
+        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, signal) => {
+        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).
@@ -729,19 +1173,41 @@ export function createWebApp(options) {
             const mod = await route.load();
             const draft = await draftFlag(c.req);
             let data;
+            let layoutData;
+            let layoutModules;
+            let layoutRetained = [];
             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).
@@ -756,7 +1222,7 @@ export function createWebApp(options) {
                         // 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
@@ -767,21 +1233,40 @@ export function createWebApp(options) {
                         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 = [];
+                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,
+                        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, {
+            const { chain, head } = resolveChainAndHead(layoutModules ?? (await loadLayoutModules(route)), mod, {
                 data,
                 params: c.params,
                 origin: originOf(c.req),
@@ -801,6 +1286,7 @@ export function createWebApp(options) {
                     params: c.params,
                     path: pathOf(c.req),
                     hydrate: hydrateRoute,
+                    ...(layoutData !== undefined ? { layoutData } : {}),
                     ...preloadOf(route.id),
                     ...stylesOf(route.id),
                     prerenderedPaths: options.prerenderedPaths ?? [],
@@ -810,6 +1296,9 @@ export function createWebApp(options) {
                 });
             }
             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.
@@ -821,10 +1310,10 @@ export function createWebApp(options) {
                         // 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));
             }
         });
         // POST runs the route's `action` (mutation). A `Response` return (e.g. a `redirect(...)`)
@@ -839,14 +1328,18 @@ export function createWebApp(options) {
                     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
@@ -880,7 +1373,7 @@ export function createWebApp(options) {
             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),
@@ -937,6 +1430,7 @@ export function generateClientEntry(manifest, options) {
     const { clientModule, resolve } = options;
     const loaderRows = [];
     const patternRows = [];
+    const statusRoutes = {};
     // 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 = [];
@@ -963,6 +1457,12 @@ export function generateClientEntry(manifest, options) {
     }
     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 `${[
         'import { createClientRouter, createMatcher, mergeHeads, resolveMeta } from "@nifrajs/web"',
@@ -971,6 +1471,14 @@ export function generateClientEntry(manifest, options) {
         // 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
@@ -1020,13 +1528,16 @@ export function generateClientEntry(manifest, options) {
         // 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")',
@@ -1054,7 +1565,7 @@ export function generateClientEntry(manifest, options) {
  * 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
@@ -1063,13 +1574,14 @@ export function generateClientEntry(manifest, options) {
  */
 export function generateServerManifest(manifest, options) {
     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 = [