@voltro/web 0.7.0 → 0.8.0

package/dist/ssr.d.ts

@@ -2,11 +2,92 @@ import { ComponentType } from 'react';
 import { PipeableStream } from 'react-dom/server';
 import { ReactNode } from 'react';
 
+/**
+ * Throw unless this page can actually stream. Verified against React 19.2.7
+ * rather than assumed — each rejected combination FAILS SILENTLY otherwise,
+ * which is worse than not shipping the feature:
+ *
+ *  - `renderMode: 'static'` — the prerender uses `renderToString`, which does
+ *    not support Suspense: it emits an ERRORED boundary (`<!--$!-->`) plus a
+ *    `<template data-msg="Switched to client rendering...">` and no warning.
+ *    The artefact would ship a permanent client-rendered fallback.
+ *  - `renderMode: 'isr'` — ISR caches a completed HTML STRING. Awaiting the
+ *    deferred values to fill that string would make `defer()` a silent no-op
+ *    that still reads like it streams; caching a stream is different
+ *    machinery entirely.
+ *  - `interactive: 'none'` — revealing a boundary needs React's inline
+ *    `$RC`/`$RV` scripts, and this mode ships zero JS. The fallback would be
+ *    permanent.
+ *  - `interactive: 'islands'` — `mount()` returns after `hydrateIslandsOnPage()`
+ *    and never hydrates the root, so nothing ever consumes the registry
+ *    promises. Islands take their props from their own serialised payload, not
+ *    from loader data, so there is no value in wiring them in.
+ */
+export declare const assertDeferralSupported: (target: DeferralTarget) => void;
+
+/** Render modes / interactive modes a page may combine with `defer()`. */
+export declare interface DeferralTarget {
+    /** Route pattern or source file — named in the error so it is actionable. */
+    readonly page: string;
+    readonly renderMode: string;
+    readonly interactive: string;
+}
+
+/** Brand key on the object `defer()` returns. A single explicit container
+ *  check — NOT a scan of arbitrary loader results for markers by shape. */
+declare const DEFERRED_RESULT_TAG: "__voltroDeferredLoaderResult";
+
+/** What a loader returns when it defers part of its data. Opaque to user
+ *  code: build it with {@link defer}, read it with `useLoaderData()`. */
+declare interface DeferredLoaderResult<TEager extends object = object, TDeferred extends Record<string, Promise<unknown>> = Record<string, Promise<unknown>>> {
+    readonly [DEFERRED_RESULT_TAG]: true;
+    /** Awaited before the shell renders — present in the SSR markup AND in the
+     *  inlined `__voltro_state__` payload. */
+    readonly eager: TEager;
+    /** Streamed after the shell — each key becomes a promise on
+     *  `useLoaderData()`, to be rendered through `<Await>`. */
+    readonly deferred: TDeferred;
+}
+
+/** Build the wire payload from what the server render was given. */
+export declare const encodeRouterState: (input: RouterStateInput) => InlinedRouterState;
+
 declare interface ErrorBoundaryProps {
     readonly error: unknown;
     readonly reset: () => void;
 }
 
+/**
+ * The wire shape. JSON cannot express `undefined`, which is why `ran` exists
+ * as a separate presence record: a loader that returned `undefined` is
+ * otherwise indistinguishable from one that never ran, and the client would
+ * re-run it on hydration (the flash this whole payload exists to remove).
+ */
+export declare interface InlinedRouterState {
+    /** The page (leaf) loader's result — exactly the value the server render
+     *  provided to the page's `LoaderDataContext`. */
+    readonly page?: unknown;
+    /** Per-layout loader results keyed by CHAIN INDEX (as a JSON string key).
+     *  The index is the same one `descriptor.chain[i]` uses on both sides —
+     *  see `wrapInChain` in ssr.tsx and in router.tsx. */
+    readonly segments?: Readonly<Record<string, unknown>>;
+    /** Which loaders actually RAN server-side. Drives cache seeding (i.e.
+     *  "don't re-run this on hydration"); the values above drive the render. */
+    readonly ran?: {
+        readonly page?: boolean;
+        readonly segments?: ReadonlyArray<number>;
+    };
+    /** Deferred (streamed) loader fields: field name -> client-registry id, for
+     *  the page loader and per chain index. The VALUES are not here — they
+     *  arrive later, published by the settle `<script>` each `<Await>` boundary
+     *  emits as its promise resolves. Absent entirely when nothing deferred, so
+     *  a non-deferring page's payload is byte-identical to what it always was. */
+    readonly deferred?: {
+        readonly page?: Readonly<Record<string, string>>;
+        readonly segments?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    };
+}
+
 /**
  * How the client-side JS hydrates a server-rendered page.
  *
@@ -25,6 +106,9 @@ declare interface ErrorBoundaryProps {
  */
 declare type InteractiveMode = 'full' | 'islands' | 'none';
 
