npm - @nifrajs/web - Versions diffs - 3.1.0 → 3.2.0 - Mend

@nifrajs/web 3.1.0 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (114) hide show

package/dist/build-plan.d.ts +228 -0
package/dist/build-plan.d.ts.map +1 -0
package/dist/build-plan.js +514 -0
package/dist/build-plan.js.map +1 -0
package/dist/build-vite.d.ts +2 -1
package/dist/build-vite.d.ts.map +1 -1
package/dist/build-vite.js.map +1 -1
package/dist/build.d.ts +2 -197
package/dist/build.d.ts.map +1 -1
package/dist/build.js +61 -502
package/dist/build.js.map +1 -1
package/dist/chunk-names.d.ts.map +1 -1
package/dist/chunk-names.js +3 -2
package/dist/chunk-names.js.map +1 -1
package/dist/dev-ssr-graph.d.ts.map +1 -1
package/dist/dev-ssr-graph.js +63 -28
package/dist/dev-ssr-graph.js.map +1 -1
package/dist/diagnostic.d.ts.map +1 -1
package/dist/diagnostic.js +9 -2
package/dist/diagnostic.js.map +1 -1
package/dist/fonts-google.d.ts.map +1 -1
package/dist/fonts-google.js +3 -1
package/dist/fonts-google.js.map +1 -1
package/dist/fs.d.ts.map +1 -1
package/dist/fs.js +2 -1
package/dist/fs.js.map +1 -1
package/dist/index.d.ts +15 -609
package/dist/index.d.ts.map +1 -1
package/dist/index.js +22 -1935
package/dist/index.js.map +1 -1
package/dist/internal/codegen.d.ts +68 -0
package/dist/internal/codegen.d.ts.map +1 -0
package/dist/internal/codegen.js +317 -0
package/dist/internal/codegen.js.map +1 -0
package/dist/internal/head-merge.d.ts +2 -0
package/dist/internal/head-merge.d.ts.map +1 -1
package/dist/internal/head-merge.js +17 -1
package/dist/internal/head-merge.js.map +1 -1
package/dist/internal/parity.d.ts +7 -0
package/dist/internal/parity.d.ts.map +1 -1
package/dist/internal/parity.js +212 -30
package/dist/internal/parity.js.map +1 -1
package/dist/internal/render-document.d.ts +372 -0
package/dist/internal/render-document.d.ts.map +1 -0
package/dist/internal/render-document.js +744 -0
package/dist/internal/render-document.js.map +1 -0
package/dist/internal/runtime-contract.d.ts +48 -0
package/dist/internal/runtime-contract.d.ts.map +1 -0
package/dist/internal/runtime-contract.js +27 -0
package/dist/internal/runtime-contract.js.map +1 -0
package/dist/internal/web-app.d.ts +171 -0
package/dist/internal/web-app.d.ts.map +1 -0
package/dist/internal/web-app.js +844 -0
package/dist/internal/web-app.js.map +1 -0
package/dist/islands.d.ts +48 -0
package/dist/islands.d.ts.map +1 -1
package/dist/islands.js +79 -0
package/dist/islands.js.map +1 -1
package/dist/module-graph.d.ts.map +1 -1
package/dist/module-graph.js +22 -9
package/dist/module-graph.js.map +1 -1
package/dist/nano.d.ts +125 -0
package/dist/nano.d.ts.map +1 -0
package/dist/nano.js +190 -0
package/dist/nano.js.map +1 -0
package/dist/plugins/css-modules.js +2 -2
package/dist/plugins/css-modules.js.map +1 -1
package/dist/plugins/kit.d.ts +12 -0
package/dist/plugins/kit.d.ts.map +1 -1
package/dist/plugins/kit.js +62 -12
package/dist/plugins/kit.js.map +1 -1
package/dist/plugins/postcss.js +2 -2
package/dist/plugins/postcss.js.map +1 -1
package/dist/plugins/scss.js +2 -2
package/dist/plugins/scss.js.map +1 -1
package/dist/plugins/stylex.d.ts +70 -0
package/dist/plugins/stylex.d.ts.map +1 -0
package/dist/plugins/stylex.js +166 -0
package/dist/plugins/stylex.js.map +1 -0
package/dist/plugins/svg.js +2 -2
package/dist/plugins/svg.js.map +1 -1
package/dist/router.d.ts +1 -1
package/dist/router.js +23 -23
package/dist/router.js.map +1 -1
package/dist/vite.d.ts.map +1 -1
package/dist/vite.js +26 -10
package/dist/vite.js.map +1 -1
package/package.json +39 -3
package/src/build-plan.ts +741 -0
package/src/build-vite.ts +1 -4
package/src/build.ts +84 -716
package/src/chunk-names.ts +3 -2
package/src/dev-ssr-graph.ts +63 -28
package/src/diagnostic.ts +14 -2
package/src/fonts-google.ts +3 -1
package/src/fs.ts +2 -1
package/src/index.ts +73 -2705
package/src/internal/codegen.ts +400 -0
package/src/internal/head-merge.ts +19 -1
package/src/internal/parity.ts +215 -35
package/src/internal/render-document.ts +1116 -0
package/src/internal/runtime-contract.ts +54 -0
package/src/internal/web-app.ts +1114 -0
package/src/islands.ts +85 -0
package/src/module-graph.ts +23 -9
package/src/nano.ts +246 -0
package/src/plugins/css-modules.ts +2 -2
package/src/plugins/kit.ts +65 -12
package/src/plugins/postcss.ts +2 -2
package/src/plugins/scss.ts +2 -2
package/src/plugins/stylex.ts +298 -0
package/src/plugins/svg.ts +2 -2
package/src/router.ts +24 -24
package/src/vite.ts +33 -9

