@pyreon/server 0.14.0 → 0.16.0

package/lib/analysis/client.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"client.js","children":[{"name":"src/client.ts","uid":"9000fe03-1"}]}],"isRoot":true},"nodeParts":{"9000fe03-1":{"renderedLength":4420,"gzipLength":1683,"brotliLength":0,"metaUid":"9000fe03-0"}},"nodeMetas":{"9000fe03-0":{"id":"/src/client.ts","moduleParts":{"client.js":"9000fe03-1"},"imported":[{"uid":"9000fe03-2"},{"uid":"9000fe03-3"},{"uid":"9000fe03-4"}],"importedBy":[],"isEntry":true},"9000fe03-2":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"9000fe03-0"}]},"9000fe03-3":{"id":"@pyreon/router","moduleParts":{},"imported":[],"importedBy":[{"uid":"9000fe03-0"}]},"9000fe03-4":{"id":"@pyreon/runtime-dom","moduleParts":{},"imported":[],"importedBy":[{"uid":"9000fe03-0"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"client.js","children":[{"name":"src/client.ts","uid":"edf0a820-1"}]}],"isRoot":true},"nodeParts":{"edf0a820-1":{"renderedLength":11827,"gzipLength":3912,"brotliLength":0,"metaUid":"edf0a820-0"}},"nodeMetas":{"edf0a820-0":{"id":"/src/client.ts","moduleParts":{"client.js":"edf0a820-1"},"imported":[{"uid":"edf0a820-2"},{"uid":"edf0a820-3"},{"uid":"edf0a820-4"}],"importedBy":[],"isEntry":true},"edf0a820-2":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"edf0a820-0"}]},"edf0a820-3":{"id":"@pyreon/router","moduleParts":{},"imported":[],"importedBy":[{"uid":"edf0a820-0"}]},"edf0a820-4":{"id":"@pyreon/runtime-dom","moduleParts":{},"imported":[],"importedBy":[{"uid":"edf0a820-0"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/analysis/index.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"home/runner/work/pyreon/pyreon/packages/core/head/lib/ssr.js","uid":"e7d677ae-1"},{"name":"src","children":[{"uid":"e7d677ae-3","name":"html.ts"},{"uid":"e7d677ae-5","name":"middleware.ts"},{"uid":"e7d677ae-7","name":"handler.ts"},{"uid":"e7d677ae-9","name":"island.ts"},{"uid":"e7d677ae-11","name":"ssg.ts"},{"uid":"e7d677ae-13","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"e7d677ae-1":{"renderedLength":2713,"gzipLength":1078,"brotliLength":0,"metaUid":"e7d677ae-0"},"e7d677ae-3":{"renderedLength":2790,"gzipLength":1162,"brotliLength":0,"metaUid":"e7d677ae-2"},"e7d677ae-5":{"renderedLength":1738,"gzipLength":835,"brotliLength":0,"metaUid":"e7d677ae-4"},"e7d677ae-7":{"renderedLength":3104,"gzipLength":1337,"brotliLength":0,"metaUid":"e7d677ae-6"},"e7d677ae-9":{"renderedLength":1401,"gzipLength":664,"brotliLength":0,"metaUid":"e7d677ae-8"},"e7d677ae-11":{"renderedLength":2806,"gzipLength":1214,"brotliLength":0,"metaUid":"e7d677ae-10"},"e7d677ae-13":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"e7d677ae-12"}},"nodeMetas":{"e7d677ae-0":{"id":"/home/runner/work/pyreon/pyreon/packages/core/head/lib/ssr.js","moduleParts":{"index.js":"e7d677ae-1"},"imported":[{"uid":"e7d677ae-14"},{"uid":"e7d677ae-16"}],"importedBy":[{"uid":"e7d677ae-6"}]},"e7d677ae-2":{"id":"/src/html.ts","moduleParts":{"index.js":"e7d677ae-3"},"imported":[],"importedBy":[{"uid":"e7d677ae-12"},{"uid":"e7d677ae-6"}]},"e7d677ae-4":{"id":"/src/middleware.ts","moduleParts":{"index.js":"e7d677ae-5"},"imported":[{"uid":"e7d677ae-14"}],"importedBy":[{"uid":"e7d677ae-12"},{"uid":"e7d677ae-6"}]},"e7d677ae-6":{"id":"/src/handler.ts","moduleParts":{"index.js":"e7d677ae-7"},"imported":[{"uid":"e7d677ae-14"},{"uid":"e7d677ae-0"},{"uid":"e7d677ae-15"},{"uid":"e7d677ae-16"},{"uid":"e7d677ae-2"},{"uid":"e7d677ae-4"}],"importedBy":[{"uid":"e7d677ae-12"}]},"e7d677ae-8":{"id":"/src/island.ts","moduleParts":{"index.js":"e7d677ae-9"},"imported":[{"uid":"e7d677ae-14"}],"importedBy":[{"uid":"e7d677ae-12"}]},"e7d677ae-10":{"id":"/src/ssg.ts","moduleParts":{"index.js":"e7d677ae-11"},"imported":[{"uid":"e7d677ae-17"},{"uid":"e7d677ae-18"}],"importedBy":[{"uid":"e7d677ae-12"}]},"e7d677ae-12":{"id":"/src/index.ts","moduleParts":{"index.js":"e7d677ae-13"},"imported":[{"uid":"e7d677ae-6"},{"uid":"e7d677ae-2"},{"uid":"e7d677ae-8"},{"uid":"e7d677ae-4"},{"uid":"e7d677ae-10"}],"importedBy":[],"isEntry":true},"e7d677ae-14":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"e7d677ae-6"},{"uid":"e7d677ae-8"},{"uid":"e7d677ae-4"},{"uid":"e7d677ae-0"}]},"e7d677ae-15":{"id":"@pyreon/router","moduleParts":{},"imported":[],"importedBy":[{"uid":"e7d677ae-6"}]},"e7d677ae-16":{"id":"@pyreon/runtime-server","moduleParts":{},"imported":[],"importedBy":[{"uid":"e7d677ae-6"},{"uid":"e7d677ae-0"}]},"e7d677ae-17":{"id":"node:fs/promises","moduleParts":{},"imported":[],"importedBy":[{"uid":"e7d677ae-10"}]},"e7d677ae-18":{"id":"node:path","moduleParts":{},"imported":[],"importedBy":[{"uid":"e7d677ae-10"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"22c74963-1","name":"html.ts"},{"uid":"22c74963-3","name":"middleware.ts"},{"uid":"22c74963-5","name":"handler.ts"},{"uid":"22c74963-7","name":"island.ts"},{"uid":"22c74963-9","name":"ssg.ts"},{"uid":"22c74963-11","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"22c74963-1":{"renderedLength":2752,"gzipLength":1146,"brotliLength":0,"metaUid":"22c74963-0"},"22c74963-3":{"renderedLength":1738,"gzipLength":835,"brotliLength":0,"metaUid":"22c74963-2"},"22c74963-5":{"renderedLength":3356,"gzipLength":1446,"brotliLength":0,"metaUid":"22c74963-4"},"22c74963-7":{"renderedLength":2957,"gzipLength":1377,"brotliLength":0,"metaUid":"22c74963-6"},"22c74963-9":{"renderedLength":2806,"gzipLength":1214,"brotliLength":0,"metaUid":"22c74963-8"},"22c74963-11":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"22c74963-10"}},"nodeMetas":{"22c74963-0":{"id":"/src/html.ts","moduleParts":{"index.js":"22c74963-1"},"imported":[{"uid":"22c74963-14"}],"importedBy":[{"uid":"22c74963-10"},{"uid":"22c74963-4"}]},"22c74963-2":{"id":"/src/middleware.ts","moduleParts":{"index.js":"22c74963-3"},"imported":[{"uid":"22c74963-12"}],"importedBy":[{"uid":"22c74963-10"},{"uid":"22c74963-4"}]},"22c74963-4":{"id":"/src/handler.ts","moduleParts":{"index.js":"22c74963-5"},"imported":[{"uid":"22c74963-12"},{"uid":"22c74963-13"},{"uid":"22c74963-14"},{"uid":"22c74963-15"},{"uid":"22c74963-0"},{"uid":"22c74963-2"}],"importedBy":[{"uid":"22c74963-10"}]},"22c74963-6":{"id":"/src/island.ts","moduleParts":{"index.js":"22c74963-7"},"imported":[{"uid":"22c74963-12"}],"importedBy":[{"uid":"22c74963-10"}]},"22c74963-8":{"id":"/src/ssg.ts","moduleParts":{"index.js":"22c74963-9"},"imported":[{"uid":"22c74963-16"},{"uid":"22c74963-17"}],"importedBy":[{"uid":"22c74963-10"}]},"22c74963-10":{"id":"/src/index.ts","moduleParts":{"index.js":"22c74963-11"},"imported":[{"uid":"22c74963-4"},{"uid":"22c74963-0"},{"uid":"22c74963-6"},{"uid":"22c74963-2"},{"uid":"22c74963-8"}],"importedBy":[],"isEntry":true},"22c74963-12":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"22c74963-4"},{"uid":"22c74963-6"},{"uid":"22c74963-2"}]},"22c74963-13":{"id":"@pyreon/head/ssr","moduleParts":{},"imported":[],"importedBy":[{"uid":"22c74963-4"}]},"22c74963-14":{"id":"@pyreon/router","moduleParts":{},"imported":[],"importedBy":[{"uid":"22c74963-4"},{"uid":"22c74963-0"}]},"22c74963-15":{"id":"@pyreon/runtime-server","moduleParts":{},"imported":[],"importedBy":[{"uid":"22c74963-4"}]},"22c74963-16":{"id":"node:fs/promises","moduleParts":{},"imported":[],"importedBy":[{"uid":"22c74963-8"}]},"22c74963-17":{"id":"node:path","moduleParts":{},"imported":[],"importedBy":[{"uid":"22c74963-8"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/client.js

@@ -3,6 +3,8 @@ import { RouterProvider, createRouter, hydrateLoaderData } from "@pyreon/router"
 import { hydrateRoot, mount } from "@pyreon/runtime-dom";
 
 //#region src/client.ts
+const __DEV__ = process.env.NODE_ENV !== "production";
+const _countSink = globalThis;
 /**
 * Hydrate a server-rendered Pyreon app on the client.
 *
@@ -14,6 +16,7 @@ import { hydrateRoot, mount } from "@pyreon/runtime-dom";
 * Returns a cleanup function that unmounts the app.
 */
 function startClient(options) {
+	/* v8 ignore next 3 */
 	if (typeof document === "undefined") throw new Error("[Pyreon] startClient() can only be called in the browser.");
 	const { App, routes, container = "#app" } = options;
 	const el = typeof container === "string" ? document.querySelector(container) : container;
@@ -32,43 +35,138 @@ function startClient(options) {
 * Hydrate all `<pyreon-island>` elements on the page.
 *
 * Only loads JavaScript for components that are actually present in the HTML.
-* Respects hydration strategies (load, idle, visible, media, never).
+* Respects hydration strategies (load, idle, visible, media, never). Returns
+* a cleanup function that disconnects any pending observers/listeners.
+*
+* **`hydrate: 'never'` islands do NOT require a registry entry** — the whole
+* point of the strategy is shipping zero client JS, so importing the loader
+* (which would pull the component into the client bundle graph) defeats it.
+* Such islands are silently skipped here without a `data-island-error` flag.
 *
 * @example
 * hydrateIslands({
 *   Counter: () => import("./Counter"),
 *   Search:  () => import("./Search"),
+*   // No entry for `StaticBadge` even though it appears as a never-island
+*   // in the HTML — registering one would defeat the strategy.
 * })
 */
-/**
-* Hydrate all `<pyreon-island>` elements on the page.
-* Returns a cleanup function that disconnects any pending observers/listeners.
-*/
 function hydrateIslands(registry) {
+	/* v8 ignore next */
 	if (typeof document === "undefined") return () => {};
 	const islands = document.querySelectorAll("pyreon-island");
 	const cleanups = [];
 	for (const el of islands) {
 		const componentId = el.getAttribute("data-component");
 		if (!componentId) continue;
+		if (el.parentElement?.closest("pyreon-island")) {
+			console.error(`[Pyreon] island "${componentId}" is nested inside another <pyreon-island>. Nested islands are not supported — the outer island's hydrateRoot replaces the inner element before its loader runs. Move the inner island out of the outer island's tree, or fold them into a single component.`);
+			el.setAttribute("data-island-error", "nested");
+			if (__DEV__) _countSink.__pyreon_count__?.("island.skipped.nested");
+			continue;
+		}
+		const strategy = el.getAttribute("data-hydrate") ?? "load";
+		if (strategy === "never") {
+			if (__DEV__) _countSink.__pyreon_count__?.("island.skipped.never");
+			continue;
+		}
 		const loader = registry[componentId];
 		if (!loader) {
 			console.warn(`No loader registered for island "${componentId}"`);
+			el.setAttribute("data-island-error", "no-loader");
+			if (__DEV__) _countSink.__pyreon_count__?.("island.skipped.no-loader");
 			continue;
 		}
-		const strategy = el.getAttribute("data-hydrate") ?? "load";
-		const cleanup = scheduleHydration(el, loader, el.getAttribute("data-props") ?? "{}", strategy);
+		const propsJson = el.getAttribute("data-props") ?? "{}";
+		const prefetchCleanup = schedulePrefetch(el, loader, el.getAttribute("data-prefetch") ?? "none");
+		if (prefetchCleanup) cleanups.push(prefetchCleanup);
+		if (__DEV__) _countSink.__pyreon_count__?.("island.scheduled");
+		const cleanup = scheduleHydration(el, loader, propsJson, strategy);
 		if (cleanup) cleanups.push(cleanup);
 	}
 	return () => {
 		for (const fn of cleanups) fn();
 	};
 }
+function schedulePrefetch(el, loader, prefetch) {
+	if (prefetch === "none") return null;
+	/* v8 ignore next */
+	if (typeof window === "undefined") return null;
+	let cancelled = false;
+	const prime = () => {
+		if (cancelled) return;
+		if (__DEV__) _countSink.__pyreon_count__?.("island.prefetch");
+		loader().catch(() => {});
+	};
+	if (prefetch === "idle") {
+		if ("requestIdleCallback" in window) {
+			const id = requestIdleCallback(prime);
+			return () => {
+				cancelled = true;
+				cancelIdleCallback(id);
+			};
+		}
+		const id = setTimeout(prime, 200);
+		return () => {
+			cancelled = true;
+			clearTimeout(id);
+		};
+	}
+	if (!("IntersectionObserver" in window)) {
+		prime();
+		return null;
+	}
+	const observer = new IntersectionObserver((entries) => {
+		for (const entry of entries) if (entry.isIntersecting) {
+			observer.disconnect();
+			prime();
+			return;
+		}
+	}, { rootMargin: "200px" });
+	observer.observe(el);
+	return () => {
+		cancelled = true;
+		observer.disconnect();
+	};
+}
+/**
+* Hydrate all `<pyreon-island>` elements using a registry auto-generated by
+* `@pyreon/vite-plugin` (`pyreon({ islands: true })` is the default).
+*
+* Eliminates the manual sync between `island()` declarations in source and
+* the client-side `hydrateIslands({ ... })` call — typo / forgotten entry /
+* registry drift is the #1 author foot-gun for islands.
+*
+* The auto-registry omits `hydrate: 'never'` islands by design; their
+* components stay out of the client bundle entirely. Other strategies
+* resolve via the same dynamic-import paths their `island()` declaration
+* specified.
+*
+* The user passes the virtual-module result. We don't import it inside
+* `@pyreon/server/client` because Rolldown's static-import analysis runs
+* before plugin resolveId hooks for workspace sources, and would fail to
+* resolve the virtual specifier. Importing in the user's entry-client (where
+* the plugin's resolveId fires natively) is the clean shape.
+*
+* @example
+* // src/entry-client.ts
+* import { hydrateIslandsAuto } from '@pyreon/server/client'
+* import * as registry from 'virtual:pyreon/islands-registry'
+* hydrateIslandsAuto(registry)
+*/
+function hydrateIslandsAuto(registry) {
+	/* v8 ignore next */
+	if (typeof document === "undefined") return () => {};
+	if (!registry.__pyreonIslandsEnabled) throw new Error("[Pyreon] hydrateIslandsAuto() requires `pyreon({ islands: true })` in vite.config.ts (the default). The plugin emitted a stub registry because islands support was explicitly disabled. Either re-enable islands in the plugin, or use the manual hydrateIslands({ ... }) form.");
+	return hydrateIslands(registry.__pyreonIslandRegistry);
+}
 function scheduleHydration(el, loader, propsJson, strategy) {
+	/* v8 ignore next */
 	if (typeof window === "undefined") return null;
 	let cancelled = false;
 	const hydrate = () => {
-		if (!cancelled) hydrateIsland(el, loader, propsJson);
+		if (cancelled) return Promise.resolve();
+		return hydrateIsland(el, loader, propsJson);
 	};
 	switch (strategy) {
 		case "load":
@@ -89,7 +187,7 @@ function scheduleHydration(el, loader, propsJson, strategy) {
 			};
 		}
 		case "visible": return observeVisibility(el, hydrate);
-		case "never": return null;
+		case "interaction": return scheduleInteractionHydration(el, hydrate, DEFAULT_INTERACTION_EVENTS);
 		default:
 			if (strategy.startsWith("media(")) {
 				const query = strategy.slice(6, -1);
@@ -110,10 +208,102 @@ function scheduleHydration(el, loader, propsJson, strategy) {
 					mql.removeEventListener("change", onChange);
 				};
 			}
+			if (strategy.startsWith("interaction(")) {
+				const eventsStr = strategy.slice(12, -1).trim();
+				return scheduleInteractionHydration(el, hydrate, eventsStr ? eventsStr.split(",").map((s) => s.trim()).filter(Boolean) : DEFAULT_INTERACTION_EVENTS);
+			}
 			hydrate();
 			return null;
 	}
 }
+/**
+* Default events for the `interaction` strategy. Picked to cover the common
+* "user reaches for it" surface: keyboard (`focus`), mouse (`pointerenter`,
+* `click`), and touch (`touchstart`). First matching event triggers hydrate
+* + removes ALL listeners (one-shot).
+*/
+const DEFAULT_INTERACTION_EVENTS = [
+	"focus",
+	"click",
+	"pointerenter",
+	"touchstart"
+];
+function scheduleInteractionHydration(el, hydrate, events) {
+	let hydrationStarted = false;
+	let hydrated = false;
+	let replayPath = null;
+	el.setAttribute("data-island-state", "awaiting-interaction");
+	const startHydration = () => {
+		if (hydrationStarted) return;
+		hydrationStarted = true;
+		el.setAttribute("data-island-state", "hydrating");
+		hydrate().then(() => {
+			hydrated = true;
+			el.removeAttribute("data-island-state");
+			for (const ev of events) el.removeEventListener(ev, dispatch, INTERACTION_LISTENER_OPTS);
+			if (!replayPath) return;
+			const liveTarget = resolveReplayPath(el, replayPath);
+			if (liveTarget && liveTarget.isConnected) liveTarget.dispatchEvent(new MouseEvent("click", {
+				bubbles: true,
+				cancelable: true
+			}));
+		});
+	};
+	const dispatch = (event) => {
+		if (hydrated) return;
+		if (event.type === "click") {
+			event.stopImmediatePropagation();
+			event.preventDefault();
+			const target = event.target;
+			if (target) replayPath = captureReplayPath(el, target);
+		}
+		startHydration();
+	};
+	for (const ev of events) el.addEventListener(ev, dispatch, INTERACTION_LISTENER_OPTS);
+	return () => {
+		if (hydrated) return;
+		el.removeAttribute("data-island-state");
+		for (const ev of events) el.removeEventListener(ev, dispatch, INTERACTION_LISTENER_OPTS);
+	};
+}
+const INTERACTION_LISTENER_OPTS = {
+	passive: false,
+	capture: true
+};
+function captureReplayPath(el, target) {
+	const testid = target.getAttribute?.("data-testid");
+	if (testid) return {
+		kind: "testid",
+		value: testid
+	};
+	const steps = [];
+	let node = target;
+	while (node !== el) {
+		const parent = node.parentElement;
+		if (!parent) return null;
+		const index = Array.from(parent.children).indexOf(node);
+		if (index < 0) return null;
+		steps.unshift({
+			tag: node.tagName,
+			index
+		});
+		node = parent;
+	}
+	return {
+		kind: "path",
+		steps
+	};
+}
+function resolveReplayPath(el, path) {
+	if (path.kind === "testid") return el.querySelector(`[data-testid="${path.value}"]`);
+	let node = el;
+	for (const { tag, index } of path.steps) {
+		const child = node?.children[index];
+		if (!child || child.tagName !== tag) return null;
+		node = child;
+	}
+	return node;
+}
 async function hydrateIsland(el, loader, propsJson) {
 	const name = el.getAttribute("data-component") ?? "unknown";
 	try {
@@ -123,15 +313,21 @@ async function hydrateIsland(el, loader, propsJson) {
 			if (typeof props !== "object" || props === null || Array.isArray(props)) throw new TypeError("Expected object");
 		} catch (parseErr) {
 			console.error(`Invalid island props JSON for "${name}"`, parseErr);
+			el.setAttribute("data-island-error", "invalid-props");
+			if (__DEV__) _countSink.__pyreon_count__?.("island.error");
 			return;
 		}
 		const mod = await loader();
 		hydrateRoot(el, h(typeof mod === "function" ? mod : mod.default, props));
+		if (__DEV__) _countSink.__pyreon_count__?.("island.hydrated");
 	} catch (err) {
 		console.error(`Failed to hydrate island "${name}"`, err);
+		el.setAttribute("data-island-error", "hydration-failed");
+		if (__DEV__) _countSink.__pyreon_count__?.("island.error");
 	}
 }
 function observeVisibility(el, callback) {
+	/* v8 ignore next */
 	if (typeof window === "undefined") return null;
 	if (!("IntersectionObserver" in window)) {
 		callback();
@@ -149,5 +345,5 @@ function observeVisibility(el, callback) {
 }
 
 //#endregion
-export { hydrateIslands, startClient };
+export { hydrateIslands, hydrateIslandsAuto, startClient };
 //# sourceMappingURL=client.js.map

package/lib/index.js

@@ -1,108 +1,10 @@
-import { createContext, h, provide, pushContext, useContext } from "@pyreon/core";
-import { renderToStream, renderToString, runWithRequestContext } from "@pyreon/runtime-server";
-import { RouterProvider, createRouter, prefetchLoaderData, serializeLoaderData } from "@pyreon/router";
+import { createContext, h, provide, useContext } from "@pyreon/core";
+import { renderWithHead } from "@pyreon/head/ssr";
+import { RouterProvider, createRouter, getRedirectInfo, prefetchLoaderData, serializeLoaderData, stringifyLoaderData } from "@pyreon/router";
+import { renderToStream, runWithRequestContext } from "@pyreon/runtime-server";
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 
-//#region ../head/lib/ssr.js
-function createHeadContext() {
-	const map = /* @__PURE__ */ new Map();
-	let dirty = true;
-	let cachedTags = [];
-	let cachedTitleTemplate;
-	let cachedHtmlAttrs = {};
-	let cachedBodyAttrs = {};
-	function rebuild() {
-		if (!dirty) return;
-		dirty = false;
-		const keyed = /* @__PURE__ */ new Map();
-		const unkeyed = [];
-		let titleTemplate;
-		const htmlAttrs = {};
-		const bodyAttrs = {};
-		for (const entry of map.values()) {
-			for (const tag of entry.tags) if (tag.key) keyed.set(tag.key, tag);
-			else unkeyed.push(tag);
-			if (entry.titleTemplate !== void 0) titleTemplate = entry.titleTemplate;
-			if (entry.htmlAttrs) Object.assign(htmlAttrs, entry.htmlAttrs);
-			if (entry.bodyAttrs) Object.assign(bodyAttrs, entry.bodyAttrs);
-		}
-		cachedTags = [...keyed.values(), ...unkeyed];
-		cachedTitleTemplate = titleTemplate;
-		cachedHtmlAttrs = htmlAttrs;
-		cachedBodyAttrs = bodyAttrs;
-	}
-	return {
-		add(id, entry) {
-			map.set(id, entry);
-			dirty = true;
-		},
-		remove(id) {
-			map.delete(id);
-			dirty = true;
-		},
-		resolve() {
-			rebuild();
-			return cachedTags;
-		},
-		resolveTitleTemplate() {
-			rebuild();
-			return cachedTitleTemplate;
-		},
-		resolveHtmlAttrs() {
-			rebuild();
-			return cachedHtmlAttrs;
-		},
-		resolveBodyAttrs() {
-			rebuild();
-			return cachedBodyAttrs;
-		}
-	};
-}
-const HeadContext = createContext(null);
-const VOID_TAGS = new Set([
-	"meta",
-	"link",
-	"base"
-]);
-async function renderWithHead(app) {
-	const ctx = createHeadContext();
-	function HeadInjector() {
-		pushContext(new Map([[HeadContext.id, ctx]]));
-		return app;
-	}
-	const html = await renderToString(h(HeadInjector, null));
-	const titleTemplate = ctx.resolveTitleTemplate();
-	return {
-		html,
-		head: ctx.resolve().map((tag) => serializeTag(tag, titleTemplate)).join("\n  "),
-		htmlAttrs: ctx.resolveHtmlAttrs(),
-		bodyAttrs: ctx.resolveBodyAttrs()
-	};
-}
-function serializeTag(tag, titleTemplate) {
-	if (tag.tag === "title") {
-		const raw = tag.children || "";
-		return `<title>${esc(titleTemplate ? typeof titleTemplate === "function" ? titleTemplate(raw) : titleTemplate.replace(/%s/g, raw) : raw)}</title>`;
-	}
-	const props = tag.props;
-	const attrs = props ? Object.entries(props).map(([k, v]) => `${k}="${esc(v)}"`).join(" ") : "";
-	const open = attrs ? `<${tag.tag} ${attrs}` : `<${tag.tag}`;
-	if (VOID_TAGS.has(tag.tag)) return `${open} />`;
-	return `${open}>${(tag.children || "").replace(/<\/(script|style|noscript)/gi, "<\\/$1").replace(/<!--/g, "<\\!--")}</${tag.tag}>`;
-}
-const ESC_RE = /[&<>"]/g;
-const ESC_MAP = {
-	"&": "&amp;",
-	"<": "&lt;",
-	">": "&gt;",
-	"\"": "&quot;"
-};
-function esc(s) {
-	return ESC_RE.test(s) ? s.replace(ESC_RE, (ch) => ESC_MAP[ch]) : s;
-}
-
-//#endregion
 //#region src/html.ts
 /**
 * HTML template processing for SSR/SSG.
@@ -159,7 +61,7 @@ function processCompiledTemplate(compiled, data) {
 function buildScripts(clientEntry, loaderData) {
 	const parts = [];
 	if (loaderData && Object.keys(loaderData).length > 0) {
-		const json = JSON.stringify(loaderData).replace(/<\//g, "<\\/");
+		const json = stringifyLoaderData(loaderData);
 		parts.push(`<script>window.__PYREON_LOADER_DATA__=${json}<\/script>`);
 	}
 	parts.push(`<script type="module" src="${clientEntry}"><\/script>`);
@@ -171,7 +73,7 @@ function buildClientEntryTag(clientEntry) {
 }
 /** Fast path: build scripts with a pre-built client entry tag */
 function buildScriptsFast(clientEntryTag, loaderData) {
-	if (loaderData && Object.keys(loaderData).length > 0) return `<script>window.__PYREON_LOADER_DATA__=${JSON.stringify(loaderData).replace(/<\//g, "<\\/")}<\/script>\n  ${clientEntryTag}`;
+	if (loaderData && Object.keys(loaderData).length > 0) return `<script>window.__PYREON_LOADER_DATA__=${stringifyLoaderData(loaderData)}<\/script>\n  ${clientEntryTag}`;
 	return clientEntryTag;
 }
 
@@ -264,7 +166,7 @@ function createHandler(options) {
 		return runWithRequestContext(async () => {
 			try {
 				provideRequestLocals(ctx.locals);
-				await prefetchLoaderData(router, path);
+				await prefetchLoaderData(router, path, req);
 				const app = h(RouterProvider, { router }, h(App, null));
 				if (mode === "stream") return renderStreamResponse(app, router, compiled, clientEntryTag, ctx.headers);
 				const { html: appHtml, head } = await renderWithHead(app);
@@ -275,11 +177,17 @@ function createHandler(options) {
 					app: appHtml,
 					scripts
 				});
+				const status = router.currentRoute()?.isNotFound === true ? 404 : 200;
 				return new Response(fullHtml, {
-					status: 200,
+					status,
 					headers: ctx.headers
 				});
 			} catch (err) {
+				const info = getRedirectInfo(err);
+				if (info) return new Response(null, {
+					status: info.status,
+					headers: { Location: info.url }
+				});
 				if (__DEV__) console.error("[Pyreon Server] SSR render failed:", err);
 				return new Response("Internal Server Error", {
 					status: 500,
@@ -314,6 +222,7 @@ async function renderStreamResponse(app, router, compiled, clientEntryTag, extra
 			}
 			push(shellTail);
 		} catch (err) {
+			/* v8 ignore start */
 			if (__DEV__) console.error("[Pyreon Server] Stream render failed:", err);
 			push(`<script>console.error("[pyreon/server] Stream render failed")<\/script>`);
 			push(shellTail);
@@ -338,15 +247,17 @@ async function renderStreamResponse(app, router, compiled, clientEntryTag, extra
 *   3. Wraps the output in `<pyreon-island>` with serialized props + hydration strategy
 */
 function island(loader, options) {
-	const { name, hydrate = "load" } = options;
+	const { name, hydrate = "load", prefetch = "none" } = options;
 	const wrapper = async function IslandWrapper(props) {
 		const mod = await loader();
 		const Comp = typeof mod === "function" ? mod : mod.default;
-		return h("pyreon-island", {
+		const attrs = {
 			"data-component": name,
-			"data-props": serializeIslandProps(props),
+			"data-props": serializeIslandProps(props, name),
 			"data-hydrate": hydrate
-		}, h(Comp, props));
+		};
+		if (prefetch !== "none" && hydrate !== "load" && hydrate !== "never") attrs["data-prefetch"] = prefetch;
+		return h("pyreon-island", attrs, h(Comp, props));
 	};
 	Object.defineProperties(wrapper, {
 		__island: {
@@ -362,24 +273,51 @@ function island(loader, options) {
 		hydrate: {
 			value: hydrate,
 			enumerable: true
+		},
+		prefetch: {
+			value: prefetch,
+			enumerable: true
 		}
 	});
 	return wrapper;
 }
 /**
-* Serialize component props to a JSON string for embedding in HTML attributes.
-* Strips non-serializable values (functions, symbols, children).
+* Serialize island props to JSON for embedding in `data-props`.
+*
+* **Prop contract** (what survives the SSR → client roundtrip):
+*
+* - ✅ JSON-native: strings, finite numbers, booleans, null, arrays, plain objects
+* - ❌ **Dropped silently**: `children`, functions, symbols, `undefined` (a warning
+*   fires in dev when `children` is dropped — it's the most common surprise)
+* - ❌ **Coerced**: `Date` becomes an ISO string (no auto-revival on the client),
+*   `Map` / `Set` / class instances lose their type
+* - ⚠️ **`BigInt` is unsupported**: `JSON.stringify` throws on `BigInt` values.
+*   We catch the throw, log in dev, and emit `{}` rather than 500ing the SSR.
+*   Convert to string yourself before passing as a prop.
+*
+* For anything more complex than JSON, pass an ID and have the island component
+* fetch / restore the rich value on the client.
 */
-function serializeIslandProps(props) {
+function serializeIslandProps(props, islandName) {
 	const clean = {};
+	let droppedChildren = false;
 	for (const [key, value] of Object.entries(props)) {
-		if (key === "children") continue;
+		if (key === "children") {
+			if (value !== void 0) droppedChildren = true;
+			continue;
+		}
 		if (typeof value === "function") continue;
 		if (typeof value === "symbol") continue;
 		if (value === void 0) continue;
 		clean[key] = value;
 	}
-	return JSON.stringify(clean);
+	if (droppedChildren && process.env.NODE_ENV !== "production") console.warn(`[Pyreon] island "${islandName}" was passed children, but island props do not support children — they were dropped. Render the children inside the island component itself.`);
+	try {
+		return JSON.stringify(clean);
+	} catch (err) {
+		if (process.env.NODE_ENV !== "production") console.error(`[Pyreon] island "${islandName}" props could not be serialized (likely BigInt or circular reference). Falling back to empty props. Original error: ${err.message}`);
+		return "{}";
+	}
 }
 
 //#endregion

package/lib/types/client.d.ts

@@ -28,19 +28,58 @@ type IslandLoader = () => Promise<{
  * Hydrate all `<pyreon-island>` elements on the page.
  *
  * Only loads JavaScript for components that are actually present in the HTML.
- * Respects hydration strategies (load, idle, visible, media, never).
+ * Respects hydration strategies (load, idle, visible, media, never). Returns
+ * a cleanup function that disconnects any pending observers/listeners.
+ *
+ * **`hydrate: 'never'` islands do NOT require a registry entry** — the whole
+ * point of the strategy is shipping zero client JS, so importing the loader
+ * (which would pull the component into the client bundle graph) defeats it.
+ * Such islands are silently skipped here without a `data-island-error` flag.
  *
  * @example
  * hydrateIslands({
  *   Counter: () => import("./Counter"),
  *   Search:  () => import("./Search"),
+ *   // No entry for `StaticBadge` even though it appears as a never-island
+ *   // in the HTML — registering one would defeat the strategy.
  * })
  */
+declare function hydrateIslands(registry: Record<string, IslandLoader>): () => void;
 /**
- * Hydrate all `<pyreon-island>` elements on the page.
- * Returns a cleanup function that disconnects any pending observers/listeners.
+ * Auto-discovered island registry shape — emitted by `@pyreon/vite-plugin`
+ * as `virtual:pyreon/islands-registry`. The user passes the imported module
+ * to `hydrateIslandsAuto()`.
  */
-declare function hydrateIslands(registry: Record<string, IslandLoader>): () => void;
+interface AutoIslandRegistry {
+  readonly __pyreonIslandRegistry: Record<string, IslandLoader>;
+  readonly __pyreonIslandsEnabled: boolean;
+}
+/**
+ * Hydrate all `<pyreon-island>` elements using a registry auto-generated by
+ * `@pyreon/vite-plugin` (`pyreon({ islands: true })` is the default).
+ *
+ * Eliminates the manual sync between `island()` declarations in source and
+ * the client-side `hydrateIslands({ ... })` call — typo / forgotten entry /
+ * registry drift is the #1 author foot-gun for islands.
+ *
+ * The auto-registry omits `hydrate: 'never'` islands by design; their
+ * components stay out of the client bundle entirely. Other strategies
+ * resolve via the same dynamic-import paths their `island()` declaration
+ * specified.
+ *
+ * The user passes the virtual-module result. We don't import it inside
+ * `@pyreon/server/client` because Rolldown's static-import analysis runs
+ * before plugin resolveId hooks for workspace sources, and would fail to
+ * resolve the virtual specifier. Importing in the user's entry-client (where
+ * the plugin's resolveId fires natively) is the clean shape.
+ *
+ * @example
+ * // src/entry-client.ts
+ * import { hydrateIslandsAuto } from '@pyreon/server/client'
+ * import * as registry from 'virtual:pyreon/islands-registry'
+ * hydrateIslandsAuto(registry)
+ */
+declare function hydrateIslandsAuto(registry: AutoIslandRegistry): () => void;
 //#endregion
-export { StartClientOptions, hydrateIslands, startClient };
+export { AutoIslandRegistry, StartClientOptions, hydrateIslands, hydrateIslandsAuto, startClient };
 //# sourceMappingURL=client2.d.ts.map