+/** True for exactly the object {@link defer} returns. */
+export declare const isDeferredLoaderResult: (value: unknown) => value is DeferredLoaderResult;
+
 declare interface LoaderContext {
     readonly params: Readonly<Record<string, string>>;
     readonly pathname: string;
@@ -139,6 +223,33 @@ declare interface PageMeta {
 
 export declare const parseCookieHeader: (raw: string | undefined) => Record<string, string>;
 
+/**
+ * Split one loader result for a streaming render. `scope` is `'page'` for the
+ * page loader or the layout's chain index, and only feeds the registry id.
+ */
+export declare const prepareDeferredLoaderData: (result: unknown, scope: "page" | number) => PreparedLoaderData;
+
+/** One loader's result, prepared for a streaming SSR render. */
+export declare interface PreparedLoaderData {
+    /** What the RENDERER gets: eager fields plus one tagged promise per
+     *  deferred field. Identical to the plain result when nothing deferred. */
+    readonly renderData: unknown;
+    /** What the `__voltro_state__` payload gets: eager fields only. A promise
+     *  serialises to `{}`, so the deferred half must never reach it. */
+    readonly stateData: unknown;
+    /** Deferred field name -> registry id, for the state payload. `undefined`
+     *  when the loader did not defer — the wire shape is then byte-identical
+     *  to what a non-deferring page has always emitted. */
+    readonly deferredIds: Readonly<Record<string, string>> | undefined;
+}
+
+/**
+ * The `<script>` every streaming SSR emitter puts in `<head>`, before the
+ * shell. Must precede any settle script — which is automatic, since settle
+ * scripts ride in the body.
+ */
+export declare const renderDeferredRegistryScript: () => string;
+
 /**
  * Helper for the build pipeline: stringify the resolved meta into a
  * `<head>`-ready HTML fragment. Returns an empty string when no meta
@@ -249,26 +360,69 @@ export declare interface RenderPageStreamResult {
 /**
  * Render a page to an HTML string using its layout chain + loader data. The
  * returned `html` is the body fragment — the caller composes the surrounding
- * document. Renders synchronously via `renderToString`; for the streaming
- * path (flush the shell before the whole tree is ready) use
+ * document. Renders synchronously via `renderToString`.
+ *
+ * This is the ARTEFACT renderer: static prerender and ISR, both of which need
+ * the whole document. See the doctrine note above before switching a caller to
  * {@link renderPageToStream}.
  */
 export declare const renderPageToHtml: (options: RenderPageOptions) => RenderPageResult;
 
 /**
- * Streaming SSR — the richer path alongside {@link renderPageToHtml}. Renders
- * the page via React's `renderToPipeableStream` so the server can flush the
- * shell (and each Suspense boundary as it resolves) instead of buffering the
- * whole document into one string. Same tree, same providers, same meta as the
- * sync path; the difference is time-to-first-byte and native Suspense
- * streaming.
+ * Streaming SSR — the RESPONSE renderer, for `renderMode: 'ssr'`. Renders via
+ * React's `renderToPipeableStream` so the server can flush the shell (and each
+ * Suspense boundary as it resolves) instead of buffering the whole document
+ * into one string. Same tree, same providers, same meta as the sync path.
  *
  * The caller drives the response: write the doctype + `<head>` (using the
  * synchronously-returned `meta`) + opening `<body><div id="root">` in
- * `onShellReady`, `stream.pipe(res)`, then close the document in `onAllReady`.
+ * `onShellReady`, pipe the stream, then close the document once it ends.
+ * Both boot paths do that through ONE shared helper —
+ * `streamSsrResponse` in `@voltro/cli`'s `ssrShell.ts` — rather than
+ * hand-mirroring the sequence, which is the drift class that previously cost
+ * this pipeline its layout-loader data in dev.
+ *
+ * Two details the caller MUST get right, both learned the hard way:
+ *
+ *  - **Pass `bootstrapModules`, don't leave the entry `<script type="module">`
+ *    in the shell.** A plain module script is deferred until the document is
+ *    fully parsed — on a streamed response that is AFTER the last deferred
+ *    boundary, which deletes the entire benefit. React emits `bootstrapModules`
+ *    as `async` at the end of the shell instead.
+ *  - **Pipe through a `PassThrough`.** React's `pipe()` calls `end()` on the
+ *    destination itself, so writing the closing `</div>` + shell tail straight
+ *    to the response would land after it was already closed.
  */
 export declare const renderPageToStream: (options: RenderPageStreamOptions) => RenderPageStreamResult;
 
+/**
+ * The full `<script>` tag every SSR emitter injects into `<head>`. Emitters
+ * call THIS, never the pieces — that is what keeps the dev / serve / prerender
+ * paths on one payload shape.
+ */
+export declare const renderRouterStateScript: (input: RouterStateInput) => string;
+
+/** id of the `<script type="application/json">` tag carrying the payload. */
+export declare const ROUTER_STATE_SCRIPT_ID = "__voltro_state__";
+
+export declare interface RouterStateInput {
+    /** Page loader result passed to `renderPageToHtml` / `renderPageToStream`. */
+    readonly loaderData: unknown;
+    /** Layout loader results, keyed by chain index — the same object passed to
+     *  the renderer, so the inlined payload cannot disagree with the markup. */
+    readonly segmentLoaderData?: Readonly<Record<number, unknown>> | undefined;
+    /** Whether the page module actually exported a `loader`. Not derivable from
+     *  `loaderData` (a loader may legitimately resolve to `undefined`/`null`,
+     *  and the SSR paths default the field to `null` when there is no loader). */
+    readonly pageLoaderRan: boolean;
+    /** Page-loader deferred fields: name -> registry id. Produced by
+     *  `prepareDeferredLoaderData` in the SSR pipeline; omit when nothing
+     *  deferred (which is every non-streaming emitter). */
+    readonly deferredPageIds?: Readonly<Record<string, string>> | undefined;
+    /** Layout-loader deferred fields, keyed by chain index. */
+    readonly deferredSegmentIds?: Readonly<Record<number, Readonly<Record<string, string>>>> | undefined;
+}
+
 /**
  * One layer in a page's nesting chain. Each represents a directory level
  * in the file-convention layout (or a route group).
@@ -301,11 +455,11 @@ declare interface RouteSegment {
 }
 
 /**
- * Serialise loader data into a `<script>` payload safe to embed in
- * HTML. The result is wrapped in `<script type="application/json"
- * id="__voltro_state__">` by the caller; here we just produce the
- * JSON body with `</` sequences escaped (the well-known SSR XSS
- * vector).
+ * Serialise arbitrary data for inlining into an HTML `<script>` body.
+ *
+ * Escaping `<` is the well-known SSR XSS fix: it makes a `</script>` inside a
+ * string value un-parseable as a closing tag while staying valid JSON (`\u003c`
+ * decodes back to `<`), so no consumer has to un-escape anything.
  */
 export declare const serialiseStateForInlining: (state: unknown) => string;
 

package/dist/ssr.js

@@ -1,47 +1,48 @@
-import { c as e, d as t, r as n, t as r, x as i } from "./serverContext-DSValgbm.js";
-import { createElement as a } from "react";
-import { renderToPipeableStream as o, renderToString as s } from "react-dom/server";
+import { _ as e, a as t, g as n, m as r, n as i, p as a, s as o, t as s } from "./routerState-ga64vk2B.js";
+import { c, d as l, r as u, t as d, x as f } from "./serverContext-BW0GF8fv.js";
+import { createElement as p } from "react";
+import { renderToPipeableStream as m, renderToString as h } from "react-dom/server";
 //#region src/ssr.tsx
-var c = (t, n, r, i) => {
-	let o = a(e.Provider, { value: r }, a(t));
-	if (!n) return o;
-	for (let t = n.length - 1; t >= 0; t--) {
-		let r = n[t];
-		if (r.Layout) {
-			let n = r.Layout;
-			o = a(e.Provider, { value: i(t) }, a(n, { children: o }));
+var g = (e, t, n, r) => {
+	let i = p(c.Provider, { value: n }, p(e));
+	if (!t) return i;
+	for (let e = t.length - 1; e >= 0; e--) {
+		let n = t[e];
+		if (n.Layout) {
+			let t = n.Layout;
+			i = p(c.Provider, { value: r(e) }, p(t, { children: i }));
 		}
 	}
-	return o;
-}, l = (e) => {
-	let { descriptor: n, params: o, pathname: s, loaderData: l, segmentLoaderData: u, requestContext: d, outerWrap: f, locale: p } = e, m = i(n.meta, o, l, p), h = {
-		pathname: s,
+	return i;
+}, _ = (e) => {
+	let { descriptor: t, params: n, pathname: r, loaderData: i, segmentLoaderData: a, requestContext: o, outerWrap: s, locale: c } = e, u = f(t.meta, n, i, c), m = {
+		pathname: r,
 		search: "",
-		params: o,
-		loaderData: l,
+		params: n,
+		loaderData: i,
 		navigate: () => {
 			throw Error("navigate() is not supported during server-side rendering. Trigger navigations on the client only.");
 		},
 		prefetch: () => {},
 		registerBlocker: () => () => {},
 		blocked: null
-	}, g = n.Component;
-	if (!g) throw Error(`SSR received a descriptor with no Component for "${s}". Lazy page routes are a client-only optimization and must not be used on the server.`);
-	let _ = a(t.Provider, { value: h }, c(g, n.chain, l, (e) => u?.[e]));
-	return d && (_ = a(r.Provider, { value: d }, _)), f && (_ = f(_)), {
+	}, h = t.Component;
+	if (!h) throw Error(`SSR received a descriptor with no Component for "${r}". Lazy page routes are a client-only optimization and must not be used on the server.`);
+	let _ = p(l.Provider, { value: m }, g(h, t.chain, i, (e) => a?.[e]));
+	return o && (_ = p(d.Provider, { value: o }, _)), s && (_ = s(_)), {
 		tree: _,
-		meta: m
+		meta: u
 	};
-}, u = (e) => {
-	let { tree: t, meta: n } = l(e);
+}, v = (e) => {
+	let { tree: t, meta: n } = _(e);
 	return {
-		html: s(t),
+		html: h(t),
 		meta: n
 	};
-}, d = (e) => {
-	let { tree: t, meta: n } = l(e);
+}, y = (e) => {
+	let { tree: t, meta: n } = _(e);
 	return {
-		stream: o(t, {
+		stream: m(t, {
 			...e.bootstrapModules ? { bootstrapModules: [...e.bootstrapModules] } : {},
 			...e.onShellReady ? { onShellReady: e.onShellReady } : {},
 			...e.onShellError ? { onShellError: e.onShellError } : {},
@@ -49,20 +50,20 @@ var c = (t, n, r, i) => {
 		}),
 		meta: n
 	};
-}, f = (e) => {
+}, b = (e) => {
 	if (!e) return "";
 	let t = [];
-	if (typeof e.title == "string" && t.push(`<title>${m(e.title)}</title>`), e.description && t.push(`<meta name="description" content="${h(e.description)}" />`), e.canonical && t.push(`<link rel="canonical" href="${h(e.canonical)}" />`), e.tags) for (let n of e.tags) {
-		let e = n.name ? `name="${h(n.name)}"` : n.property ? `property="${h(n.property)}"` : "";
-		e && t.push(`<meta ${e} content="${h(n.content)}" />`);
+	if (typeof e.title == "string" && t.push(`<title>${x(e.title)}</title>`), e.description && t.push(`<meta name="description" content="${S(e.description)}" />`), e.canonical && t.push(`<link rel="canonical" href="${S(e.canonical)}" />`), e.tags) for (let n of e.tags) {
+		let e = n.name ? `name="${S(n.name)}"` : n.property ? `property="${S(n.property)}"` : "";
+		e && t.push(`<meta ${e} content="${S(n.content)}" />`);
 	}
 	if (e.links) for (let n of e.links) {
 		let e = [
-			`rel="${h(n.rel)}"`,
-			`href="${h(n.href)}"`,
-			n.hreflang ? `hreflang="${h(n.hreflang)}"` : "",
-			n.type ? `type="${h(n.type)}"` : "",
-			n.title ? `title="${h(n.title)}"` : ""
+			`rel="${S(n.rel)}"`,
+			`href="${S(n.href)}"`,
+			n.hreflang ? `hreflang="${S(n.hreflang)}"` : "",
+			n.type ? `type="${S(n.type)}"` : "",
+			n.title ? `title="${S(n.title)}"` : ""
 		].filter(Boolean).join(" ");
 		t.push(`<link ${e} />`);
 	}
@@ -71,6 +72,6 @@ var c = (t, n, r, i) => {
 		t.push(`<script type="application/ld+json" data-voltro-page-jsonld>${e}<\/script>`);
 	}
 	return t.join("\n    ");
-}, p = (e) => JSON.stringify(e ?? null).replace(/</g, "\\u003c"), m = (e) => e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"), h = (e) => e.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}, x = (e) => e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"), S = (e) => e.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 //#endregion
-export { n as parseCookieHeader, f as renderMetaToHtml, u as renderPageToHtml, d as renderPageToStream, p as serialiseStateForInlining };
+export { s as ROUTER_STATE_SCRIPT_ID, o as assertDeferralSupported, i as encodeRouterState, a as isDeferredLoaderResult, u as parseCookieHeader, r as prepareDeferredLoaderData, n as renderDeferredRegistryScript, b as renderMetaToHtml, v as renderPageToHtml, y as renderPageToStream, t as renderRouterStateScript, e as serialiseStateForInlining };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/web",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The Voltro web framework — file-based routing, render modes (SSR / SSG / islands), the page-export contract, data hooks, and the browser mount.",
   "keywords": [
     "voltro",
@@ -52,8 +52,8 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.7.0",
-    "@voltro/ui": "0.7.0"
+    "@voltro/client": "0.8.0",
+    "@voltro/ui": "0.8.0"
   },
   "peerDependencies": {
     "@effect/platform": "^0.96.2",

package/dist/mount-DhGdfjSE.js

@@ -1,74 +0,0 @@
-import { t as e } from "./frameworkBoot-C_d7E8Fj.js";
-import { StrictMode as t, createElement as n } from "react";
-import { createRoot as r, hydrateRoot as i } from "react-dom/client";
-import { jsx as a } from "react/jsx-runtime";
-//#region src/islands.tsx
-var o = /* @__PURE__ */ new Map(), s = (e, t) => {
-	o.set(t.name, e);
-	let r = t.hydrate ?? "visible", i = (i) => n("div", {
-		"data-voltro-island": "",
-		"data-island-name": t.name,
-		"data-island-hydrate": r,
-		"data-island-props": l(i)
-	}, n(e, i));
-	return i.displayName = `Island(${t.name})`, i;
-}, c = (e) => o.get(e), l = (e) => JSON.stringify(e ?? {}).replace(/</g, "\\u003c"), u = (e) => {
-	if (!e) return {};
-	try {
-		return JSON.parse(e);
-	} catch {
-		return {};
-	}
-}, d = () => {
-	let e = document.querySelectorAll("[data-voltro-island]:not([data-voltro-hydrated])");
-	for (let t of e) {
-		let e = t.dataset.islandName ?? "", r = o.get(e);
-		if (!r) {
-			console.warn(`[voltro] island "${e}" referenced in DOM but not registered. Did the island file get imported in this bundle?`);
-			continue;
-		}
-		let a = u(t.dataset.islandProps ?? null), s = t.dataset.islandHydrate ?? "visible";
-		t.setAttribute("data-voltro-hydrated", "pending");
-		let c = () => {
-			t.getAttribute("data-voltro-hydrated") !== "done" && (t.setAttribute("data-voltro-hydrated", "done"), i(t, n(r, a)));
-		};
-		if (s === "load") c();
-		else if (s === "idle") {
-			let e = globalThis.requestIdleCallback;
-			e ? e(c) : setTimeout(c, 0);
-		} else if (s === "visible") {
-			let e = new IntersectionObserver((t) => {
-				t.some((e) => e.isIntersecting) && (e.disconnect(), c());
-			}, { rootMargin: "64px" });
-			e.observe(t);
-		} else if (s === "interaction") {
-			let e = () => {
-				t.removeEventListener("pointerdown", e), t.removeEventListener("keydown", e), c();
-			};
-			t.addEventListener("pointerdown", e, { passive: !0 }), t.addEventListener("keydown", e);
-		}
-	}
-}, f = (e) => `${window.location.protocol === "https:" ? "wss:" : "ws:"}//${window.location.host}/ws/${e}`, p = (n, o) => {
-	let s = document.getElementById(o.rootId ?? "root");
-	if (!s) throw Error(`@voltro/web: no #${o.rootId ?? "root"} element in the document`);
-	let c = Object.entries(o.apis).map(([e, t]) => ({
-		name: e,
-		group: t.group,
-		descriptors: t.descriptors ?? {},
-		wsUrl: t.wsUrl ?? f(e),
-		headers: t.headers
-	})), l = document.getElementById("__voltro_state__") !== null && s.children.length > 0, u = document.querySelector("meta[name=\"voltro-interactive\"]")?.getAttribute("content") ?? "full";
-	if (u === "none") return;
-	if (u === "islands") {
-		d();
-		return;
-	}
-	let p = /* @__PURE__ */ a(t, { children: /* @__PURE__ */ a(e, {
-		App: n,
-		apis: c,
-		...o.Devtools ? { Devtools: o.Devtools } : {}
-	}) });
-	l ? i(s, p) : r(s).render(p);
-};
-//#endregion
-export { s as i, c as n, d as r, p as t };