package/dist/internal/render-document.js ADDED Viewed

@@ -0,0 +1,744 @@
+import { isSameOriginPath, status as statusResult } from "@nifrajs/core/server";
+import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, prepareDeferred } from "../deferred.js";
+import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "../isr.js";
+import { ACTION_GLOBAL, BOUNDARY_GLOBAL, DATA_GLOBAL, LAYOUT_DATA_GLOBAL, ROOT_ATTRIBUTE, ROUTE_GLOBAL, } from "../render-seam.js";
+import { PRERENDERED_GLOBAL, REDIRECT_HEADER } from "../router.js";
+import { trustedHeadAttributes } from "./head-attributes.js";
+import { isStaticMeta, mergeHeads } from "./head-merge.js";
+import { PRE_HYDRATION_GUARD } from "./runtime-contract.js";
+import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./script-types.js";
+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");
+/**
+ * A control-flow value that renders as plain data - what `redirect()` returns, and what core's
+ * `status(...)` returns. Recognized here rather than imported: core keeps its own predicate internal,
+ * and the registry symbol is the contract between them (two copies of core must still agree).
+ */
+const isResponseResult = (value) => typeof value === "object" &&
+    value !== null &&
+    value[RESPONSE_RESULT] === true &&
+    typeof value.toResponse === "function";
+/** A returned/thrown value that ends the request as-is: either shape of control-flow signal. */
+export const isControlFlow = (value) => value instanceof Response || isResponseResult(value);
+/**
+ * Server: render a full HTML document for a page - the adapter's hydration head + the SSR
+ * markup (**streamed**) + the serialized loader data + the client module - as a `Response`.
+ * 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, revalidateTags = [], routeId, status = 200, title = "nifra", head, rootId = "root", hydrate = true, islandScripts = [], nonce, boundaries, headers: extraHeaders, } = options;
+    if (nonce !== undefined && nonce.trim() === "") {
+        throw new TypeError("[nifra/web] renderPage nonce must be non-empty when provided");
+    }
+    const nonceAttr = nonce === undefined ? "" : ` nonce="${escapeAttr(nonce)}"`;
+    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);
+    // 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 boundarySplit = boundaries === undefined
+        ? undefined
+        : prepareDeferred(boundaries, deferred.length + layoutDeferred.length + (actionSplit?.deferred.length ?? 0));
+    // On the common page-only path (no layout loader, no action) reuse `deferred` directly instead of
+    // allocating a fresh spread array every request.
+    const allDeferred = layoutDeferred.length === 0 && actionSplit === undefined && boundarySplit === undefined
+        ? deferred
+        : [
+            ...deferred,
+            ...layoutDeferred,
+            ...(actionSplit ? actionSplit.deferred : []),
+            ...(boundarySplit ? boundarySplit.deferred : []),
+        ];
+    // Omitted entirely when no layout has a loader - a page-only app emits exactly what it did before.
+    const layoutTail = options.layoutData === undefined
+        ? ""
+        : `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
+        ? ""
+        : `window.${ACTION_GLOBAL}=${serializeData(actionSplit.forClient)};`;
+    const boundaryTail = boundarySplit === undefined
+        ? ""
+        : `window.${BOUNDARY_GLOBAL}=${serializeData(boundarySplit.forClient)};`;
+    const deferredRuntime = allDeferred.length > 0 ? `<script${nonceAttr}>${DEFERRED_RUNTIME}</script>` : "";
+    // The regex only injects the CSP nonce into the (constant) hydration head; with no nonce it's a
+    // no-op that still scans the whole script every request. Skip it on the common no-nonce path.
+    // The request-invariant document pieces. With a caller-supplied per-route cache (and no per-request
+    // nonce, which would bake into them) they're built once and reused; the per-request seams - the
+    // deferred runtime in the shell, the action/layout-data globals and the serialized loader data in
+    // the tail - are always assembled fresh. Byte-identical to building the whole document inline.
+    const slot = nonce === undefined && options.assemblyCache !== undefined ? options.assemblyCache : {};
+    if (slot.shellPre === undefined) {
+        // Matched-route chunk preloads, concatenated directly. De-duped against the entry, which is
+        // preloaded separately below.
+        let preloadLinks = "";
+        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.
+        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>`, 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`.
+        let islandPreloads = "";
+        for (const src of islandScripts)
+            islandPreloads += `<link rel="modulepreload" href="${escapeAttr(src)}">`;
+        // 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${nonceAttr}>${PRE_HYDRATION_GUARD}</script>` : "";
+        // `<html>` attributes. `lang` defaults to `"en"`; `dir` is omitted entirely when unset, which IS
+        // HTML's `ltr` default. Both attribute-escaped. `client.ts`'s `applyHead` mirrors this exact
+        // defaulting on soft-nav, so a hard load and a client navigation produce the same `<html>`.
+        const htmlAttrs = ` lang="${escapeAttr(head?.lang ?? "en")}"${head?.dir === undefined ? "" : ` dir="${escapeAttr(head.dir)}"`}`;
+        // Marks the container for the client entry when the id is not the one the entry falls back to.
+        const rootMarker = rootId === "root" ? "" : ` ${ROOT_ATTRIBUTE}`;
+        // A non-hydrated page omits the adapter's hydration bootstrap entirely (Solid's `_$HY` registry
+        // script, etc.) - there is no client takeover to feed, so it's dead bytes on a static document.
+        // The nonce rewrite only runs when a nonce is set; with none it was a whole-string no-op scan.
+        const rawHydrationHead = hydrate ? adapter.hydrationHead(nonce) : "";
+        const hydrationHead = nonce === undefined
+            ? rawHydrationHead
+            : rawHydrationHead.replace(/<script(?![^>]*\bnonce=)(?=[\s>])/g, `<script${nonceAttr}`);
+        // Shell up to the deferred-runtime seam: on a hydrating page that seam sits after the entry +
+        // route-chunk preloads; a non-hydrating page has no runtime insertion at all.
+        const entryPreloads = hydrate
+            ? `<link rel="modulepreload" href="${escapeAttr(clientEntry ?? "")}">${preloadLinks}`
+            : "";
+        slot.shellPre = `<!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}${entryPreloads}`;
+        slot.shellPost = `${islandPreloads}${hydrationHead}</head><body><div id="${escapeAttr(rootId)}"${rootMarker}>`;
+        // 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)}"${nonceAttr}></script>`;
+        if (hydrate) {
+            slot.tailPre = `<script${nonceAttr}>${route}`;
+            slot.tailMid = prerendered;
+            slot.tailData = `window.${DATA_GLOBAL}=`;
+            slot.tailPost = `</script><script type="module" src="${escapeAttr(clientEntry ?? "")}"${nonceAttr}></script>${islandTags}</body></html>`;
+        }
+        else {
+            slot.tailPre = "";
+            slot.tailMid = "";
+            slot.tailData = "";
+            slot.tailPost = `${islandTags}</body></html>`;
+        }
+    }
+    // The deferred runtime rides only on a hydrating page (a static page has no client takeover), and
+    // only when something actually deferred - matching the pre-cache emission exactly.
+    const runtimeSeam = hydrate && allDeferred.length > 0 ? deferredRuntime : "";
+    const shellHtml = `${slot.shellPre}${runtimeSeam}${slot.shellPost}`;
+    // 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.
+    const tailHtml = hydrate
+        ? `${slot.tailPre}${action}${slot.tailMid}${layoutTail}${boundaryTail}${slot.tailData}${serializeData(forClient)}${slot.tailPost}`
+        : slot.tailPost;
+    const headers = { "content-type": "text/html; charset=utf-8" };
+    // Caller-supplied headers (a terminal status page's `cache-control`, say). Applied before the
+    // 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.
+    if (revalidate !== undefined)
+        headers[ISR_REVALIDATE_HEADER] = String(revalidate);
+    const serializedTags = serializeISRTags(revalidateTags);
+    if (serializedTags !== undefined)
+        headers[ISR_REVALIDATE_TAGS_HEADER] = serializedTags;
+    const renderProps = {
+        data: forComponent,
+        actionData: actionSplit?.forComponent,
+        // `params`/`path` thread the matched route + URL to the adapter's `useParams`/`useLocation` so they
+        // render SSR-correct. Spread only when supplied (exactOptionalPropertyTypes) - an adapter with no
+        // router bindings simply never reads them.
+        ...(options.params !== undefined ? { params: options.params } : {}),
+        ...(options.path !== undefined ? { path: options.path } : {}),
+        // Same rule for `search`: the validated query the adapter's `useSearch` reads, spread only when the
+        // caller supplied it (a non-router render never has it).
+        ...(options.search !== undefined ? { search: options.search } : {}),
+        // 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) }
+            : {}),
+        ...(boundarySplit !== undefined
+            ? { boundaries: boundarySplit.forComponent }
+            : {}),
+    };
+    // Fast path: nothing `defer()`s and the adapter can render synchronously to a string → buffer the
+    // whole document in one pass. Progressive streaming only benefits pages with deferred boundaries
+    // (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, nonceAttr).then((response) => new ResponseRenderedPage(response));
+}
+async function renderStreamedPage(adapter, chain, renderProps, shellHtml, closeRootHtml, allDeferred, tailHtml, status, headers, nonceAttr) {
+    // 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, nonceAttr);
+    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, nonceAttr) {
+    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${nonceAttr}>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${nonceAttr}>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), and nothing a URL parser resolves off-origin. Everything else (absolute URL with
+ * a scheme, `//host`, `javascript:`, a bare relative `foo`) requires `external: true`. The predicate
+ * lives in the kernel - see `isSameOriginPath` - so this gate and the auth guards' `redirectTo`
+ * cannot drift apart. */
+/**
+ * Build a redirect - return it from a route `action` for the Post/Redirect/Get pattern (POST
+ * mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit). Defaults to 303
+ * (See Other); pass `{ status: 307 }` or `{ status: 308 }` to preserve the method.
+ *
+ * **Secure by default:** `location` must be a same-origin path (begins with `/`, not `//`). An
+ * off-origin/absolute destination throws unless you pass `{ external: true }` - this closes the
+ * open-redirect footgun of `return redirect(formData.get("next"))` on the no-JS (native-form) path,
+ * which serves the action's control-flow value verbatim.
+ *
+ * Returns a plain render, not a `Response`. A redirect is a status line and one header - the most
+ * body-less response there is - and building a `Response` for it costs the whole Web object plus, on
+ * Node, a stream drained back out. As data it renders on the same lane a handler's return takes.
+ * `redirect(...)` is still returned or thrown from exactly the same places; only `.status` /
+ * `.headers` are gone from the value, replaced by `options.headers` and the request's `c.set`.
+ *
+ * @param options redirect status, extra headers, and whether an off-origin destination is intentional.
+ */
+export function redirect(location, options = {}) {
+    if (options.external !== true && !isSameOriginPath(location)) {
+        throw new Error(`[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//", no backslash or control character), or redirect(location, { external: true }) for a deliberate off-origin redirect. This guards against open redirects from unvalidated input.`);
+    }
+    // Reject CR/LF in the Location explicitly - defense-in-depth (response splitting / header
+    // injection). Spec-correct runtimes' Headers setter throws on CR/LF, but `external: true` lets
+    // 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 statusResult(options.status ?? 303, undefined, {
+        headers: options.headers === undefined ? { location } : { ...options.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.
+ */
+export 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;
+}
+/**
+ * An action's control-flow value passes straight through - except a redirect on a client-submit data
+ * request: fetch would follow the 3xx into HTML the client can't use, so the redirect rides the
+ * X-Nifra-Redirect header on a 204 and the client navigates. One conversion shared by the returned-
+ * and thrown- paths, so `return redirect()` and `throw redirect()` agree.
+ *
+ * Takes either shape: `redirect()` is a plain render, while a hand-rolled `new Response(...)` from an
+ * action still arrives as a `Response`. The rewrite stays on the lane its input was on - a plain
+ * redirect converts to a plain 204, and never materializes the `Response` it is replacing.
+ */
+export function actionResponse(result, isDataRequest) {
+    if (!isDataRequest)
+        return result;
+    if (isResponseResult(result)) {
+        const plain = result.plain;
+        // No `plain` means a carrier that only knows how to build a `Response` (not one of ours) - fall
+        // back rather than guess at its status.
+        if (plain === undefined)
+            return actionResponse(result.toResponse(), isDataRequest);
+        if (plain.status < 300 || plain.status >= 400)
+            return result;
+        const location = plain.headers?.location ?? "/";
+        return statusResult(204, undefined, { headers: { [REDIRECT_HEADER]: location } });
+    }
+    if (result.status >= 300 && result.status < 400) {
+        const location = result.headers.get("location") ?? "/";
+        return statusResult(204, undefined, { headers: { [REDIRECT_HEADER]: location } });
+    }
+    return result;
+}
+/**
+ * Narrow the route's params to the ones a layout owns.
+ *
+ * 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`.
+ */
+export 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({});
+export 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");
+export 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;
+};
+export const layoutErrorId = (err) => typeof err === "object" && err !== null
+    ? err[LAYOUT_ERROR_ID]
+    : undefined;
+export 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. */
+export 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",
+};
+export 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
+ * 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) {
+    const serialized = JSON.stringify(data ?? null);
+    // Most loader payloads contain no script-sensitive characters. Guard with chained `indexOf`
+    // rather than a regex `.test`: each probe is a native memchr-style scan, measured ~7x faster than
+    // the regex scan on V8 for a multi-KB payload (and the engine rejects the two >0xFF separator
+    // probes in O(1) when the string is internally one-byte, which serialized JSON almost always is).
+    // The same four characters are probed as the SCRIPT_ESCAPE class, so any payload the regex would
+    // escape still takes the escape path - this is only a cheaper detector, never a security
+    // relaxation.
+    const needsEscape = serialized.indexOf("<") !== -1 ||
+        serialized.indexOf(">") !== -1 ||
+        serialized.indexOf(LINE_SEP) !== -1 ||
+        serialized.indexOf(PARA_SEP) !== -1;
+    return needsEscape
+        ? serialized.replace(SCRIPT_ESCAPE, (ch) => SCRIPT_ESCAPE_MAP[ch] ?? ch)
+        : serialized;
+}
+function escapeHtml(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+/**
+ * Escape a `<script>` element's text content so it cannot break out of the element. Per the HTML spec,
+ * a script's text may contain any character EXCEPT the sequences that the parser treats as element
+ * boundaries: `</` (which would begin the end tag - `</script>` is the obvious XSS vector, but ANY `</`
+ * starts script-data-end-tag parsing), and the comment/CDATA edges `<!--` / `]]>`. We escape the `<`
+ * (and the `>` of `]]>`) to its JS unicode escape: inside a JS/JSON string literal `<` is the
+ * identical character, so a JSON-LD payload is byte-equivalent after parsing - but the raw `<`/`>` the
+ * HTML tokenizer scans for is gone. This is the JSON-LD-in-HTML rule (content is JSON, never raw HTML),
+ * mirroring {@link serializeData}'s posture for the data-global script. Idempotent on already-safe text.
+ */
+function escapeScriptContent(content) {
+    // Order matters: rewrite `]]>` first (its `>` becomes `>`), then every `<` (covers `</` and
+    // `<!--` in one pass). `<` → `<`; the lone `>` of `]]>` → `>`. A bare `>` elsewhere is
+    // harmless in script data, so only the `]]>` close is targeted for `>`.
+    return content.replaceAll("]]>", "]]\\u003e").replaceAll("<", "\\u003c");
+}
+function escapeAttr(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+/** Serialize attributes that passed the shared SSR/client head trust policy. */
+function tagAttrs(tag, attrs) {
+    const trusted = trustedHeadAttributes(tag, attrs);
+    if (trusted === null)
+        return null;
+    let out = "";
+    for (const [name, value] of trusted) {
+        if (out !== "")
+            out += " ";
+        out += value === true ? name : `${name}="${escapeAttr(value)}"`;
+    }
+    return out;
+}
+// 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. Function results are
+// never cached, even when a function deliberately reuses one mutable object across requests. WeakMap
+// so a route module that's GC'd takes its entry with it.
+const headTagsCache = new WeakMap();
+function assertExecutableScriptType(type) {
+    if (!EXECUTABLE_SCRIPT_TYPES.has(type)) {
+        throw new TypeError(`[nifra/web] executable inline scripts accept ${[...EXECUTABLE_SCRIPT_TYPES].map((t) => JSON.stringify(t)).join(" or ")}; received ${JSON.stringify(type)}`);
+    }
+}
+/** Render a route's `meta`/`link`/`script` as managed (`data-nifra`) head tags. Title is set
+ * separately. XSS-safe by construction: every attribute flows through the shared tag-specific trust
+ * policy then value escaping, and each `script[].content` through `escapeScriptContent`
+ * (breakout-escaped) - so loader-derived strings (LLM-authored `og:*`, user content) can't inject markup
+ * or close the tag early. String concatenation (no intermediate `.map()` arrays + spread) - parity with
+ * the already concat-based preloadLinks/styleLinks/islandPreloads loops; byte-identical output. Result
+ * is memoized only for objects observed as static meta exports (serialized once per route). */
+function headTags(head) {
+    if (head === undefined)
+        return "";
+    const cacheable = isStaticMeta(head);
+    if (cacheable) {
+        const cached = headTagsCache.get(head);
+        if (cached !== undefined)
+            return cached;
+    }
+    let out = "";
+    if (head.meta !== undefined)
+        for (const m of head.meta) {
+            const attrs = tagAttrs("meta", m);
+            if (attrs !== null)
+                out += `<meta${attrs === "" ? "" : ` ${attrs}`} data-nifra>`;
+        }
+    if (head.link !== undefined)
+        for (const l of head.link) {
+            const attrs = tagAttrs("link", l);
+            if (attrs !== null)
+                out += `<link${attrs === "" ? "" : ` ${attrs}`} data-nifra>`;
+        }
+    // `<script>` slot - JSON-LD + other inert head scripts. `type` is attribute-escaped; `content` is
+    // breakout-escaped (`escapeScriptContent`) so a `</script>` (or `<!--`/`]]>`) payload can't close the
+    // element early. Managed (`data-nifra`) so a soft-nav's `applyHead` cleanly replaces it.
+    if (head.script !== undefined)
+        for (const s of head.script) {
+            const type = s.type ?? "application/ld+json";
+            if (!INERT_SCRIPT_TYPES.has(type)) {
+                throw new TypeError(`[nifra/web] head.script only accepts inert JSON script types; received ${JSON.stringify(type)}. Use unsafeInlineScript() with a CSP nonce for executable code.`);
+            }
+            out += `<script type="${type}" data-nifra>${escapeScriptContent(s.content)}</script>`;
+        }
+    if (head.unsafeScript !== undefined)
+        for (const s of head.unsafeScript) {
+            if (s.unsafe !== true || s.nonce.trim() === "") {
+                throw new TypeError("[nifra/web] executable inline scripts require a non-empty CSP nonce");
+            }
+            // `type` is validated, not escaped, for the same reason as the inert slot above: an unknown
+            // value here is a bug, and escaping one would emit a nonsense script type rather than say so.
+            // It was interpolated raw while the `nonce` beside it was escaped, so a descriptor built by hand
+            // - `unsafeScript` is a public field, the helper is only a convenience - could close the
+            // attribute and inject markup. Measured: `type: '"><img src=x onerror=alert(1)>'` reached the
+            // document. An injection in the slot whose whole purpose is to make script emission trustworthy.
+            assertExecutableScriptType(s.type);
+            out += `<script type="${s.type}" nonce="${escapeAttr(s.nonce)}" data-nifra>${escapeScriptContent(s.content)}</script>`;
+        }
+    if (cacheable)
+        headTagsCache.set(head, out);
+    return out;
+}
+/**
+ * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
+ * engines which URL is authoritative for a page (deduping query-string / tracking variants).
+ *
+ * ```ts
+ * export const meta = (a) => ({ link: [canonical(`https://site.com/posts/${a.params.slug}`)] })
+ * ```
+ */
+export function canonical(href) {
+    return { rel: "canonical", href };
+}
+/**
+ * Build the Open Graph `<meta property="og:*">` entries for a route's `meta.meta`. Returns only the
+ * properties you supplied (plus `og:type`, defaulting to `"website"`), so it composes with other meta.
+ *
+ * ```ts
+ * export const meta = { meta: [...openGraph({ title: "Nifra", image: "https://site.com/og.png" })] }
+ * ```
+ */
+export function openGraph(input) {
+    const tags = [];
+    const add = (property, content) => {
+        if (content !== undefined)
+            tags.push({ property, content });
+    };
+    add("og:title", input.title);
+    add("og:description", input.description);
+    add("og:image", input.image);
+    add("og:url", input.url);
+    // `og:type` always present (the spec's required property) - default "website" when unset.
+    tags.push({ property: "og:type", content: input.type ?? "website" });
+    return tags;
+}
+/**
+ * Build a JSON-LD `<script type="application/ld+json">` entry for a route's `meta.script` from a plain
+ * object. `JSON.stringify` produces the body; the head renderer breakout-escapes it (see
+ * `escapeScriptContent`), so a string field containing `</script>` is embedded safely.
+ *
+ * ```ts
+ * export const meta = {
+ *   script: [jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })],
+ * }
+ * ```
+ */
+export function jsonLd(data) {
+    return { type: "application/ld+json", content: JSON.stringify(data) };
+}
+/**
+ * Deliberately unsafe escape hatch for executable inline code. The required nonce keeps the result
+ * compatible with a strict CSP and makes the security-sensitive choice visible at the call site.
+ */
+export function unsafeInlineScript(content, options) {
+    if (options.nonce.trim() === "") {
+        throw new TypeError("[nifra/web] unsafeInlineScript requires a non-empty CSP nonce");
+    }
+    const type = options.type ?? "module";
+    // Checked here as well as at emit: the type union is compile-time only, and this helper is the one
+    // place a caller is told what it may pass. Failing at the call site names the argument; failing at
+    // render names a document.
+    assertExecutableScriptType(type);
+    return {
+        unsafe: true,
+        type,
+        nonce: options.nonce,
+        content,
+    };
+}
+//# sourceMappingURL=render-document.js.map