@pajecawav/yamf 0.0.7 → 0.0.9

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,77 @@ 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 => {
+	const islandProps = parse(island.getAttribute("island-props") ?? "{}");
+	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

@@ -1,7 +1,10 @@
 import { stringify } from "devalue";
 import type { Child, FC } from "hono/jsx";
 import type { ImportAssetsResultRaw } from "#/shared/assets";
-import type { IslandClientDirective } from "./types";
+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 {
@@ -10,7 +13,7 @@ declare module "hono/jsx" {
 				"island-props"?: string;
 				"island-src": string;
 				"island-entry": string;
-				"island-client": IslandClientDirective;
+				"island-client"?: IslandClientDirective;
 				children: Child;
 				style?: JSX.CSSProperties;
 			};
@@ -18,23 +21,45 @@ declare module "hono/jsx" {
 	}
 }
 
+const isSkipDirective = (directive: IslandClientDirective | undefined): boolean => {
+	return directive === false || directive === "skip";
+};
+
 export const createIsland = (
 	Component: FC,
 	exportName: string,
 	assets: ImportAssetsResultRaw,
 ): FC => {
-	const ComponentWrapper: FC & { name: string } = props => {
+	const ComponentWrapper: FC<IslandProps> & { name: string } = ({
+		"yamf-client": clientDirective,
+		...props
+	}) => {
 		if (!assets.entry) {
 			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}
-				// oxlint-disable-next-line typescript/no-unsafe-type-assertion
-				island-client={props["yamf-client"] as IslandClientDirective}
+				island-client={clientDirective}
 				// TODO: export CSS?
 				style={{ display: "contents" }}
 			>

package/src/page.tsx

@@ -1,13 +1,14 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { Fragment, type Child } from "hono/jsx";
 import { renderToReadableStream } from "hono/jsx/streaming";
 import { Hono } from "hono/tiny";
 import type { EventHandlerResponse, H3Event } from "nitro/h3";
-import { HTTPResponse, withServerTiming } from "nitro/h3";
+import { HTTPError, HTTPResponse, withServerTiming } from "nitro/h3";
 import { useSeoMeta } from "unhead";
 import type { Unhead } from "unhead/server";
 import { transformHtmlTemplate } from "unhead/server";
-import { createStreamableHead, wrapStream } from "unhead/stream/server";
-import type { ResolvableLink, UseSeoMetaInput } from "unhead/types";
+import { createStreamableHead, renderSSRHeadSuspenseChunk, wrapStream } from "unhead/stream/server";
+import type { ResolvableHead, ResolvableLink, UseSeoMetaInput } from "unhead/types";
 import { Root as RootComponent } from "virtual:yamf:root";
 import { template } from "virtual:yamf:template";
 import { Router } from "wouter";
@@ -20,24 +21,160 @@ export type PageHandler = (
 	params: {
 		assets: ImportAssetsResult;
 		head?: YamfHead;
+		nonce?: string;
 	},
 ) => EventHandlerResponse;
 
-export type PageRenderer = (
+export type PageRenderer<P = unknown, Q = unknown> = (
 	event: H3Event,
 	params: {
 		head: Unhead;
 		seoHead: (input: UseSeoMetaInput) => void;
+		params: P;
+		query: Q;
 	},
 ) => HTTPResponse | Child | Promise<Child | HTTPResponse>;
 
-interface DefinePageOptions {
-	render: PageRenderer;
+export interface PageCacheOptions {
+	maxAge: number;
+	swr?: number;
+	private?: boolean;
+}
+
+interface DefinePageOptions<P = unknown, Q = unknown> {
+	render: PageRenderer<P, Q>;
 	stream?: boolean;
+	/**
+	 * Cache-Control for the page response. `60` is shorthand for
+	 * `{ maxAge: 60 }` → `Cache-Control: public, max-age=60`; the object form
+	 * adds `stale-while-revalidate` and `private`.
+	 */
+	cache?: number | PageCacheOptions;
+	/**
+	 * Standard-schema validator (zod, valibot, arktype, …) for the route
+	 * params. On failure the page throws HTTPError 404 before render; the
+	 * validated, typed output is passed to render as `params`.
+	 */
+	params?: StandardSchemaV1<unknown, P>;
+	/**
+	 * Standard-schema validator for the search params. On failure the page
+	 * throws HTTPError 400 before render; the validated, typed output is
+	 * passed to render as `query`. Repeated keys collapse to the last value.
+	 */
+	query?: StandardSchemaV1<unknown, Q>;
 }
 
-export const definePage = (options: DefinePageOptions): PageHandler => {
-	return async (event, { assets, head: headInit }) => {
+const cacheControlValue = (cache: number | PageCacheOptions): string => {
+	const options = typeof cache === "number" ? { maxAge: cache } : cache;
+
+	const parts = [options.private ? "private" : "public", `max-age=${options.maxAge}`];
+
+	if (options.swr !== undefined) {
+		parts.push(`stale-while-revalidate=${options.swr}`);
+	}
+
+	return parts.join(", ");
+};
+
+// resolvable head inputs may be functions — resolve them for serialization
+const unwrapEntryInput = (input: unknown): ResolvableHead => {
+	return (
+		typeof input === "function" ? (input as () => ResolvableHead)() : input
+	) as ResolvableHead;
+};
+
+const collectHeadInputs = (head: Unhead): ResolvableHead[] => {
+	const inputs: ResolvableHead[] = [];
+
+	for (const entry of head.entries.values()) {
+		inputs.push(unwrapEntryInput(entry.input));
+	}
+
+	return inputs;
+};
+
+const serializeHeadPayload = (inputs: ResolvableHead[]): string => {
+	return JSON.stringify(inputs)
+		.replace(/</g, "\\u003c")
+		.replace(/>/g, "\\u003e")
+		.replace(/&/g, "\\u0026");
+};
+
+const scriptNonceAttr = (nonce?: string): string => {
+	return nonce ? ` nonce="${nonce.replace(/"/g, "&quot;")}"` : "";
+};
+
+// client handshake: re-register the server head entries (titleTemplate,
+// htmlAttrs, page-level head) into the client head via the unhead stream
+// queue, so post-hydration updates keep templates and adopt SSR tags
+// instead of duplicating them
+const headPayloadScript = (inputs: ResolvableHead[], nonce?: string): string => {
+	if (!inputs.length) {
+		return "";
+	}
+
+	return `<script${scriptNonceAttr(nonce)}>window.__unhead__&&window.__unhead__.push(${serializeHeadPayload(inputs)})</script>`;
+};
+
+// injected at the start of <body>: unhead rebuilds the html/head tags and
+// appends its head tags (including the stream bootstrap shim) inside <head>,
+// so the payload must come after them for window.__unhead__ to exist
+const injectHeadPayload = (template: string, script: string): string => {
+	if (!script) {
+		return template;
+	}
+
+	if (/<body[^>]*>/.test(template)) {
+		return template.replace(/<body[^>]*>/, match => `${match}${script}`);
+	}
+
+	return template.replace("</head>", `</head>${script}`);
+};
+
+const validateWithSchema = async <T,>(
+	schema: StandardSchemaV1<unknown, T> | undefined,
+	value: unknown,
+	status: 400 | 404,
+	what: string,
+): Promise<T> => {
+	if (!schema) {
+		return value as T;
+	}
+
+	const result = await schema["~standard"].validate(value);
+
+	if (result.issues) {
+		throw new HTTPError(`Invalid ${what}`, {
+			status,
+			cause: new Error(result.issues.map(issue => issue.message).join("; ")),
+		});
+	}
+
+	return result.value;
+};
+
+export const definePage = <P = unknown, Q = unknown>(
+	options: DefinePageOptions<P, Q>,
+): PageHandler => {
+	return async (event, { assets, head: headInit, nonce }) => {
+		if (options.cache !== undefined) {
+			event.res.headers.set("cache-control", cacheControlValue(options.cache));
+		}
+
+		const params = await validateWithSchema(
+			options.params,
+			event.context.params,
+			404,
+			"path params",
+		);
+
+		const query = await validateWithSchema(
+			options.query,
+			Object.fromEntries(event.url.searchParams),
+			400,
+			"query params",
+		);
+
 		const { head } = createStreamableHead({ init: [headInit] });
 		const seoHead = (input?: UseSeoMetaInput) => useSeoMeta(head, input);
 		seoHead(headInit?.seo);
@@ -50,12 +187,17 @@ export const definePage = (options: DefinePageOptions): PageHandler => {
 			script: [{ type: "module", src: assets.entry }],
 		});
 
-		const content = await options.render(event, { head, seoHead });
+		const content = await options.render(event, { head, seoHead, params, query });
 
 		if (content instanceof HTTPResponse) {
 			return content;
 		}
 
+		// must be collected before wrapStream — it clears entries after the shell
+		const payloadScript = headPayloadScript(collectHeadInputs(head), nonce);
+
+		const templateWithPayload = injectHeadPayload(template, payloadScript);
+
 		const Root = RootComponent ?? Fragment;
 
 		const App = async () => (
@@ -83,7 +225,7 @@ export const definePage = (options: DefinePageOptions): PageHandler => {
 
 						html = transformHtmlTemplate(
 							head,
-							template.replace("<!--ssr-outlet-->", html ?? ""),
+							templateWithPayload.replace("<!--ssr-outlet-->", html ?? ""),
 						);
 
 						return new Response(html, responseInit);
@@ -92,7 +234,30 @@ export const definePage = (options: DefinePageOptions): PageHandler => {
 				.request("/");
 		}
 
-		const stream = wrapStream(head, renderToReadableStream(<App />), template);
+		const stream = wrapStream(
+			head,
+			renderToReadableStream(<App />),
+			templateWithPayload,
+			undefined,
+			{
+				// same as unhead's default flushChunk, but with CSP nonce support
+				flushChunk: () => {
+					let chunk: string;
+
+					try {
+						chunk = renderSSRHeadSuspenseChunk(head);
+					} catch {
+						return "";
+					}
+
+					if (!chunk) {
+						return "";
+					}
+
+					return `<script${scriptNonceAttr(nonce)}>window.__unhead__&&(${chunk});document.currentScript.remove()</script>`;
+				},
+			},
+		);
 
 		return new Response(stream, responseInit);
 	};

package/src/safeAsync.tsx

@@ -0,0 +1,46 @@
+import type { Child, FC } from "hono/jsx";
+
+export interface SafeAsyncFallbackProps {
+	error: unknown;
+}
+
+const DefaultFallback: FC<SafeAsyncFallbackProps> = () => (
+	<div
+		role="alert"
+		data-testid="yamf-error"
+		style="padding: 1rem; border: 1px solid currentColor"
+	>
+		Something went wrong.
+	</div>
+);
+
+/**
+ * Wraps an async server component with error handling for streaming SSR.
+ *
+ * When an async component inside a Suspense boundary rejects after the shell
+ * has been flushed, the streaming renderer swallows the error: the browser
+ * keeps the loading fallback forever with a 200 status, and nothing reaches
+ * the error handler. `safeAsync` awaits the component directly, so a
+ * rejection is caught here and rendered as `fallback` instead.
+ *
+ * Catches errors of the wrapped component itself, not of its subtree.
+ */
+export const safeAsync = <P extends object>(
+	Component: (props: P) => Child | Promise<Child>,
+	fallback: FC<SafeAsyncFallbackProps> = DefaultFallback,
+): FC<P> => {
+	const Safe = async (props: P): Promise<Child> => {
+		try {
+			return await Component(props);
+		} catch (error) {
+			console.error("[yamf] safeAsync: async component rejected", error);
+
+			return fallback({ error });
+		}
+	};
+
+	// hono's FC type does not include Promise<Child> in its return type,
+	// but the JSX renderer awaits component results
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion
+	return Safe as FC<P>;
+};

package/src/server/entry.tsx

@@ -24,6 +24,8 @@ interface Route {
 
 const router = createRouter<Route>();
 
+const registeredRoutes = new Map<string, string>();
+
 for (const [relativePath, handler] of Object.entries(pages).toSorted((a, b) =>
 	a[0].localeCompare(b[0]),
 )) {
@@ -46,6 +48,16 @@ for (const [relativePath, handler] of Object.entries(pages).toSorted((a, b) =>
 
 	route = withLeadingSlash(withoutTrailingSlash(route));
 
+	const conflictingFile = registeredRoutes.get(route);
+
+	if (conflictingFile && conflictingFile !== relativePath) {
+		console.warn(
+			`[yamf] duplicate page route "${route}": ${conflictingFile} and ${relativePath} both map to it — the routes conflict`,
+		);
+	}
+
+	registeredRoutes.set(route, relativePath);
+
 	addRoute(router, "GET", route, {
 		handler,
 		serverAssets: pagesServerAssets[relativePath],
@@ -57,6 +69,15 @@ export type ServerEntry = EventHandlerWithFetch<EventHandlerRequest, Promise<unk
 export interface DefineServerEntryOptions {
 	head?: YamfHead | ((event: H3Event) => YamfHead);
 	disableEarlyHints?: boolean;
+	/**
+	 * CSP nonce for the inline scripts yamf injects (head handshake payload
+	 * and streamed head patches).
+	 *
+	 * Note: unhead's stream bootstrap script (`window.__unhead__||(…)`) does
+	 * not support a nonce in unhead 3.x — with a strict `script-src` CSP it
+	 * must be allowed separately (e.g. via a hash).
+	 */
+	nonce?: string | ((event: H3Event) => string | undefined);
 }
 
 export const defineServerEntry = (options?: DefineServerEntryOptions): ServerEntry => {
@@ -72,7 +93,9 @@ export const defineServerEntry = (options?: DefineServerEntryOptions): ServerEnt
 
 		const assets = clientAssets.merge(...[rootAssets, serverAssets].filter(x => !!x));
 
-		if (!options?.disableEarlyHints) {
+		// early hints are pointless inside the prerender worker — nitro's
+		// prerenderer buffers the response to a file and discards them
+		if (!options?.disableEarlyHints && !event.req.headers.has("x-nitro-prerender")) {
 			const link = [
 				...assets.js.map(script => `<${script.href}>; rel=modulepreload`),
 				...assets.css.map(style => `<${style.href}>; rel=preload; as=style`),
@@ -86,6 +109,7 @@ export const defineServerEntry = (options?: DefineServerEntryOptions): ServerEnt
 		return (await handler())(event, {
 			assets,
 			head: typeof options?.head === "function" ? options.head(event) : options?.head,
+			nonce: typeof options?.nonce === "function" ? options.nonce(event) : options?.nonce,
 		});
 	};
 

package/src/vite/index.ts

@@ -1,8 +1,10 @@
 import { existsSync } from "node:fs";
+import { resolve } from "node:path";
 import type { NitroPluginConfig } from "nitro/vite";
 import { nitro } from "nitro/vite";
 import type { EnvironmentOptions, PluginOption } from "vite";
 import { islands } from "./islands";
+import { prerenderModule } from "./prerender";
 import { virtualAssets } from "./virtual-assets";
 import { virtualErrorHandler } from "./virtual-error-handler";
 import { virtualPages } from "./virtual-pages";
@@ -19,7 +21,11 @@ const yamf = (options?: YamfOptions): PluginOption[] => {
 	// TODO: extendable config
 	plugins.push({
 		name: "yamf:config",
-		config() {
+		config(config) {
+			// resolved against the vite root (not cwd) so running vite from
+			// another working directory does not silently drop the ssr entry
+			const root = config.root ?? process.cwd();
+
 			const ssrEnv: EnvironmentOptions = {
 				build: {
 					// TODO: figure out if this should be true
@@ -61,7 +67,7 @@ const yamf = (options?: YamfOptions): PluginOption[] => {
 					],
 				},
 				environments: {
-					...(existsSync("./src/server.tsx") ? { ssr: ssrEnv } : {}),
+					...(existsSync(resolve(root, "./src/server.tsx")) ? { ssr: ssrEnv } : {}),
 					client: {
 						build: {
 							rolldownOptions: {
@@ -82,16 +88,37 @@ const yamf = (options?: YamfOptions): PluginOption[] => {
 	plugins.push(virtualTemplate());
 	plugins.push(virtualRoot());
 
+	// registers the nitro module that makes prerender work (see prerenderModule)
+	plugins.push({
+		name: "yamf:prerender",
+		nitro: prerenderModule,
+	});
+
+	// reserved nitro keys are yamf-controlled and intentionally win over user
+	// values; everything else the user passes through wins. user publicAssets
+	// are merged with yamf's instead of being dropped
+	const {
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		serverDir: _serverDir,
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		renderer: _renderer,
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		compressPublicAssets: _compressPublicAssets,
+		publicAssets: userPublicAssets,
+		...userNitro
+	} = options?.nitro ?? {};
+
 	plugins.push(
 		nitro({
+			...userNitro,
 			serverDir: "./src",
 			renderer: false,
-			...options?.nitro,
 			compressPublicAssets: {
 				gzip: true,
 				brotli: true,
 			},
 			publicAssets: [
+				...(userPublicAssets ?? []),
 				{
 					baseURL: "assets",
 					dir: "./public/assets",