@pyreon/server 0.15.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":"src","children":[{"uid":"339bb46f-1","name":"html.ts"},{"uid":"339bb46f-3","name":"middleware.ts"},{"uid":"339bb46f-5","name":"handler.ts"},{"uid":"339bb46f-7","name":"island.ts"},{"uid":"339bb46f-9","name":"ssg.ts"},{"uid":"339bb46f-11","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"339bb46f-1":{"renderedLength":2790,"gzipLength":1162,"brotliLength":0,"metaUid":"339bb46f-0"},"339bb46f-3":{"renderedLength":1738,"gzipLength":835,"brotliLength":0,"metaUid":"339bb46f-2"},"339bb46f-5":{"renderedLength":3261,"gzipLength":1391,"brotliLength":0,"metaUid":"339bb46f-4"},"339bb46f-7":{"renderedLength":1401,"gzipLength":664,"brotliLength":0,"metaUid":"339bb46f-6"},"339bb46f-9":{"renderedLength":2806,"gzipLength":1214,"brotliLength":0,"metaUid":"339bb46f-8"},"339bb46f-11":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"339bb46f-10"}},"nodeMetas":{"339bb46f-0":{"id":"/src/html.ts","moduleParts":{"index.js":"339bb46f-1"},"imported":[],"importedBy":[{"uid":"339bb46f-10"},{"uid":"339bb46f-4"}]},"339bb46f-2":{"id":"/src/middleware.ts","moduleParts":{"index.js":"339bb46f-3"},"imported":[{"uid":"339bb46f-12"}],"importedBy":[{"uid":"339bb46f-10"},{"uid":"339bb46f-4"}]},"339bb46f-4":{"id":"/src/handler.ts","moduleParts":{"index.js":"339bb46f-5"},"imported":[{"uid":"339bb46f-12"},{"uid":"339bb46f-13"},{"uid":"339bb46f-14"},{"uid":"339bb46f-15"},{"uid":"339bb46f-0"},{"uid":"339bb46f-2"}],"importedBy":[{"uid":"339bb46f-10"}]},"339bb46f-6":{"id":"/src/island.ts","moduleParts":{"index.js":"339bb46f-7"},"imported":[{"uid":"339bb46f-12"}],"importedBy":[{"uid":"339bb46f-10"}]},"339bb46f-8":{"id":"/src/ssg.ts","moduleParts":{"index.js":"339bb46f-9"},"imported":[{"uid":"339bb46f-16"},{"uid":"339bb46f-17"}],"importedBy":[{"uid":"339bb46f-10"}]},"339bb46f-10":{"id":"/src/index.ts","moduleParts":{"index.js":"339bb46f-11"},"imported":[{"uid":"339bb46f-4"},{"uid":"339bb46f-0"},{"uid":"339bb46f-6"},{"uid":"339bb46f-2"},{"uid":"339bb46f-8"}],"importedBy":[],"isEntry":true},"339bb46f-12":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"339bb46f-4"},{"uid":"339bb46f-6"},{"uid":"339bb46f-2"}]},"339bb46f-13":{"id":"@pyreon/head/ssr","moduleParts":{},"imported":[],"importedBy":[{"uid":"339bb46f-4"}]},"339bb46f-14":{"id":"@pyreon/router","moduleParts":{},"imported":[],"importedBy":[{"uid":"339bb46f-4"}]},"339bb46f-15":{"id":"@pyreon/runtime-server","moduleParts":{},"imported":[],"importedBy":[{"uid":"339bb46f-4"}]},"339bb46f-16":{"id":"node:fs/promises","moduleParts":{},"imported":[],"importedBy":[{"uid":"339bb46f-8"}]},"339bb46f-17":{"id":"node:path","moduleParts":{},"imported":[],"importedBy":[{"uid":"339bb46f-8"}]}},"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,6 +1,6 @@
 import { createContext, h, provide, useContext } from "@pyreon/core";
 import { renderWithHead } from "@pyreon/head/ssr";
