@nifrajs/web 0.1.0-alpha.1

package/dist/index.js

@@ -0,0 +1,784 @@
+/**
+ * @nifrajs/web — the framework-agnostic SSR core. It owns the render *seam* and the HTML
+ * document orchestration, and knows nothing about any specific UI framework: a render
+ * adapter (@nifrajs/web-solid, @nifrajs/web-react, …) supplies the actual render + hydrate.
+ *
+ * The core treats a "component" and a hydration "container" as opaque `unknown` — only
+ * the adapter interprets them. That keeps this package both framework-agnostic and free
+ * of DOM types: it is pure server orchestration + string building.
+ */
+import { server } from "@nifrajs/core";
+import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, defer, MAP_DEFERRED_SOURCE, ndjsonStream, prepareDeferred, } from "./deferred.js";
+import { isDraftEnabled } from "./draft.js";
+import { ISR_REVALIDATE_HEADER } from "./isr.js";
+import { DATA_HEADER, PRERENDERED_GLOBAL, REDIRECT_HEADER, REVALIDATE_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";
+// 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
+// wrapper for rendered SSR responses.
+export { ISR_REVALIDATE_HEADER, ISR_STATUS_HEADER, KVCacheStore, MemoryCacheStore, revalidateEndpoint, withISR, } from "./isr.js";
+// File-based routing manifest — pure + fs-free. `discoverRoutes` (fs) lives in `@nifrajs/web/fs`.
+export { buildManifest, enumeratePrerenderedPaths, enumerateStaticRoutes, filePathToPattern, filePathToPatterns, } from "./manifest.js";
+// Keyed query-cache (agnostic) — a `query(key, fn)` primitive (dedup + staleness + invalidation + GC)
+// consumed by the per-adapter `useQuery`/`createQuery` bindings.
+export { 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";
+// Deferred loader data (`defer()` + the `Deferred<T>` type) — consumed by the adapter's `<Await>`.
+export { defer };
+/** Global the server serializes loader data into; the client reads it to hydrate. */
+export const DATA_GLOBAL = "__NIFRA_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
+ * reads it so hydration after a native form POST matches the server-rendered markup. */
+export const ACTION_GLOBAL = "__NIFRA_ACTION__";
+// Shared, stateless — allocated once at module load, not per render/stream.
+const TEXT_ENCODER = new TextEncoder();
+// XSS-safe `<script>` JSON escaping in a SINGLE pass: `<`/`>` would break out of the
+// script element; U+2028/U+2029 are valid JSON but historically break JS string literals. Built via
+// fromCharCode so no raw separator chars live in this source. One regex + one output string replaces
+// the prior four sequential `replaceAll` full-string passes.
+const LINE_SEP = String.fromCharCode(0x2028);
+const PARA_SEP = String.fromCharCode(0x2029);
+const SCRIPT_ESCAPE = new RegExp(`[<>${LINE_SEP}${PARA_SEP}]`, "g");
+const SCRIPT_ESCAPE_MAP = {
+    "<": "\\u003c",
+    ">": "\\u003e",
+    [LINE_SEP]: "\\u2028",
+    [PARA_SEP]: "\\u2029",
+};
+const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body");
+const RESPONSE_RESULT = Symbol.for("nifra.response.result");
+/**
+ * Server: render a full HTML document for a page — the adapter's hydration head + the SSR
+ * markup (**streamed**) + the serialized loader data + the client module — as a `Response`.
+ * The shell (`<head>` + the open container) flushes first, the adapter's app stream follows,
+ * then the tail (data globals + client entry). Pure Web Standards, so it returns straight from
+ * a nifra route handler and streams on any fetch runtime (Bun/Node/Deno/Workers).
+ */
+export function renderPage(options) {
+    const page = renderPageResult(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 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.
+    const prerendered = prerenderedPaths.length === 0
+        ? ""
+        : `window.${PRERENDERED_GLOBAL}=${serializeData(prerenderedPaths)};`;
+    // Split deferred values: the component sees markers (id + promise) to `<Await>`; the serialized
+    // data carries `{__nifra_deferred: id}` placeholders (promises don't serialize). `actionData` may
+    // 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;
+    // Only emit the action global when an action actually ran, so plain GET output is unchanged.
+    const action = actionSplit === undefined
+        ? ""
+        : `window.${ACTION_GLOBAL}=${serializeData(actionSplit.forClient)};`;
+    const deferredRuntime = allDeferred.length > 0 ? `<script>${DEFERRED_RUNTIME}</script>` : "";
+    // Matched-route chunk preloads, concatenated directly (skip the `filter().map()`
+    // intermediate arrays — and the whole loop — on the common no-extra-preload render). De-duped
+    // against the entry, which is preloaded separately below.
+    let preloadLinks = "";
+    if (preload.length > 0) {
+        for (const url of preload) {
+            if (url !== clientEntry)
+                preloadLinks += `<link rel="modulepreload" href="${escapeAttr(url)}">`;
+        }
+    }
+    // The matched route's stylesheets — `<link rel="stylesheet">` in `<head>` so CSS arrives with the
+    // first paint (no FOUC). Render-blocking by design, and emitted regardless of `hydrate` (a static or
+    // `_error` page still wants its styles). In dev (Vite) CSS is injected client-side instead, so
+    // `styles` is empty there.
+    let styleLinks = "";
+    for (const url of styles)
+        styleLinks += `<link rel="stylesheet" href="${escapeAttr(url)}">`;
+    // Island bundles are referenced only by a `<script type="module">` at the END of `<body>` (below), so
+    // the browser doesn't discover them until the whole page is parsed. `modulepreload` them in `<head>`
+    // so the fetch starts immediately, in parallel with parsing — regardless of `hydrate` (an island page
+    // is typically hydrate:false). Without this, a heavy island bundle on a cold first load leaves its
+    // server-rendered placeholder visible until that late, un-prefetched fetch lands ("stuck loading").
+    let islandPreloads = "";
+    for (const src of islandScripts)
+        islandPreloads += `<link rel="modulepreload" href="${escapeAttr(src)}">`;
+    // Shell — flushed before the app finishes rendering: `<head>` (title, meta, hydration head) + the
+    // open container. `modulepreload` of the client entry — plus the matched route's own chunks
+    // (`preloadLinks`) — lets the JS download while the body streams. One template literal (no
+    // intermediate array + `join`) — byte-identical to the prior output.
+    // A non-hydrated page (e.g. an `_error` boundary) omits the client-entry preload, route-chunk
+    // preloads, and deferred runtime — there's no client takeover to feed.
+    const hydrationLinks = hydrate
+        ? `<link rel="modulepreload" href="${escapeAttr(clientEntry)}">${preloadLinks}${deferredRuntime}`
+        : "";
+    const shellHtml = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><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>";
+    // Tail — the loader-data globals + the client module. Module scripts defer (run after parse), so
+    // the data global + every streamed deferred resolution are set before the entry hydrates.
+    // Island bundles load regardless of `hydrate` — a static page (hydrate:false) ships no framework
+    // client but can still mount no-framework islands (`@nifrajs/web/islands`).
+    let islandTags = "";
+    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>`
+        : ""}${islandTags}</body></html>`;
+    const headers = { "content-type": "text/html; charset=utf-8" };
+    // 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.
+    if (revalidate !== undefined)
+        headers[ISR_REVALIDATE_HEADER] = String(revalidate);
+    const renderProps = { data: forComponent, actionData: actionSplit?.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
+    // (those take the streaming path below); for a plain page the streaming pipeline + the framework's
+    // streaming renderer are pure overhead vs a single sync render + concat. A buffered string body also
+    // gets an automatic Content-Length. A render throw surfaces here exactly as the streaming path's
+    // shell-readiness `await` does, so the `_error` boundary still maps it to a status.
+    if (allDeferred.length === 0 && adapter.renderToString !== undefined) {
+        const out = adapter.renderToString(chain, renderProps);
+        return typeof out === "string"
+            ? new BufferedRenderedPage(shellHtml + out + closeRootHtml + tailHtml, status, headers)
+            : out.then((bodyHtml) => new BufferedRenderedPage(shellHtml + bodyHtml + closeRootHtml + tailHtml, status, headers));
+    }
+    return renderStreamedPage(adapter, chain, renderProps, shellHtml, closeRootHtml, allDeferred, tailHtml, status, headers).then((response) => new ResponseRenderedPage(response));
+}
+async function renderStreamedPage(adapter, chain, renderProps, shellHtml, closeRootHtml, allDeferred, tailHtml, status, headers) {
+    // Streaming path — required for `defer()` (progressive `<Await>` resolution) and used by any adapter
+    // that doesn't implement `renderToString`. Awaiting `renderToStream` resolves on shell-readiness
+    // (React: on-shell-ready; Solid: synchronously), so a shell-render throw surfaces before any byte is
+    // sent. A *mid*-stream failure errors the body instead.
+    const enc = TEXT_ENCODER;
+    const shell = enc.encode(shellHtml);
+    const closeRoot = enc.encode(closeRootHtml);
+    const tail = enc.encode(tailHtml);
+    const appStream = await adapter.renderToStream(chain, renderProps);
+    const body = streamDocument(shell, appStream, closeRoot, allDeferred, tail, enc);
+    return new Response(body, { status, headers });
+}
+class BufferedRenderedPage {
+    [RESPONSE_RESULT] = true;
+    body;
+    status;
+    headers;
+    constructor(body, status, headers) {
+        this.body = body;
+        this.status = status;
+        this.headers = headers;
+    }
+    toResponse() {
+        return htmlResponse(this.body, { status: this.status, headers: this.headers });
+    }
+    toNodeBody() {
+        return { status: this.status, headers: this.headers, body: this.body };
+    }
+}
+class ResponseRenderedPage {
+    [RESPONSE_RESULT] = true;
+    response;
+    constructor(response) {
+        this.response = response;
+    }
+    toResponse() {
+        return this.response;
+    }
+}
+function htmlResponse(body, init) {
+    const response = new Response(body, init);
+    // @nifrajs/node can write buffered HTML straight to ServerResponse with `end(body)`, avoiding a Web
+    // Response stream drain on Node. Non-enumerable + Symbol.for keeps this invisible to Web runtimes and
+    // cross-package without adding a runtime dependency from @nifrajs/node to @nifrajs/web.
+    Object.defineProperty(response, NODE_RESPONSE_BODY, { value: body });
+    return response;
+}
+/**
+ * Assemble the document stream: `shell` → the app `stream` (forwarded chunk-by-chunk, so a streaming
+ * renderer's progressive flushing is preserved) → `closeRoot` → one `__nifraResolve`/`__nifraReject`
+ * script per deferred value (emitted once its promise settles — by now the app stream has awaited
+ * the same Suspense boundaries — and placed OUTSIDE `#root`) → `tail`. A mid-stream app error errors
+ * the result (the body breaks) rather than silently truncating a 200.
+ */
+function streamDocument(shell, stream, closeRoot, deferred, tail, enc) {
+    return new ReadableStream({
+        async start(controller) {
+            const reader = stream.getReader();
+            try {
+                controller.enqueue(shell);
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    controller.enqueue(value);
+                }
+                controller.enqueue(closeRoot);
+                // Stream each resolution as ITS OWN promise settles — NOT in array order. A slow
+                // defer() must not block a faster one; each script self-addresses by id, so order is irrelevant.
+                await Promise.all(deferred.map(async (d) => {
+                    try {
+                        const value = serializeData(await d.promise);
+                        controller.enqueue(enc.encode(`<script>window.__nifraResolve(${d.id},${value})</script>`));
+                    }
+                    catch (err) {
+                        // A rejected deferred streams __nifraReject (the client `<Await>` surfaces it) — it must
+                        // not break the whole body. Redact: stream a stable opaque code, never the raw error
+                        // text; log the real reason server-side.
+                        console.error("[nifra/web] deferred value rejected:", err);
+                        controller.enqueue(enc.encode(`<script>window.__nifraReject(${d.id},${serializeData(DEFERRED_ERROR_CODE)})</script>`));
+                    }
+                }));
+                controller.enqueue(tail);
+                controller.close();
+            }
+            catch (err) {
+                controller.error(err);
+            }
+            finally {
+                reader.releaseLock();
+            }
+        },
+    });
+}
+/** A same-origin destination is an absolute path: one leading `/`, but NOT `//` (protocol-relative →
+ * another origin). Everything else (absolute URL with a scheme, `//host`, `javascript:`, a bare
+ * relative `foo`) is treated as off-origin and requires `external: true`. */
+function isSameOriginPath(location) {
+    return location.startsWith("/") && !location.startsWith("//");
+}
+/**
+ * Build a redirect `Response` — return it from a route `action` for the Post/Redirect/Get
+ * pattern (POST mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit).
+ * Defaults to 303 (See Other); pass `307`/`308` (or `{ status }`) to preserve the method.
+ *
+ * **Secure by default:** `location` must be a same-origin path (begins with `/`, not `//`). An
+ * off-origin/absolute destination throws unless you pass `{ external: true }` — this closes the
+ * open-redirect footgun of `return redirect(formData.get("next"))` on the no-JS (native-form) path,
+ * which returns the action's `Response` verbatim.
+ *
+ * @param statusOrOptions a status number (back-compat) or `{ status?, external? }`.
+ */
+export function redirect(location, statusOrOptions = 303) {
+    const opts = typeof statusOrOptions === "number" ? { status: statusOrOptions } : statusOrOptions;
+    if (opts.external !== true && !isSameOriginPath(location)) {
+        throw new Error(`[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//"), or redirect(location, { external: true }) for a deliberate off-origin redirect. This guards against open redirects from unvalidated input.`);
+    }
+    // Reject CR/LF in the Location explicitly — defense-in-depth (response splitting / header
+    // injection). Spec-correct runtimes' Headers setter throws on CR/LF, but `external: true` lets
+    // unvalidated input reach this sink, so we don't rely on the runtime. Same posture as
+    // serializeCookie / the SSE frame formatter, which strip CRLF at their sinks.
+    if (/[\r\n]/.test(location)) {
+        throw new Error(`[nifra/web] redirect location contains a CR/LF character — refusing to emit a header-injecting redirect.`);
+    }
+    return new Response(null, { status: opts.status ?? 303, headers: { location } });
+}
+/**
+ * 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
+ * marks those cached routes stale — refetching the active one and any mounted fetcher showing them —
+ * so a mutation can refresh views beyond the one that was submitted. `data` is still surfaced to the
+ * component as `actionData` (the wrapper is transparent to `ActionData<typeof action>`).
+ */
+export function revalidate(paths, data) {
+    return { __nifraRevalidate: paths, data };
+}
+/**
+ * Serialize loader data for embedding inside an inline `<script>`. `JSON.stringify` alone
+ * is NOT safe there: a string containing `</script>` or `<!--` would break out of the
+ * script element (an XSS vector). Escape `<`/`>` to `\uXXXX`, plus the U+2028/U+2029
+ * separators.
+ */
+export function serializeData(data) {
+    return JSON.stringify(data ?? null).replace(SCRIPT_ESCAPE, (ch) => SCRIPT_ESCAPE_MAP[ch] ?? ch);
+}
+function escapeHtml(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function escapeAttr(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+const SAFE_ATTR_NAME = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+/** Serialize a meta/link tag's attributes: validate the name (dev-authored) + escape the value
+ * (may carry loader data → XSS). Invalid attribute names are dropped. */
+function tagAttrs(attrs) {
+    return Object.entries(attrs)
+        .filter(([name]) => SAFE_ATTR_NAME.test(name))
+        .map(([name, value]) => `${name}="${escapeAttr(value)}"`)
+        .join(" ");
+}
+// Memoize the serialized head-tag string by the resolved `Meta` object's identity. A STATIC route
+// `meta` is returned by-reference from resolveMeta, so the same object recurs every request → cache
+// hit, and the invariant string is serialized once per route, not per request. A FUNCTION `meta`
+// builds a fresh object each request (new identity) → miss → recompute, exactly as needed (its
+// content can vary). WeakMap so a route module that's GC'd takes its entry with it.
+const headTagsCache = new WeakMap();
+/** Render a route's `meta`/`link` as managed (`data-nifra`) head tags. Title is set separately.
+ * String concatenation (no intermediate `.map()` arrays + spread) — parity with the already
+ * concat-based preloadLinks/styleLinks/islandPreloads loops; byte-identical output.
+ * Result is memoized per resolved-`Meta` identity (static meta → serialized once per route). */
+function headTags(head) {
+    if (head === undefined)
+        return "";
+    const cached = headTagsCache.get(head);
+    if (cached !== undefined)
+        return cached;
+    let out = "";
+    if (head.meta !== undefined)
+        for (const m of head.meta)
+            out += `<meta ${tagAttrs(m)} data-nifra>`;
+    if (head.link !== undefined)
+        for (const l of head.link)
+            out += `<link ${tagAttrs(l)} data-nifra>`;
+    headTagsCache.set(head, out);
+    return out;
+}
+/** Resolve a route's `meta` (static or a function of the loader data + params) to a {@link Meta}. */
+export function resolveMeta(meta, args) {
+    if (meta === undefined)
+        return {};
+    return typeof meta === "function" ? meta(args) : meta;
+}
+/**
+ * Build a nifra app from a route manifest: every route SSRs its layout chain via `renderPage`,
+ * and a wildcard catch-all renders `_404` (or a plain 404). Reuses @nifrajs/core's router +
+ * lifecycle, so matching, params, and precedence are battle-tested. fs-free — feed it a
+ * manifest from `discoverRoutes` (`@nifrajs/web/fs`) at startup, so the served app stays portable.
+ */
+export function createWebApp(options) {
+    const { adapter, manifest, clientEntry, title, api } = options;
+    const titleOption = title === undefined ? {} : { title };
+    // Draft/preview: when a `draftSecret` is configured, each request's signed `__nifra_draft` cookie is
+    // verified once and surfaced to loaders/actions as `ctx.draft`. No secret ⇒ always `false` (sync, free).
+    const draftFlag = (req) => options.draftSecret === undefined
+        ? Promise.resolve(false)
+        : isDraftEnabled(req, options.draftSecret);
+    // Per-route preload chunks (spread into renderPage; omitted when unmapped, for exactOptionalPropertyTypes).
+    const preloadOf = (id) => {
+        const chunks = options.routePreload?.[id];
+        return chunks ? { preload: chunks } : {};
+    };
+    // The matched route's stylesheet links (spread into renderPage). Per-route when the build mapped it
+    // (`routeStyles[id]` — only the chain's CSS; an empty array ⇒ no `<link>`), else the aggregate
+    // `styles`. Omitted entirely when CSS-free (for exactOptionalPropertyTypes).
+    const stylesOf = (id) => {
+        const perRoute = options.routeStyles?.[id];
+        if (perRoute !== undefined)
+            return { styles: perRoute };
+        return options.styles && options.styles.length > 0 ? { styles: options.styles } : {};
+    };
+    const app = server();
+    // SSG `fallback: "404"`: the set of concrete paths that actually exist for those routes. An unlisted
+    // 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 ?? []);
+    // Resolve a route's layout chain (outermost layout → page). Loaded lazily — the data-only and
+    // 405 branches return before any layout is needed.
+    const loadLayouts = (route) => Promise.all(
+    // layoutIds only reference layouts present in the manifest (buildManifest invariant).
+    route.layoutIds.map((id) => manifest.layouts[id].load().then((m) => m.default)));
+    // 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);
+    /**
+     * Render the **nearest `_error` boundary** when a route's loader throws (the agnostic, server-side
+     * half of error UI — works on every adapter, no client takeover). The boundary renders in place of
+     * the page, wrapped by the layouts **at or above** its segment (deeper layouts are dropped). It's
+     * served **non-hydrated** at status 500: a terminal page, and rendering a boundary (not the page the
+     * client maps this route to) would otherwise hydrate-mismatch. The component receives `{ name,
+     * message }` — never the stack (no internals leak into HTML).
+     */
+    const renderError = async (route, errorId, err) => {
+        const errDir = dirOfId(errorId, "_error");
+        const keptLayoutIds = route.layoutIds.filter((id) => {
+            const ld = dirOfId(id, "_layout");
+            return ld === "" || ld === errDir || errDir.startsWith(`${ld}/`);
+        });
+        const layouts = await Promise.all(keptLayoutIds.map((id) => manifest.layouts[id].load().then((m) => m.default)));
+        const { default: errComp } = await (manifest.errors?.[errorId]).load();
+        const e = err instanceof Error ? err : new Error(String(err));
+        return renderPageResult({
+            adapter,
+            chain: [...layouts, errComp],
+            data: { name: e.name, message: e.message },
+            clientEntry,
+            routeId: errorId,
+            status: 500,
+            hydrate: false,
+            ...titleOption,
+        });
+    };
+    // 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 () => {
+        if (manifest.notFound === undefined) {
+            return new Response("Not Found", {
+                status: 404,
+                headers: { "content-type": "text/plain; charset=utf-8" },
+            });
+        }
+        const { default: notFound } = await manifest.notFound.load();
+        return renderPageResult({
+            adapter,
+            chain: [notFound],
+            data: null,
+            clientEntry,
+            routeId: "_404",
+            status: 404,
+            ...preloadOf("_404"),
+            ...stylesOf("_404"),
+            prerenderedPaths: options.prerenderedPaths ?? [],
+            ...titleOption,
+        });
+    };
+    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).
+        const is404Fallback = options.staticFallbacks?.[route.pattern] === "404";
+        app.register("GET", route.pattern, undefined, async (c) => {
+            // Enforce `fallback: "404"` before any work: an unlisted path under this route doesn't exist.
+            // Covers hard navigation directly; a client soft-nav's data fetch gets the 404, throws, and the
+            // history layer falls back to a full-page navigation (which lands here again, as a document).
+            if (is404Fallback && !prerenderedSet.has(new URL(c.req.url).pathname)) {
+                return renderNotFound();
+            }
+            const mod = await route.load();
+            const draft = await draftFlag(c.req);
+            let data;
+            try {
+                data = mod.loader
+                    ? await mod.loader({ params: c.params, request: c.req, api, env: c.env, draft })
+                    : null;
+            }
+            catch (err) {
+                // A thrown `Response` is a control-flow signal (a guard's `redirect(...)`, an explicit error
+                // response) — let it propagate to core, which returns it as-is. Real errors render the nearest
+                // `_error` boundary, if any; with none, rethrow (unchanged 500 behavior).
+                if (err instanceof Response)
+                    throw err;
+                // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
+                if (options.onLoaderError !== undefined) {
+                    try {
+                        options.onLoaderError(err, { request: c.req, params: c.params, route: route.pattern });
+                    }
+                    catch {
+                        // A faulty reporter must never break error rendering.
+                    }
+                }
+                const errorId = route.errorIds?.at(-1);
+                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.
+                if (c.req.headers.get(DATA_HEADER) !== null) {
+                    return new Response("Internal Server Error", {
+                        status: 500,
+                        headers: { "content-type": "text/plain; charset=utf-8" },
+                    });
+                }
+                return renderError(route, errorId, 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), {
+                    headers: { "content-type": "application/x-ndjson; charset=utf-8" },
+                });
+            }
+            const chain = [...(await loadLayouts(route)), mod.default];
+            const head = resolveMeta(mod.meta, { data, params: c.params });
+            const hydrateRoute = mod.hydrate !== false;
+            try {
+                // `await` so a shell-render throw (renderToStream rejects before any byte) is caught here and
+                // can render the `_error` page — not just a loader throw. Mid-stream (post-shell) throws can't
+                // be recovered to a full page; the per-adapter client boundary catches client render errors.
+                return await renderPageResult({
+                    adapter,
+                    chain,
+                    data,
+                    head,
+                    clientEntry,
+                    routeId: route.id,
+                    hydrate: hydrateRoute,
+                    ...preloadOf(route.id),
+                    ...stylesOf(route.id),
+                    prerenderedPaths: options.prerenderedPaths ?? [],
+                    ...(mod.revalidate !== undefined ? { revalidate: mod.revalidate } : {}),
+                    ...(mod.islandScripts !== undefined ? { islandScripts: mod.islandScripts } : {}),
+                    ...titleOption,
+                });
+            }
+            catch (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) {
+                    try {
+                        options.onLoaderError(err, { request: c.req, params: c.params, route: route.pattern });
+                    }
+                    catch {
+                        // A faulty reporter must never break error rendering.
+                    }
+                }
+                const errorId = route.errorIds?.at(-1);
+                if (errorId === undefined)
+                    throw err;
+                return renderError(route, errorId, err);
+            }
+        });
+        // POST runs the route's `action` (mutation). A `Response` return (e.g. a `redirect(...)`)
+        // passes straight through; a data return re-renders the page (the loader re-runs for fresh
+        // data) with `actionData`. Routes without an action reject POST with 405 — not a stray 404.
+        app.register("POST", route.pattern, undefined, async (c) => {
+            const mod = await route.load();
+            const draft = await draftFlag(c.req);
+            if (mod.action === undefined) {
+                return new Response("Method Not Allowed", {
+                    status: 405,
+                    headers: { allow: "GET", "content-type": "text/plain; charset=utf-8" },
+                });
+            }
+            const result = await mod.action({ params: c.params, request: c.req, api, env: c.env, draft });
+            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
+            // responses (the client acts on them — a full-page POST re-runs loaders inline, so no header).
+            const isRevalidate = result !== null && typeof result === "object" && "__nifraRevalidate" in result;
+            const actionResult = isRevalidate ? result.data : result;
+            const revalidateHeader = isRevalidate
+                ? { [REVALIDATE_HEADER]: result.__nifraRevalidate.join(",") }
+                : {};
+            if (actionResult instanceof Response) {
+                // Client submit can't read a 3xx Location (fetch follows it to HTML), so convey the
+                // redirect via a header on a 204 and let the client navigate. Native forms get the 3xx.
+                if (isDataRequest && actionResult.status >= 300 && actionResult.status < 400) {
+                    const location = actionResult.headers.get("location") ?? "/";
+                    return new Response(null, { status: 204, headers: { [REDIRECT_HEADER]: location } });
+                }
+                return actionResult;
+            }
+            // Client submit wants just the action's data (it revalidates the loader itself); a native
+            // form POST re-renders the full page (loader re-runs) with the action data.
+            if (isDataRequest) {
+                // An action may `defer()` slow parts of its result — stream them (critical data first, then
+                // each deferred as it settles) exactly like a loader; a non-deferred action returns one JSON.
+                const { forClient, deferred } = prepareDeferred(actionResult);
+                if (deferred.length === 0)
+                    return Response.json(actionResult ?? null, { headers: revalidateHeader });
+                return new Response(ndjsonStream(forClient, deferred), {
+                    headers: { "content-type": "application/x-ndjson; charset=utf-8", ...revalidateHeader },
+                });
+            }
+            const data = mod.loader
+                ? await mod.loader({ params: c.params, request: c.req, api, env: c.env, draft })
+                : null;
+            const chain = [...(await loadLayouts(route)), mod.default];
+            const head = resolveMeta(mod.meta, { data, params: c.params });
+            const hydrateRoute = mod.hydrate !== false;
+            // A full-page POST streams the action's `defer()`'d parts mid-document behind `<Await>` too —
+            // `renderPage` splits `actionData` like loader data (works with JS off; hydrates after).
+            return renderPageResult({
+                adapter,
+                chain,
+                data,
+                actionData: actionResult,
+                head,
+                clientEntry,
+                routeId: route.id,
+                hydrate: hydrateRoute,
+                ...preloadOf(route.id),
+                ...stylesOf(route.id),
+                prerenderedPaths: options.prerenderedPaths ?? [],
+                ...titleOption,
+            });
+        });
+    }
+    // Wildcard catch-all: unmatched paths render `_404` (404), or a plain text 404 if absent.
+    app.register("GET", "/*", undefined, () => renderNotFound());
+    return app;
+}
+/**
+ * Codegen: emit a client-entry module (as source) that lazily imports each route's layout chain
+ * (so `Bun.build` with `splitting` code-splits one chunk per route), builds a `patterns` list,
+ * then creates the agnostic router store (with a `loadModule` hook), installs history + form
+ * interception, loads the initial route's chunk, and hydrates the adapter's stateful Router. The
+ * initial route is derived from the URL (falling back to the server-injected route id, e.g.
+ * `_404`), so after hydration the Router owns navigation and swaps routes without full reloads.
+ * Bun has no `import.meta.glob`, so file-based routing needs this. Write the result to a file and
+ * bundle it with `buildClient` / `Bun.build` (+ the adapter's transform).
+ */
+export function generateClientEntry(manifest, options) {
+    const { clientModule, resolve } = options;
+    const loaderRows = [];
+    const patternRows = [];
+    // 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 = [];
+    // Lazy loader returns the raw modules (for both the component chain + the page's `meta` export).
+    const lazyLoader = (files) => {
+        const imports = files.map((f) => `import(${JSON.stringify(resolve(f))})`).join(", ");
+        return `() => Promise.all([${imports}])`;
+    };
+    for (const route of manifest.routes) {
+        // layoutIds only reference layouts present in the manifest (buildManifest invariant).
+        const files = [
+            ...route.layoutIds.map((id) => manifest.layouts[id].file),
+            route.file,
+        ];
+        // Append the nearest `_error` file LAST, so loadModule can pull it off the tail and wrap the page.
+        const nearestErrorId = route.errorIds?.at(-1);
+        const errorFile = nearestErrorId === undefined ? undefined : manifest.errors?.[nearestErrorId]?.file;
+        if (errorFile !== undefined) {
+            files.push(errorFile);
+            errorRouteIds.push(route.id);
+        }
+        loaderRows.push(`  ${JSON.stringify(route.id)}: ${lazyLoader(files)},`);
+        patternRows.push(`  { routeId: ${JSON.stringify(route.id)}, pattern: ${JSON.stringify(route.pattern)} },`);
+    }
+    if (manifest.notFound !== undefined) {
+        loaderRows.push(`  "_404": ${lazyLoader([manifest.notFound.file])},`);
+    }
+    return `${[
+        'import { createClientRouter, createMatcher, resolveMeta } from "@nifrajs/web"',
+        'import { applyHead, installForms, installHistory } from "@nifrajs/web/client"',
+        // Namespace import: `errorBoundary` is optional (an adapter may not export it). A namespace member
+        // 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",
+        "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
+        // route, shared layouts/deps deduped into shared chunks, so a route's code loads only when
+        // visited. loadModule caches the [layouts…, page] component chain + the page's meta per id.
+        "const loaders = {",
+        ...loaderRows,
+        "}",
+        "const chains = {}",
+        "const metas = {}",
+        "const loadModule = async (id) => {",
+        "  if (chains[id]) return",
+        "  const mods = await loaders[id]()",
+        // For an error route the `_error` module is appended LAST: wrap the page (now second-to-last) in
+        // the adapter's boundary so a client render error renders the `_error` UI. DOM-transparent, so the
+        // hydrated tree matches the SSR markup (which has no boundary). Falls back to the plain chain when
+        // the adapter has no `errorBoundary`.
+        "  if (errorBoundary && errorRouteIds.has(id)) {",
+        "    const fallback = mods[mods.length - 1].default",
+        "    const page = mods[mods.length - 2].default",
+        "    const layouts = mods.slice(0, mods.length - 2).map((m) => m.default)",
+        "    chains[id] = [...layouts, errorBoundary(fallback), page]",
+        "    metas[id] = mods[mods.length - 2].meta",
+        "  } else {",
+        "    chains[id] = mods.map((m) => m.default)",
+        "    metas[id] = mods[mods.length - 1].meta",
+        "  }",
+        "}",
+        "const patterns = [",
+        ...patternRows,
+        "]",
+        // Derive the initial route from the URL (correct on refresh/deep-link); fall back to the
+        // server-injected route id for non-pattern routes (e.g. _404, which matches nothing).
+        "const matched = createMatcher(patterns)(location.pathname)",
+        // Map any `{__nifra_deferred: id}` placeholder in the SSR data to the registry's promise, so the
+        // component receives real promises to `<Await>` (a no-op when a page has no deferred data).
+        MAP_DEFERRED_SOURCE,
+        "const initial = {",
+        `  routeId: matched ? matched.routeId : (window.${ROUTE_GLOBAL} ?? ""),`,
+        "  params: matched ? matched.params : {},",
+        "  path: location.pathname,",
+        `  data: mapDeferred(window.${DATA_GLOBAL}),`,
+        // actionData (only set after a form POST) is in the initial state so the binding hydrates
+        // consistently with the server-rendered markup; mapped through `mapDeferred` too so a deferred
+        // action's placeholders become registry markers (a no-op when the action didn't defer).
+        `  actionData: mapDeferred(window.${ACTION_GLOBAL}),`,
+        "  pending: false,",
+        "}",
+        "const router = createClientRouter({ patterns, initial, loadModule })",
+        "installHistory(router)",
+        "installForms(router)",
+        'const root = document.getElementById("root")',
+        // Load the initial route's chunk, then hydrate the Router (chain is cached). The initial head
+        // is server-rendered; subsequent navigations update it from the matched route's meta + data.
+        "if (root) loadModule(initial.routeId).then(() => {",
+        "  mountRouter({ router, routes: chains, container: root })",
+        "  router.subscribe(() => {",
+        "    const s = router.snapshot()",
+        "    if (!s.pending) applyHead(resolveMeta(metas[s.routeId], { data: s.data, params: s.params }))",
+        "  })",
+        "})",
+    ].join("\n")}\n`;
+}
+/**
+ * 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
+ * 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
+ * `createWebApp`, unchanged) + `clientEntry` (baked). Write it to a file and bundle it into the worker
+ * entry (see `buildServer` in `@nifrajs/web/build`).
+ */
+export function generateServerManifest(manifest, options) {
+    const { resolve, clientEntry, lazy = false } = options;
+    // Every unique source file in the manifest (routes + layouts + `_error` + `_404`), 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] : []),
+        ]),
+    ].sort();
+    const header = [
+        "// GENERATED by @nifrajs/web generateServerManifest — route manifest for the disk-less edge",
+        "// (no filesystem; route imports are static specifiers the bundler resolves). buildManifest is",
+        "// the same pure logic discoverRoutes feeds, so patterns + layout chains match exactly.",
+        'import { buildManifest } from "@nifrajs/web"',
+    ];
+    const clientEntryLine = `export const clientEntry = ${JSON.stringify(clientEntry)}`;
+    if (lazy) {
+        // Lazy: `() => import("./routes/x")` per route (static specifier → one chunk per route under a
+        // code-splitting bundler, loaded on first request). The map keys are the route-relative paths
+        // `buildManifest` expects; the importer it builds calls the per-file loader.
+        const loaders = files.map((file) => `  ${JSON.stringify(file)}: () => import(${JSON.stringify(resolve(file))}),`);
+        return `${[
+            ...header,
+            "const loaders = {",
+            ...loaders,
+            "}",
+            clientEntryLine,
+            "export const manifest = buildManifest(Object.keys(loaders), (file) => () => loaders[file]())",
+        ].join("\n")}\n`;
+    }
+    // Eager: `import * as` per route (all bundled into the entry, parsed at boot). Index-based
+    // identifiers are collision-proof regardless of filename.
+    const imports = files.map((file, i) => `import * as m${i} from ${JSON.stringify(resolve(file))}`);
+    const entries = files.map((file, i) => `  ${JSON.stringify(file)}: m${i},`);
+    return `${[
+        ...header,
+        ...imports,
+        "const modules = {",
+        ...entries,
+        "}",
+        clientEntryLine,
+        "export const manifest = buildManifest(Object.keys(modules), (file) => () => Promise.resolve(modules[file]))",
+    ].join("\n")}\n`;
+}
+//# sourceMappingURL=index.js.map