@voltro/web 0.37.0 → 0.39.0

package/dist/index.d.ts

@@ -503,9 +503,47 @@ export declare class LoaderCache {
 
 export declare const loaderCacheKey: (pattern: string, params: Readonly<Record<string, string>>) => string;
 
+/**
+ * What a `loader` receives.
+ *
+ * **It runs on the server AND again in the browser.** A loader is not a
+ * server-only hook: it runs during SSR for the first paint, and then runs
+ * AGAIN, in the browser, on every in-app navigation to the route. Same
+ * function, different environment.
+ *
+ * That precondition was never written down, and a consumer read "runs once per
+ * request" into the gap — which is the reading the wording invites. It cost
+ * them two days, and the reason it survived that long is the nastiest part: a
+ * client-only failure is invisible to every probe that does not NAVIGATE. A
+ * fresh page load, a `curl`, any SSR check goes through the server path and
+ * passes. Only clicking a link inside the running app reaches the other one.
+ *
+ * So anything server-only in a loader must be guarded by {@link isServer}.
+ */
 export declare interface LoaderContext<Procedures = unknown> {
     readonly params: Readonly<Record<string, string>>;
     readonly pathname: string;
+    /**
+     * `true` when this invocation is the SERVER one (SSR under `voltro dev` or
+     * `voltro start`), `false` in the browser.
+     *
+     * Exists because the alternatives are traps. `query` is absent in the browser
+     * and so reads as a discriminator, but branching on the ABSENCE OF A FUNCTION
+     * says nothing about why it is absent and breaks the moment anything else
+     * becomes conditional. `headers` is worse: it is `{}` in the browser, not
+     * `undefined`, so `ctx.headers ? …` is TRUE on both paths — a consumer
+     * checked exactly that and it silently did nothing.
+     *
+     *     export const loader = async (ctx: LoaderContext) => {
+     *       if (ctx.isServer) seedStore(prefs, await ctx.query!('prefs.get'))
+     *       return null
+     *     }
+     *
+     * REQUIRED, not optional: an optional boolean is omissible, and a server path
+     * that forgot it would read as `undefined` — falsy — and claim to be the
+     * browser. Required means the compiler names every construction site.
+     */
+    readonly isServer: boolean;
     /**
      * The raw query string, INCLUDING the leading `?`, or `''` when there is
      * none. Filled on every path — client navigation, `voltro dev` SSR and

package/dist/index.js

@@ -1,10 +1,10 @@
 import { t as e } from "./globalContext-d4A-ugDg.js";
 import { AppClientsContext as t, useAppClient as n } from "./hooks.js";
-import { a as r, c as i, i as a, l as o, o as s, r as c, s as l, u } from "./frameworkBoot--fOA34nd.js";
+import { a as r, c as i, i as a, l as o, o as s, r as c, s as l, u } from "./frameworkBoot-Tso-IjA7.js";
 import { a as d, c as f, i as p, l as m, o as h, u as g } from "./defaultFallbacks-B4Ak-R6R.js";
-import { a as _, i as ee, n as te, r as ne, t as re } from "./mount-BKP99m_W.js";
+import { a as _, i as ee, n as te, r as ne, t as re } from "./mount-BTAQ-8Vl.js";
 import { c as ie, d as ae, h as oe, l as se, p as ce, u as le } from "./routerState-DAT472IC.js";
-import { A as ue, B as de, C as fe, D as pe, E as me, F as he, G as ge, H as _e, I as v, K as y, L as b, M as x, N as S, O as C, P as w, R as T, S as E, T as D, U as O, V as k, W as A, _ as j, a as M, b as N, c as P, d as F, f as I, g as ve, h as ye, i as be, j as xe, k as Se, l as Ce, m as we, n as Te, o as Ee, p as De, q as Oe, r as ke, s as Ae, t as je, u as Me, v as Ne, w as Pe, x as Fe, y as Ie, z as Le } from "./serverContext-7toyzR70.js";
+import { A as ue, B as de, C as fe, D as pe, E as me, F as he, G as ge, H as _e, I as v, K as y, L as b, M as x, N as S, O as C, P as w, R as T, S as E, T as D, U as O, V as k, W as A, _ as j, a as M, b as N, c as P, d as F, f as I, g as ve, h as ye, i as be, j as xe, k as Se, l as Ce, m as we, n as Te, o as Ee, p as De, q as Oe, r as ke, s as Ae, t as je, u as Me, v as Ne, w as Pe, x as Fe, y as Ie, z as Le } from "./serverContext-38JTbYPa.js";
 import { Component as Re, Suspense as ze, createElement as L, use as Be, useCallback as Ve, useContext as He, useSyncExternalStore as Ue } from "react";
 import { Fragment as R, jsx as z, jsxs as B } from "react/jsx-runtime";
 export * from "@voltro/client";
@@ -147,11 +147,10 @@ var We = ({ value: e, fallback: t, children: n, errorFallback: r }) => /* @__PUR
 			"aria-current": n ? "page" : void 0
 		}, e.label);
 		return n ? [r] : [r, L("span", { key: `s${t}` }, "/")];
-	})) : null;
-	return L("div", { className: "voltro-blog-layout" }, u, L("main", {
+	})) : null, f = L("main", {
 		className: "voltro-blog-main",
 		style: Qe
-	}, d, r), a ? L("footer", {
+	}, d, r), p = a ? L("footer", {
 		className: "voltro-blog-footer",
 		style: {
 			maxWidth: "48rem",
@@ -159,7 +158,8 @@ var We = ({ value: e, fallback: t, children: n, errorFallback: r }) => /* @__PUR
 			padding: "2rem 1.5rem",
 			borderTop: "1px solid var(--voltro-blog-border, rgba(127,127,127,0.2))"
 		}
-	}, a) : null);
+	}, a) : null;
+	return L("div", { className: "voltro-blog-layout" }, u, f, p);
 }, G = (e) => {
 	if (e === "" || e === "/") return "/";
 	let t = e.startsWith("/") ? e : `/${e}`;

package/dist/{mount-BKP99m_W.js → mount-BTAQ-8Vl.js}

@@ -1,4 +1,4 @@
-import { t as e } from "./frameworkBoot--fOA34nd.js";
+import { t as e } from "./frameworkBoot-Tso-IjA7.js";
 import { o as t, r as n, t as r } from "./routerState-DAT472IC.js";
 import { StrictMode as i, createElement as a } from "react";
 import { createRoot as o, hydrateRoot as s } from "react-dom/client";
@@ -63,19 +63,19 @@ var d = /* @__PURE__ */ new Map(), f = (e, t) => {
 		descriptors: t.descriptors ?? {},
 		wsUrl: t.wsUrl ?? b(e),
 		headers: t.headers
-	})), m = n(document.getElementById(r)?.textContent, window.location.pathname), h = m !== null && f.children.length > 0, v = document.querySelector("meta[name=\"voltro-interactive\"]")?.getAttribute("content") ?? "full";
-	if (v === "none") return;
-	if (v === "islands") {
+	})), m = document.getElementById(r), h = n(m?.textContent, window.location.pathname), v = h !== null && f.children.length > 0, x = document.querySelector("meta[name=\"voltro-interactive\"]")?.getAttribute("content") ?? "full";
+	if (x === "none") return;
+	if (x === "islands") {
 		y(_()), g();
 		return;
 	}