-import { RouterProvider, createRouter, getRedirectInfo, prefetchLoaderData, serializeLoaderData } from "@pyreon/router";
+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";
@@ -61,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>`);
@@ -73,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;
 }
 
@@ -177,8 +177,9 @@ 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) {
@@ -221,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);
@@ -245,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: {
@@ -269,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

package/lib/types/index.d.ts

@@ -102,14 +102,6 @@ interface HandlerOptions {
 declare function createHandler(options: HandlerOptions): (req: Request) => Promise<Response>;
 //#endregion
 //#region src/html.d.ts
-/**
- * HTML template processing for SSR/SSG.
- *
- * Templates use comment placeholders:
- *   <!--pyreon-head-->     — replaced with <head> tags (title, meta, link, etc.)
- *   <!--pyreon-app-->      — replaced with rendered application HTML
- *   <!--pyreon-scripts-->  — replaced with client entry script + inline loader data
- */
 declare const DEFAULT_TEMPLATE = "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <!--pyreon-head-->\n</head>\n<body>\n  <div id=\"app\"><!--pyreon-app--></div>\n  <!--pyreon-scripts-->\n</body>\n</html>";
 interface TemplateData {
   head: string;
@@ -138,17 +130,25 @@ declare function processCompiledTemplate(compiled: CompiledTemplate, data: Templ
 declare function buildScripts(clientEntry: string, loaderData: Record<string, unknown> | null): string;
 //#endregion
 //#region src/island.d.ts
-type HydrationStrategy = 'load' | 'idle' | 'visible' | 'never' | `media(${string})`;
+type HydrationStrategy = 'load' | 'idle' | 'visible' | 'interaction' | 'never' | `media(${string})` | `interaction(${string})`;
+type PrefetchStrategy = 'none' | 'idle' | 'visible';
 interface IslandOptions {
   /** Unique name — must match the key in the client-side hydrateIslands() registry */
   name: string;
   /** When to hydrate on the client (default: "load") */
   hydrate?: HydrationStrategy;
+  /**
+   * Pre-warm the island's chunk before its hydration trigger fires.
+   * Best paired with `hydrate: 'visible'` or `hydrate: 'media(...)'`.
+   * Default: "none". No-op when paired with `hydrate: 'load'` or `'never'`.
+   */
+  prefetch?: PrefetchStrategy;
 }
 interface IslandMeta {
   readonly __island: true;
   readonly name: string;
   readonly hydrate: HydrationStrategy;
+  readonly prefetch: PrefetchStrategy;
 }
 /**
  * Create an island component.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/server",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "SSR handler, SSG prerender, and island architecture for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/server#readme",
   "bugs": {
@@ -43,19 +43,22 @@
     "build": "vl_rolldown_build",
     "dev": "vl_rolldown_build-watch",
     "test": "vitest run",
+    "test:browser": "vitest run --config ./vitest.browser.config.ts",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint .",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.15.0",
-    "@pyreon/head": "^0.15.0",
-    "@pyreon/reactivity": "^0.15.0",
-    "@pyreon/router": "^0.15.0",
-    "@pyreon/runtime-dom": "^0.15.0",
-    "@pyreon/runtime-server": "^0.15.0"
+    "@pyreon/core": "^0.16.0",
+    "@pyreon/head": "^0.16.0",
+    "@pyreon/reactivity": "^0.16.0",
+    "@pyreon/router": "^0.16.0",
+    "@pyreon/runtime-dom": "^0.16.0",
+    "@pyreon/runtime-server": "^0.16.0"
   },
   "devDependencies": {
-    "@pyreon/manifest": "0.13.1"
+    "@pyreon/manifest": "0.13.1",
+    "@vitest/browser": "^4.1.4",
+    "@vitest/browser-playwright": "^4.1.4"
   }
 }