@pajecawav/yamf 0.0.8 → 0.0.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pajecawav/yamf",
   "type": "module",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Yet another meta framework",
   "license": "MIT",
   "homepage": "https://github.com/pajecawav/yamf#readme",
@@ -30,36 +30,43 @@
     "access": "public"
   },
   "peerDependencies": {
-    "hono": "^4.12.30",
-    "vite": "^8.1.5"
+    "hono": "^4.13.9",
+    "vite": "^8.3.0",
+    "wouter": "^3.11.0"
+  },
+  "peerDependenciesMeta": {
+    "wouter": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@hono/react-compat": "^0.0.3",
-    "devalue": "^5.9.2",
-    "exsolve": "^1.1.1",
+    "@standard-schema/spec": "^1.1.0",
+    "devalue": "^6.0.2",
+    "exsolve": "^1.1.3",
     "nitro": "3.0.260903-beta",
     "rolldown-string": "^0.3.1",
-    "rou3": "^0.9.2",
+    "rou3": "^1.0.0",
     "ufo": "^1.6.4",
-    "unhead": "^3.4.0",
-    "wouter": "^3.11.0"
+    "unhead": "^3.4.2",
+    "wouter": "^3.13.0"
   },
   "devDependencies": {
     "@hono/react-compat": "^0.0.3",
-    "@pajecawav/tools": "^0.0.9",
+    "@pajecawav/tools": "^0.1.0",
     "@playwright/test": "^1.63.0",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.4",
     "cross-env": "^10.1.0",
-    "hono": "^4.13.7",
+    "hono": "^4.13.12",
     "husky": "^9.1.7",
     "npm-run-all2": "^9.0.3",
-    "oxfmt": "^0.66.0",
-    "oxlint": "^1.81.0",
-    "oxlint-tsgolint": "^7.0.2001",
-    "publint": "^0.3.24",
+    "oxfmt": "^0.71.0",
+    "oxlint": "^1.86.0",
+    "oxlint-tsgolint": "^7.0.2002",
+    "publint": "^0.3.25",
     "tsdown": "0.23.0",
     "typescript": "~7.0.2",
-    "vite": "^8.2.2"
+    "vite": "^8.3.2"
   },
   "scripts": {
     "build": "tsdown",

package/src/client/index.ts

@@ -1 +1,51 @@
-import "../island/client";
+/**
+ * Tiny bootstrap for the island runtime.
+ *
+ * Defines the <yamf-island> custom element and dynamically imports the real
+ * hydration runtime (hono/jsx dom renderer, devalue, unhead client) only when
+ * the document actually contains an island. Pages — or whole apps — without
+ * islands never pay for it.
+ */
+
+const pending: Set<HTMLElement> = new Set();
+
+type Hydrate = (island: HTMLElement) => void;
+
+let hydrate: Hydrate | null = null;
+let loading: boolean = false;
+
+const loadRuntime = (): void => {
+	if (loading) {
+		return;
+	}
+
+	loading = true;
+
+	void import("../island/client").then(({ hydrateIsland }) => {
+		hydrate = hydrateIsland;
+
+		for (const island of pending) {
+			pending.delete(island);
+			hydrate(island);
+		}
+	});
+};
+
+customElements.define(
+	"yamf-island",
+	class extends HTMLElement {
+		public connectedCallback() {
+			if (hydrate) {
+				hydrate(this);
+				return;
+			}
+
+			pending.add(this);
+			loadRuntime();
+		}
+
+		public disconnectedCallback() {
+			pending.delete(this);
+		}
+	},
+);

package/src/components/Head.tsx

@@ -1,7 +1,7 @@
-import type { ResolvableHead } from "unhead/types";
 import { useHead } from "#/hooks/useHead";
+import type { YamfHead } from "#/shared/head";
 
-export type HeadProps = ResolvableHead;
+export type HeadProps = YamfHead;
 
 export const Head = (props: HeadProps): void => {
 	useHead(props);

package/src/hooks/isPrerendering.ts

@@ -0,0 +1,13 @@
+import { useSSRContext } from "#/context/ssr";
+
+/**
+ * Whether the current render runs inside Nitro's build-time prerender pass —
+ * the prerenderer fetching the route to write it to disk as a static file.
+ *
+ * Always `false` in dev and at request time. Prefer this over
+ * `import.meta.prerender`: pages are bundled by the vite ssr service, where
+ * that flag is never replaced and would always read as `undefined`.
+ */
+export const isPrerendering = (): boolean => {
+	return useSSRContext()?.event.req.headers.has("x-nitro-prerender") ?? false;
+};

package/src/hooks/useHead.tsx

@@ -1,39 +1,128 @@
+import { useEffect, useRef } from "hono/jsx";
 import { useHead as _useHead, useSeoMeta as _useSeoMeta } from "unhead";
 import type { ClientUnhead } from "unhead/client";
 import { createHead } from "unhead/client";
-import type { ResolvableHead, UseSeoMetaInput } from "unhead/types";
+import type { ActiveHeadEntry, ResolvableHead, UseSeoMetaInput } from "unhead/types";
 import { useSSRContext } from "#/context/ssr";
+import type { YamfHead } from "#/shared/head";
+
+interface StreamQueue {
+	_q?: unknown[][];
+	push?: (batch: unknown[]) => void;
+}
 
 declare global {
 	interface Window {
-		__UNHEAD__?: ClientUnhead;
+		__unhead__?: StreamQueue;
+		__yamfHead__?: ClientUnhead;
 	}
 }
 
 if (!import.meta.env.SSR) {
-	window.__UNHEAD__ = createHead();
+	const head = createHead();
+
+	const drain = (batch: unknown[]): void => {
+		for (const input of batch) {
+			head.push(input as ResolvableHead);
+		}
+	};
+
+	// inline scripts (the handshake payload and streamed suspense patches)
+	// queue into window.__unhead__ while the document parses; this module is
+	// part of the deferred client entry and runs after parsing, so by now the
+	// queue holds everything the server sent — drain it into the client head
+	const queue = window.__unhead__?._q;
+
+	if (queue) {
+		for (const batch of queue) {
+			drain(batch);
+		}
+	}
+
+	// keep late patches (a stream that is still open) working
+	window.__unhead__ = { push: drain };
+
+	window.__yamfHead__ = head;
 }
 
-export const useHead = (input?: ResolvableHead): void => {
+/**
+ * Binds an unhead entry to the calling component's lifecycle: the entry is
+ * created once on mount, patched on every re-render with the latest input,
+ * and disposed on unmount. Without this, every re-render pushes a new entry
+ * that is never removed — a leak and growing DOM render cost.
+ */
+const useHeadEntryLifecycle = <T,>(
+	input: T | undefined,
+	createEntry: (head: ClientUnhead, input: T) => ActiveHeadEntry<T>,
+): void => {
+	const entryRef = useRef<ActiveHeadEntry<T> | null>(null);
+
+	useEffect(() => {
+		const head = window.__yamfHead__;
+
+		if (!head || input === undefined) {
+			return;
+		}
+
+		const entry = createEntry(head, input);
+
+		entryRef.current = entry;
+
+		return () => {
+			entry.dispose();
+			entryRef.current = null;
+		};
+		// mount-only: the entry is created once per component instance
+		// oxlint-disable-next-line eslint(exhaustive-deps)
+	}, []);
+
+	useEffect(() => {
+		if (input !== undefined) {
+			entryRef.current?.patch(input);
+		}
+	}, [input]);
+};
+
+export const useHead = (input?: YamfHead): void => {
 	if (import.meta.env.SSR) {
+		if (input === undefined) {
+			return;
+		}
+
 		const ctx = useSSRContext();
 
 		if (ctx?.head) {
-			_useHead(ctx.head, input);
+			// the custom `seo` key is yamf sugar for useSeoMeta — process it
+			// instead of passing an unknown key down to unhead
+			const { seo, ...rest } = input;
+
+			if (seo !== undefined) {
+				_useSeoMeta(ctx.head, seo);
+			}
+
+			_useHead(ctx.head, rest);
 		}
-	} else if (window.__UNHEAD__) {
-		_useHead(window.__UNHEAD__, input);
+
+		return;
 	}
+
+	useHeadEntryLifecycle(input, (head, resolved) => _useHead(head, resolved));
 };
 
 export const useSeoMeta = (input?: UseSeoMetaInput): void => {
 	if (import.meta.env.SSR) {
+		if (input === undefined) {
+			return;
+		}
+
 		const ctx = useSSRContext();
 
 		if (ctx?.head) {
 			_useSeoMeta(ctx.head, input);
 		}
-	} else if (window.__UNHEAD__) {
-		_useSeoMeta(window.__UNHEAD__, input);
+
+		return;
 	}
+
+	useHeadEntryLifecycle(input, (head, resolved) => _useSeoMeta(head, resolved));
 };

package/src/index.ts

@@ -1,8 +1,17 @@
 export { definePage } from "./page";
-export type { PageHandler } from "./page";
+export type { PageCacheOptions, PageHandler, PageRenderer } from "./page";
+
+export type { StandardSchemaV1 } from "@standard-schema/spec";
+
+// re-exported so apps can annotate render args without depending on unhead
+export type { Unhead } from "unhead/server";
+
+export { safeAsync } from "./safeAsync";
+export type { SafeAsyncFallbackProps } from "./safeAsync";
 
 export { useSSRContext } from "./context/ssr";
 export { useEvent } from "./hooks/useEvent";
+export { isPrerendering } from "./hooks/isPrerendering";
 export { useHead, useSeoMeta } from "./hooks/useHead";
 
 export type { IslandClientDirective, IslandProps } from "./island/types";

package/src/island/client.tsx

@@ -4,11 +4,11 @@ import { hydrateRoot } from "hono/jsx/dom/client";
 import { withLeadingSlash } from "ufo";
 import type { IslandClientDirectiveSerialized } from "./types";
 
-declare let __island_raw_import__: <T>(file: string) => Promise<T>;
+declare let __yamf_raw_import__: <T>(file: string) => Promise<T>;
 
-const listeners = new WeakMap<Element, VoidFunction>();
+const listeners: WeakMap<Element, VoidFunction> = new WeakMap();
 
-const observer = new IntersectionObserver(entries => {
+const observer: IntersectionObserver = new IntersectionObserver(entries => {
 	for (const entry of entries) {
 		if (entry.isIntersecting) {
 			listeners.get(entry.target)?.();
@@ -27,69 +27,81 @@ const unobserve = (target: Element) => {
 	listeners.delete(target);
 };
 
-customElements.define(
-	"yamf-island",
-	class extends HTMLElement {
-		public connectedCallback() {
-			const islandProps = parse(this.getAttribute("island-props") ?? "{}");
-			const islandSrc = this.getAttribute("island-src");
-			const islandEntry = this.getAttribute("island-entry");
-			// oxlint-disable-next-line typescript/no-unsafe-type-assertion
-			const islandClient = (this.getAttribute("island-client") ??
-				"load") as IslandClientDirectiveSerialized;
-
-			if (!islandSrc) {
-				throw new Error("Missing island-src attribute");
-			}
+// Safari does not enable requestIdleCallback by default in any stable
+// release — without a fallback, client:idle islands never hydrate there
+const requestIdle = (callback: () => void): void => {
+	const ric = window.requestIdleCallback;
 
-			if (!islandEntry) {
-				throw new Error("Missing island-entry attribute");
-			}
+	if (typeof ric === "function") {
+		ric(callback);
+		return;
+	}
 
-			const hydrateIsland = (mod: Record<string, FC>) => {
-				const Comp = mod[islandEntry];
-
-				if (!Comp) {
-					throw new Error(`Missing island entry ${islandEntry} in ${islandSrc}`);
-				}
-
-				hydrateRoot(this, <Comp {...islandProps} />);
-			};
-
-			const initIsland = () => {
-				const src = withLeadingSlash(islandSrc);
-				void __island_raw_import__<Record<string, FC>>(src).then(hydrateIsland);
-			};
-
-			switch (islandClient) {
-				case "true":
-				case "load":
-					initIsland();
-					break;
-				case "idle":
-					requestIdleCallback(initIsland);
-					break;
-				case "visible":
-					// yamf-island has `display: contents` which breaks IntersectionObserver
-					// so we have to observe the first child instead if it exists
-					if (this.firstElementChild) {
-						observe(this.firstElementChild, initIsland);
-					} else {
-						initIsland();
-					}
-					break;
-				case "false":
-				case "skip":
-					break;
-				default:
-					islandClient satisfies never;
-					// oxlint-disable-next-line typescript/restrict-template-expressions
-					throw new Error(`Invalid island-client value: ${islandClient}`);
-			}
-		}
+	setTimeout(callback, 1);
+};
+
+/**
+ * Hydrates a single <yamf-island> island. Called by the bootstrap custom
+ * element (src/client/index.ts) once this runtime module has been loaded.
+ */
+export const hydrateIsland = (island: HTMLElement): void => {
+	// skip islands omit the attribute entirely — parse after (and only if) it
+	// exists, otherwise parse("{}") would throw "Invalid input" and abort the
+	// whole pending-hydration loop
+	const rawProps = island.getAttribute("island-props");
+	const islandProps = rawProps === null ? [] : parse(rawProps);
+	const islandSrc = island.getAttribute("island-src");
+	const islandEntry = island.getAttribute("island-entry");
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion
+	const islandClient = (island.getAttribute("island-client") ??
+		"load") as IslandClientDirectiveSerialized;
+
+	if (!islandSrc) {
+		throw new Error("Missing island-src attribute");
+	}
 
-		public disconnectedCallback() {
-			unobserve(this);
+	if (!islandEntry) {
+		throw new Error("Missing island-entry attribute");
+	}
+
+	const hydrate = (mod: Record<string, FC>) => {
+		const Comp = mod[islandEntry];
+
+		if (!Comp) {
+			throw new Error(`Missing island entry ${islandEntry} in ${islandSrc}`);
 		}
-	},
-);
+
+		hydrateRoot(island, <Comp {...islandProps} />);
+	};
+
+	const initIsland = () => {
+		const src = withLeadingSlash(islandSrc);
+		void __yamf_raw_import__<Record<string, FC>>(src).then(hydrate);
+	};
+
+	switch (islandClient) {
+		case "true":
+		case "load":
+			initIsland();
+			break;
+		case "idle":
+			requestIdle(initIsland);
+			break;
+		case "visible":
+			// yamf-island has `display: contents` which breaks IntersectionObserver
+			// so we have to observe the first child instead if it exists
+			if (island.firstElementChild) {
+				observe(island.firstElementChild, initIsland);
+			} else {
+				initIsland();
+			}
+			break;
+		case "false":
+		case "skip":
+			break;
+		default:
+			islandClient satisfies never;
+			// oxlint-disable-next-line typescript/restrict-template-expressions
+			throw new Error(`Invalid island-client value: ${islandClient}`);
+	}
+};

package/src/island/server.tsx

@@ -3,6 +3,9 @@ import type { Child, FC } from "hono/jsx";
 import type { ImportAssetsResultRaw } from "#/shared/assets";
 import type { IslandClientDirective, IslandProps } from "./types";
 
+// configurable via the YAMF_ISLAND_PROPS_LIMIT env / define
+const PROPS_WARNING_LIMIT = Number(import.meta.env["YAMF_ISLAND_PROPS_LIMIT"]) || 16 * 1024;
+
 declare module "hono/jsx" {
 	namespace JSX {
 		interface IntrinsicElements {
@@ -18,6 +21,10 @@ declare module "hono/jsx" {
 	}
 }
 
+const isSkipDirective = (directive: IslandClientDirective | undefined): boolean => {
+	return directive === false || directive === "skip";
+};
+
 export const createIsland = (
 	Component: FC,
 	exportName: string,
@@ -31,9 +38,25 @@ export const createIsland = (
 			throw new Error(`Missing island entry for island ${Component.name}`);
 		}
 
+		// skip islands are never hydrated — serializing their props into the
+		// attribute would be pure dead weight in the HTML
+		const skip = isSkipDirective(clientDirective);
+
+		let islandProps: string | undefined;
+
+		if (!skip) {
+			islandProps = stringify(props);
+
+			if (import.meta.env.DEV && islandProps.length > PROPS_WARNING_LIMIT) {
+				console.warn(
+					`[yamf] island "${exportName}" receives ${(islandProps.length / 1024).toFixed(1)} KB of serialized props — consider slimming them down (limit: ${PROPS_WARNING_LIMIT} bytes, configurable via YAMF_ISLAND_PROPS_LIMIT)`,
+				);
+			}
+		}
+
 		return (
 			<yamf-island
-				island-props={stringify(props)}
+				island-props={islandProps}
 				island-src={assets.entry}
 				island-entry={exportName}
 				island-client={clientDirective}