-	h && t(m), l(m?.storeSeeds), c(m?.preloadSeeds);
-	let x = /* @__PURE__ */ u(i, { children: /* @__PURE__ */ u(e, {
+	v && t(h), l(h?.storeSeeds), c(h?.preloadSeeds);
+	let S = /* @__PURE__ */ u(i, { children: /* @__PURE__ */ u(e, {
 		App: a,
 		apis: p,
 		...d.Devtools ? { Devtools: d.Devtools } : {}
 	}) });
-	h ? s(f, x) : o(f).render(x);
+	v ? s(f, S) : o(f).render(S);
 };
 //#endregion
 export { f as a, g as i, y as n, p as r, x as t };

package/dist/mount.js

@@ -1,2 +1,2 @@
-import { n as e, t } from "./mount-BKP99m_W.js";
+import { n as e, t } from "./mount-BTAQ-8Vl.js";
 export { t as mount, e as noticeIslandsShipTheFullBundle };

package/dist/{serverContext-7toyzR70.js → serverContext-38JTbYPa.js}

@@ -291,7 +291,7 @@ var h = {
 		}
 		return this.props.children;
 	}
-}, R = "data-voltro-page-slot", Se = () => /* @__PURE__ */ p("div", { [R]: "" }), Ce = ({ routes: e, notFounds: i = [], notFound: o = n, errorFallback: c = r }) => {
+}, Se = "data-voltro-page-slot", Ce = () => /* @__PURE__ */ p("div", { [Se]: "" }), R = ({ routes: e, notFounds: i = [], notFound: o = n, errorFallback: c = r }) => {
 	let [m, h] = f(() => window.location.pathname), [g, _] = f(() => window.location.pathname), [v, y] = f(() => window.location.search + window.location.hash), b = v.split("#")[0] ?? "", x = d(new de()), S = d(/* @__PURE__ */ new Map()), [ne, w] = f(null), re = s((e, t) => (S.current.set(e, t), () => {
 		S.current.delete(e);
 	}), []), T = d(/* @__PURE__ */ new Map()), E = d(null), D = u(() => ae(e.map(ie)), [e]);
@@ -330,7 +330,7 @@ var h = {
 		n?.replace ? window.history.replaceState(r, "", e) : window.history.pushState(r, "", e), h(t.pathname), y(t.search + t.hash), n?.scroll !== !1 && me(t);
 	}, []), M = s((e, t) => {
 		let n = new URL(window.location.href), r = new URL(e, n);
-		if (!(r.pathname === n.pathname && r.search === n.search && r.hash === n.hash)) {
+		if (r.pathname !== n.pathname || r.search !== n.search || r.hash !== n.hash) {
 			for (let n of S.current.values()) if (n({
 				to: e,
 				...t ? { opts: t } : {}
@@ -356,7 +356,7 @@ var h = {
 		};
 		return document.addEventListener("click", e), () => document.removeEventListener("click", e);
 	}, [M]);
-	let N = u(() => O(D, m), [D, m]), P = d(/* @__PURE__ */ new Map()), [F, be] = f(0);
+	let N = u(() => O(D, m), [D, m]), P = d(/* @__PURE__ */ new Map()), [F, be] = f(0), Se = N?.route.load ? N.route.pattern : null;
 	l(() => {
 		let e = N?.route;
 		if (!e?.load || P.current.has(e.pattern)) return;
@@ -366,8 +366,8 @@ var h = {
 		}).catch(() => {}), () => {
 			t = !0;
 		};
-	}, [N?.route.load ? N.route.pattern : null]);
-	let R = d(/* @__PURE__ */ new Set()), Ce = s((e) => {
+	}, [Se]);
+	let R = d(/* @__PURE__ */ new Set()), Te = s((e) => {
 		let t = e.load;
 		t && (P.current.has(e.pattern) || R.current.has(e.pattern) || (R.current.add(e.pattern), t().then((t) => {
 			P.current.set(e.pattern, t);
@@ -381,7 +381,7 @@ var h = {
 		let t = P.current.get(e.pattern);
 		return t ? {
 			...e,
-			...Ne(t),
+			...Pe(t),
 			load: void 0
 		} : null;
 	}, [N, F]), B = u(() => O(D, g), [D, g]), V = u(() => {
@@ -391,10 +391,10 @@ var h = {
 		let t = P.current.get(e.pattern);
 		return t ? {
 			...e,
-			...Ne(t),
+			...Pe(t),
 			load: void 0
 		} : null;
-	}, [B, F]), H = s((e) => {
+	}, [B, F]), Oe = s((e) => {
 		let t = new URL(e, window.location.origin), n = O(D, t.pathname);
 		if (!n) return;
 		let r = (e, r) => {
@@ -402,37 +402,38 @@ var h = {
 				params: n.params,
 				pathname: t.pathname,
 				search: t.search,
-				signal: e
+				signal: e,
+				isServer: !1
 			}));
 		};
-		Ce(n.route), n.route.loader && r(k(n.route.pattern, n.params), n.route.loader), n.route.chain?.forEach((e, t) => {
+		Te(n.route), n.route.loader && r(k(n.route.pattern, n.params), n.route.loader), n.route.chain?.forEach((e, t) => {
 			e.loader && r(oe(n.route.pattern, t, n.params), e.loader);
 		});
-	}, [D, Ce]), [U, W] = f({ status: "idle" }), G = d(void 0);
-	G.current === void 0 && (G.current = a());
-	let K = d(!1), [De, Oe] = f(() => G.current?.pageClientOnly === !0 && G.current.pathname === m);
+	}, [D, Te]), [H, U] = f({ status: "idle" }), W = d(void 0);
+	W.current === void 0 && (W.current = a());
+	let ke = d(!1), [Ae, je] = f(() => W.current?.pageClientOnly === !0 && W.current.pathname === m);
 	l(() => {
-		Oe(!1);
+		je(!1);
 	}, []);
-	let [q, ke] = f(() => ({
+	let [G, Me] = f(() => ({
 		pathname: m,
-		data: ge(G.current ?? null, m),
+		data: ge(W.current ?? null, m),
 		chain: N?.route.chain
 	}));
 	l(() => {
 		let e = (e) => {
-			_(m), ke((t) => t.pathname === m && _e(t.data, e) ? t : {
+			_(m), Me((t) => t.pathname === m && _e(t.data, e) ? t : {
 				pathname: m,
 				data: e,
 				chain: N?.route.chain
 			});
 		};
 		if (!N) {
-			W({ status: "idle" }), e(void 0);
+			U({ status: "idle" }), e(void 0);
 			return;
 		}
 		if (!z) {
-			W({
+			U({
 				status: "pending",
 				key: k(N.route.pattern, N.params)
 			});
@@ -448,7 +449,8 @@ var h = {
 					params: n,
 					pathname: m,
 					search: b,
-					signal: t
+					signal: t,
+					isServer: !1
 				})
 			});
 		}
@@ -462,17 +464,18 @@ var h = {
 						params: n,
 						pathname: m,
 						search: b,
-						signal: e
+						signal: e,
+						isServer: !1
 					})
 				});
 			}
 		}), a.length === 0) {
-			W({ status: "idle" }), e(void 0);
+			U({ status: "idle" }), e(void 0);
 			return;
 		}
-		let o = k(t.pattern, n), s = G.current;
-		if (s && !K.current && m === s.pathname) {
-			K.current = !0;
+		let o = k(t.pattern, n), s = W.current;
+		if (s && !ke.current && m === s.pathname) {
+			ke.current = !0;
 			for (let e of a) e.target === "page" ? s.pageRan && x.current.seed(e.cacheKey, s.page) : s.segments.has(e.target) && x.current.seed(e.cacheKey, s.segments.get(e.target));
 		}
 		let c = a.map((e) => ({
@@ -498,18 +501,18 @@ var h = {
 			};
 		}, u = l();
 		if (u) {
-			u.ok ? (W({
+			u.ok ? (U({
 				status: "success",
 				key: o,
 				data: u.data
-			}), e(u.data)) : (W({
+			}), e(u.data)) : (U({
 				status: "error",
 				key: o,
 				error: u.error
 			}), C(u.error) || e(void 0));
 			return;
 		}
-		W({
+		U({
 			status: "pending",
 			key: o
 		}), i && _(m);
@@ -517,11 +520,11 @@ var h = {
 		return Promise.all(f).then(() => {
 			if (d) return;
 			let t = l();
-			t && (t.ok ? (W({
+			t && (t.ok ? (U({
 				status: "success",
 				key: o,
 				data: t.data
-			}), e(t.data)) : (W({
+			}), e(t.data)) : (U({
 				status: "error",
 				key: o,
 				error: t.error
@@ -534,36 +537,36 @@ var h = {
 		z,
 		m
 	]);
-	let J = q.data?.page, Y = g === m, Ae = q.pathname === g, je = Ae ? q.data?.page : void 0, Me = V?.loader === void 0 ? I : je, Pe = ve(), X = u(() => {
+	let K = G.data?.page, q = g === m, J = G.pathname === g, Ne = J ? G.data?.page : void 0, Fe = V?.loader === void 0 ? I : Ne, Ie = ve(), Y = u(() => {
 		if (!B) return null;
-		let e = B.params.locale ?? Pe;
-		return ce(V?.meta, B.params, J, e);
+		let e = B.params.locale ?? Ie;
+		return ce(V?.meta, B.params, K, e);
 	}, [
 		B,
 		V,
-		J,
-		Pe
+		K,
+		Ie
 	]);
-	l(() => ye(X), [X]);
-	let [Fe, Z] = f(""), Q = d(!1), [Ie, Le] = f(!1);
+	l(() => ye(Y), [Y]);
+	let [X, Z] = f(""), Q = d(!1), [Le, Re] = f(!1);
 	l(() => {
 		if (!Q.current) {
-			Q.current = !0, Le(!0);
+			Q.current = !0, Re(!0);
 			return;
 		}
-		let e = X?.title ?? (typeof document < "u" ? document.title : "");
+		let e = Y?.title ?? (typeof document < "u" ? document.title : "");
 		Z(e && e.length > 0 ? e : g);
-	}, [g, X]), l(() => {
+	}, [g, Y]), l(() => {
 		let e = E.current;
 		e && (E.current = null, pe(() => window.scrollTo(e.x, e.y)));
 	}, [g]);
-	let Re = u(() => ({
+	let ze = u(() => ({
 		pathname: g,
 		search: v,
 		navigate: M,
 		params: B?.params ?? {},
-		prefetch: H,
-		loaderData: J,
+		prefetch: Oe,
+		loaderData: K,
 		registerBlocker: re,
 		blocked: ne
 	}), [
@@ -571,8 +574,8 @@ var h = {
 		v,
 		M,
 		B,
-		H,
-		J,
+		Oe,
+		K,
 		re,
 		ne
 	]);
@@ -591,47 +594,47 @@ var h = {
 		ee({
 			pathname: g,
 			params: B?.params ?? {},
-			loaderData: J
+			loaderData: K
 		});
 	}, [
 		g,
 		B,
-		J
+		K
 	]), l(() => {
-		if (U.status === "pending") return t({
+		if (H.status === "pending") return t({
 			id: "voltro:router:loader",
 			kind: "loading",
 			label: "Loading…"
 		});
-	}, [U.status]), l(() => {
-		if (U.status === "error") return t({
+	}, [H.status]), l(() => {
+		if (H.status === "error") return t({
 			id: "voltro:router:loader-error",
 			kind: "error",
 			label: "Loader failed"
 		});
-	}, [U.status]), l(() => {
-		U.status === "error" && C(U.error) && M(U.error.location, { replace: !0 });
-	}, [U, M]);
-	let ze = () => {
+	}, [H.status]), l(() => {
+		H.status === "error" && C(H.error) && M(H.error.location, { replace: !0 });
+	}, [H, M]);
+	let Be = () => {
 		let e = le(i, g);
 		if (e) {
 			let { Component: t, chain: n } = e;
-			return Ee(n, /* @__PURE__ */ p(t, {}), g, c);
+			return De(n, /* @__PURE__ */ p(t, {}), g, c);
 		}
 		return /* @__PURE__ */ p(o, {});
-	}, Be = Y && B && U.status === "error" ? U.error : void 0, $;
-	if (!B) $ = ze();
-	else if (te(Be)) $ = ze();
+	}, Ve = q && B && H.status === "error" ? H.error : void 0, $;
+	if (!B) $ = Be();
+	else if (te(Ve)) $ = Be();
 	else {
 		let e = B.route.chain, t = e ? e.length - 1 : -1, n = V?.ErrorBoundary ?? ue(e, "Error", t) ?? c, r;
-		if (De) r = /* @__PURE__ */ p(Se, {});
-		else if (Y && U.status === "error" && !C(U.error)) r = /* @__PURE__ */ p(n, {
-			error: U.error,
+		if (Ae) r = /* @__PURE__ */ p(Ce, {});
+		else if (q && H.status === "error" && !C(H.error)) r = /* @__PURE__ */ p(n, {
+			error: H.error,
 			reset: () => {
-				x.current.invalidate(B.route.pattern), h((e) => e), W({ status: "idle" });
+				x.current.invalidate(B.route.pattern), h((e) => e), U({ status: "idle" });
 			}
 		});
-		else if (Y && U.status === "pending") {
+		else if (q && H.status === "pending") {
 			let i = V?.Pending ?? ue(e, "Pending", t);
 			if (i) r = /* @__PURE__ */ p(i, {});
 			else if (V?.Component) {
@@ -640,7 +643,7 @@ var h = {
 					resetKey: g,
 					Fallback: n,
 					children: /* @__PURE__ */ p(L.Provider, {
-						value: Me,
+						value: Fe,
 						children: /* @__PURE__ */ p(e, {})
 					})
 				});
@@ -651,30 +654,30 @@ var h = {
 				resetKey: g,
 				Fallback: n,
 				children: /* @__PURE__ */ p(L.Provider, {
-					value: Me,
+					value: Fe,
 					children: /* @__PURE__ */ p(e, {})
 				})
 			}) : null;
 		}
-		$ = Ee(e, r, g, c, (t) => {
-			if (Ae) return q.data?.segments[t];
+		$ = De(e, r, g, c, (t) => {
+			if (J) return G.data?.segments[t];
 			let n = e?.[t]?.Layout;
-			return n !== void 0 && n === q.chain?.[t]?.Layout ? q.data?.segments[t] : void 0;
+			return n !== void 0 && n === G.chain?.[t]?.Layout ? G.data?.segments[t] : void 0;
 		});
 	}
 	return /* @__PURE__ */ p(we, {
-		value: Re,
-		announcer: Ie ? /* @__PURE__ */ p(Te, { message: Fe }) : null,
+		value: ze,
+		announcer: Le ? /* @__PURE__ */ p(Ee, { message: X }) : null,
 		children: $
 	});
 }, we = ({ value: e, announcer: t, children: n }) => /* @__PURE__ */ m(P.Provider, {
 	value: e,
 	children: [n, t]
-}), z = (e, t) => /* @__PURE__ */ p(we, {
+}), Te = (e, t) => /* @__PURE__ */ p(we, {
 	value: e,
 	announcer: null,
 	children: t
-}), B = {
+}), z = {
 	position: "absolute",
 	width: 1,
 	height: 1,
@@ -684,14 +687,14 @@ var h = {
 	clip: "rect(0, 0, 0, 0)",
 	whiteSpace: "nowrap",
 	border: 0
-}, Te = ({ message: e }) => /* @__PURE__ */ p("div", {
+}, Ee = ({ message: e }) => /* @__PURE__ */ p("div", {
 	"data-vweb-route-announcer": "",
 	role: "status",
 	"aria-live": "assertive",
 	"aria-atomic": "true",
-	style: B,
+	style: z,
 	children: e
-}), Ee = (e, t, n, r, i) => {
+}), De = (e, t, n, r, i) => {
 	if (!e || e.length === 0) return t;
 	let a = t;
 	for (let t = e.length - 1; t >= 0; t--) {
@@ -713,14 +716,14 @@ var h = {
 		}
 	}
 	return a;
-}, V = () => F().pathname, H = () => F().navigate, U = () => F().params, W = () => {
+}, B = () => F().pathname, V = () => F().navigate, Oe = () => F().params, H = () => {
 	let e = c(L);
 	if (e === I) throw Error("useLoaderData() was called at a level that declares no `loader`. Export `loader` from this page/layout, or — if this component is shared between routes that have one and routes that do not — read it with `useOptionalLoaderData()`, which returns `undefined` here instead of throwing. The React component stack below names the component.");
 	return e;
-}, G = () => {
+}, U = () => {
 	let e = c(L);
 	return e === I ? void 0 : e;
-}, K = () => F().prefetch, De = (e) => {
+}, W = () => F().prefetch, ke = (e) => {
 	let { registerBlocker: t, blocked: n } = F(), r = d(Symbol("voltro:blocker")), i = d(e);
 	return i.current = e, l(() => {
 		let e = r.current;
@@ -734,22 +737,22 @@ var h = {
 		retry: n.retry,
 		reset: n.reset
 	} : { blocked: !1 };
-}, Oe = (e) => e instanceof URLSearchParams ? e : new URLSearchParams(e), q = () => {
+}, Ae = (e) => e instanceof URLSearchParams ? e : new URLSearchParams(e), je = () => {
 	let { navigate: e } = F();
 	return s((t, n) => {
-		let r = new URLSearchParams(typeof window < "u" ? window.location.search : ""), i = Oe(typeof t == "function" ? t(r) : t).toString(), a = typeof window < "u" ? window.location.pathname : "/", o = i ? `${a}?${i}` : a;
+		let r = new URLSearchParams(typeof window < "u" ? window.location.search : ""), i = Ae(typeof t == "function" ? t(r) : t).toString(), a = typeof window < "u" ? window.location.pathname : "/", o = i ? `${a}?${i}` : a;
 		e(o, {
 			replace: !n?.push,
 			...n?.scroll === void 0 ? {} : { scroll: n.scroll }
 		});
 	}, [e]);
-}, ke = (e) => e, J = (e, t) => {
+}, G = (e) => e, Me = (e, t) => {
 	let n = new URLSearchParams();
 	for (let [e, r] of Object.entries(t)) r !== void 0 && n.append(e, String(r));
 	let r = n.toString();
 	return r ? `${e}?${r}` : e;
-}, Y = (e, t) => `${e}#${t.replace(/^#/, "")}`, Ae = (e) => /^([a-z][a-z0-9+.-]*:|\/\/|#)/i.test(e), je = ({ to: e, children: t, onClick: n, prefetch: r = !1, replace: i = !1, onMouseEnter: a, onFocus: o, ref: c, ...u }) => {
-	let f = H(), m = K(), h = Ae(e), g = d(null), ee = s((e) => {
+}, K = (e, t) => `${e}#${t.replace(/^#/, "")}`, q = (e) => /^([a-z][a-z0-9+.-]*:|\/\/|#)/i.test(e), J = ({ to: e, children: t, onClick: n, prefetch: r = !1, replace: i = !1, onMouseEnter: a, onFocus: o, ref: c, ...u }) => {
+	let f = V(), m = W(), h = q(e), g = d(null), ee = s((e) => {
 		g.current = e, typeof c == "function" ? c(e) : c && (c.current = e);
 	}, [c]);
 	l(() => {
@@ -782,10 +785,10 @@ var h = {
 		onFocus: y,
 		children: t
 	});
-}, Me = (e) => je({
+}, Ne = (e) => J({
 	...e,
 	to: e.to
-}), Ne = (e) => ({
+}), Pe = (e) => ({
 	Component: e.default,
 	meta: e.meta,
 	loader: e.loader,
@@ -793,27 +796,27 @@ var h = {
 	Pending: e.Pending,
 	renderMode: e.renderMode,
 	interactive: e.interactive
-}), Pe = (e, t, n = {}) => ({
+}), Fe = (e, t, n = {}) => ({
 	pattern: e,
-	...Ne(t),
+	...Pe(t),
 	chain: n.chain
-}), X = (e, t, n = {}) => ({
+}), Ie = (e, t, n = {}) => ({
 	pattern: e,
 	load: t,
 	chain: n.chain
-}), Fe = async (e, t) => {
+}), Y = async (e, t) => {
 	let n = O(e.map(ie), t)?.route.load;
 	if (n) try {
 		await n();
 	} catch {}
-}, Z = e("serverRequest", null), Q = () => c(Z), Ie = () => {
-	let e = Q();
+}, X = e("serverRequest", null), Z = () => c(X), Q = () => {
+	let e = Z();
 	if (e !== null) {
 		let t = e.url.indexOf("?");
 		return new URLSearchParams(t >= 0 ? e.url.slice(t + 1) : "");
 	}
 	return typeof window < "u" ? new URLSearchParams(window.location.search) : new URLSearchParams();
-}, Le = ({ value: e, children: t }) => /* @__PURE__ */ p(Z.Provider, {
+}, Le = ({ value: e, children: t }) => /* @__PURE__ */ p(X.Provider, {
 	value: e,
 	children: t
 }), Re = (e) => {
@@ -834,4 +837,4 @@ var h = {
 	return t;
 };
 //#endregion
-export { W as A, b as B, Fe as C, oe as D, ce as E, K as F, _ as G, C as H, q as I, ee as K, Y as L, H as M, G as N, ae as O, U as P, J as R, Pe as S, fe as T, x as U, te as V, S as W, ke as _, Q as a, k as b, L as c, Se as d, Me as f, ie as g, P as h, Ie as i, V as j, De as k, I as l, Ce as m, Le as n, je as o, ne as p, v as q, Re as r, de as s, Z as t, R as u, le as v, z as w, O as x, X as y, y as z };
+export { H as A, b as B, Y as C, oe as D, ce as E, W as F, _ as G, C as H, je as I, ee as K, K as L, V as M, U as N, ae as O, Oe as P, Me as R, Fe as S, fe as T, x as U, te as V, S as W, G as _, Z as a, k as b, L as c, Ce as d, Ne as f, ie as g, P as h, Q as i, B as j, ke as k, I as l, R as m, Le as n, J as o, ne as p, v as q, Re as r, de as s, X as t, Se as u, le as v, Te as w, O as x, Ie as y, y as z };

package/dist/ssr.d.ts

@@ -6,6 +6,7 @@ import { ProcedureOutput } from '@voltro/client';
 import { ProcedureTypeMap } from '@voltro/client';
 import { ReactNode } from 'react';
 import { seedPreloadedSubscription } from '@voltro/client';
+import { seedPreloadedSubscriptionFailure } from '@voltro/client';
 import { StoreSeed } from '@voltro/client';
 import { StoreSeedBag } from '@voltro/client';
 
@@ -210,9 +211,47 @@ declare type InteractiveMode = 'full' | 'islands' | 'none';
 /** True for exactly the object {@link defer} returns. */
 export declare const isDeferredLoaderResult: (value: unknown) => value is DeferredLoaderResult;
 
+/**
+ * What a `loader` receives.
+ *
+ * **It runs on the server AND again in the browser.** A loader is not a
+ * server-only hook: it runs during SSR for the first paint, and then runs
+ * AGAIN, in the browser, on every in-app navigation to the route. Same
+ * function, different environment.
+ *
+ * That precondition was never written down, and a consumer read "runs once per
+ * request" into the gap — which is the reading the wording invites. It cost
+ * them two days, and the reason it survived that long is the nastiest part: a
+ * client-only failure is invisible to every probe that does not NAVIGATE. A
+ * fresh page load, a `curl`, any SSR check goes through the server path and
+ * passes. Only clicking a link inside the running app reaches the other one.
+ *
+ * So anything server-only in a loader must be guarded by {@link isServer}.
+ */
 declare interface LoaderContext<Procedures = unknown> {
     readonly params: Readonly<Record<string, string>>;
     readonly pathname: string;
+    /**
+     * `true` when this invocation is the SERVER one (SSR under `voltro dev` or
+     * `voltro start`), `false` in the browser.
+     *
+     * Exists because the alternatives are traps. `query` is absent in the browser
+     * and so reads as a discriminator, but branching on the ABSENCE OF A FUNCTION
+     * says nothing about why it is absent and breaks the moment anything else
+     * becomes conditional. `headers` is worse: it is `{}` in the browser, not
+     * `undefined`, so `ctx.headers ? …` is TRUE on both paths — a consumer
+     * checked exactly that and it silently did nothing.
+     *
+     *     export const loader = async (ctx: LoaderContext) => {
+     *       if (ctx.isServer) seedStore(prefs, await ctx.query!('prefs.get'))
+     *       return null
+     *     }
+     *
+     * REQUIRED, not optional: an optional boolean is omissible, and a server path
+     * that forgot it would read as `undefined` — falsy — and claim to be the
+     * browser. Required means the compiler names every construction site.
+     */
+    readonly isServer: boolean;
     /**
      * The raw query string, INCLUDING the leading `?`, or `''` when there is
      * none. Filled on every path — client navigation, `voltro dev` SSR and
@@ -676,6 +715,8 @@ declare interface RouteSegment {
 
 export { seedPreloadedSubscription }
 
+export { seedPreloadedSubscriptionFailure }
+
 /**
  * Serialise arbitrary data for inlining into an HTML `<script>` body.
  *