@pajecawav/yamf 0.0.8 → 0.0.10

package/README.md

@@ -1,6 +1,6 @@
 # yamf
 
-SSR meta-framework on top of [Vite](https://vite.dev), [Nitro](https://nitro.build/), and [Hono JSX](https://hono.dev/docs/guides/jsx). File-based routing for HTML pages, islands architecture for client interactivity, client-side routing via [wouter](https://github.com/molefrog/wouter), React-ecosystem compatibility through [@hono/react-compat](https://github.com/honojs/react-compat), head/SEO via [unhead](https://unhead.unjs.io/), and full Nitro feature set (presets, caching, middleware, API routes).
+SSR meta-framework on top of [Vite](https://vite.dev), [Nitro](https://nitro.build/), and [Hono JSX](https://hono.dev/docs/guides/jsx). File-based routing for HTML pages, islands architecture for client interactivity, routing hooks in islands via [wouter](https://github.com/molefrog/wouter), React-ecosystem compatibility through [@hono/react-compat](https://github.com/honojs/react-compat), head/SEO via [unhead](https://unhead.unjs.io/), and full Nitro feature set (presets, caching, middleware, API routes).
 
 ## Install
 
@@ -98,6 +98,56 @@ export default definePage({
 });
 ```
 
+### Streaming and mid-stream errors
+
+Set `stream: true` to flush the shell early and stream Suspense boundaries as they resolve (better TTFB for slow data). If an async component rejects after the shell has been sent, the streaming renderer swallows the error and the fallback would stay forever — wrap risky async components with `safeAsync` to render an error fallback instead:
+
+```tsx
+import { definePage, safeAsync } from "@pajecawav/yamf";
+import { Suspense } from "hono/jsx";
+
+const SlowSection = safeAsync(Slow, () => <p>Failed to load.</p>);
+
+export default definePage({
+    stream: true,
+    render: () => (
+        <Suspense fallback={<p>Loading…</p>}>
+            <SlowSection />
+        </Suspense>
+    ),
+});
+```
+
+### Caching
+
+```tsx
+export default definePage({
+    cache: 60, // Cache-Control: public, max-age=60
+    // or
+    cache: { maxAge: 60, swr: 10, private: true },
+    render: () => ...,
+});
+```
+
+### Params and query validation
+
+`params` and `query` accept any [standard-schema](https://standardschema.dev/) validator (zod, valibot, arktype…). Validation runs before render: invalid path params produce 404, invalid query produces 400. Validated, typed values are passed to `render`:
+
+```tsx
+import { z } from "zod";
+import { definePage } from "@pajecawav/yamf";
+
+export default definePage({
+    params: z.object({ id: z.coerce.number().int() }),
+    query: z.object({ page: z.coerce.number().default(1) }),
+    render: (_event, { params, query }) => (
+        <p>
+            {params.id} — page {query.page}
+        </p>
+    ),
+});
+```
+
 ## Islands
 
 Any file matching `*.island.{tsx,ts,jsx,js}` is automatically wrapped. Each exported function becomes an island that server-renders inside `<yamf-island>` and hydrates on the client.
@@ -147,7 +197,7 @@ export default definePage({
 | `visible`        | Hydrate when scrolled into view.    |
 | `skip`           | Server-rendered only, no hydration. |
 
-Props are serialized with `devalue` (supports `Date`, `Map`, `Set`, `URL`, `RegExp`, `Error`, `BigInt`, cycles).
+Props are serialized with `devalue` (supports `Date`, `Map`, `Set`, `URL`, `RegExp`, `Error`, `BigInt`, cycles). Islands with `yamf-client="skip"` (or `false`) do not serialize their props at all — the client never reads them. In dev, yamf warns when serialized props exceed 16KB (configurable via the `YAMF_ISLAND_PROPS_LIMIT` define/env).
 
 ### React ecosystem compatibility
 
@@ -155,7 +205,7 @@ The Vite plugin aliases `react` and `react-dom` to [`@hono/react-compat`](https:
 
 ## Routing
 
-Every page renders inside a [wouter](https://github.com/molefrog/wouter) `<Router>`, seeded with the current request's `pathname` and `search` for SSR. After hydration, navigation is client-side — wouter hooks and components work inside islands and the root layout:
+Every page renders inside a [wouter](https://github.com/molefrog/wouter) `<Router>`, seeded with the current request's `pathname` and `search` for SSR. wouter hooks and components work inside islands and the root layout:
 
 ```tsx
 // src/components/Search.island.tsx
@@ -178,7 +228,11 @@ export const Search = () => {
 };
 ```
 
-wouter's `Link`, `Route`, `useLocation`, `useRoute`, and `useSearchParams` are all available. Note that yamf's file-based routing (see [File routing](#file-routing)) handles full-page SSR routes, while wouter handles client-side navigation and query-param state within a page.
+wouter's `Route`, `useLocation`, `useRoute`, and `useSearchParams` are all available for in-page routing state. wouter is an optional peer dependency of yamf — declare it in your own `package.json` when you use it in islands.
+
+**Navigation between pages is always a full page load** — pages are server-rendered HTML documents and are not shipped to the client. Use plain `<a href>` links for page navigation (optionally with [Speculation Rules](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API) prefetching/prerendering).
+
+> **Footgun:** wouter's `<Link>` inside an island intercepts the click and changes the URL with `history.pushState` — but the page content does not change, leaving the URL and the document out of sync. Do not use `<Link>` for cross-page navigation in yamf.
 
 ## Client entry
 
@@ -187,7 +241,9 @@ wouter's `Link`, `Route`, `useLocation`, `useRoute`, and `useSearchParams` are a
 import "@pajecawav/yamf/client";
 ```
 
-Side-effect import. Registers the `yamf-island` custom element and initializes `window.__UNHEAD__`. Required for island hydration and client-side `useHead`.
+Side-effect import. Registers the `yamf-island` custom element via a tiny (~1KB) bootstrap and initializes the client head. The full hydration runtime (hono/jsx DOM renderer, devalue, unhead client) is dynamically imported only when the document actually contains an island — island-free pages don't pay for it.
+
+The client head is hydrated from the server: the entry-head config (including `titleTemplate`) and the server's head entries are re-registered on the client, and head patches streamed after the shell are applied on hydration.
 
 ## Head and SEO
 
@@ -263,8 +319,8 @@ Optional. Wraps every page's content. CSS imported here is included in the asset
 
 - `useEvent()` — current `H3Event`. Works in components inside the render tree and root layout, not in `render` itself.
 - `useSSRContext()` — returns `{ head, event } | null`.
-- `useHead(input)` — push head tags.
-- `useSeoMeta(input)` — shorthand for SEO meta.
+- `useHead(input)` — push head tags. On the client this is a real hook: the head entry is created once per component, patched on re-render and disposed on unmount — call it unconditionally at the top level of the component.
+- `useSeoMeta(input)` — shorthand for SEO meta. Same lifecycle on the client.
 
 ## API routes and error handling
 

package/dist/client/index.js

@@ -1 +1,39 @@
-import "../island/client.js";
+//#region src/client/index.ts
+/**
+* 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 = /* @__PURE__ */ new Set();
+let hydrate = null;
+let loading = false;
+const loadRuntime = () => {
+	if (loading) return;
+	loading = true;
+	import("../island/client.js").then(({ hydrateIsland }) => {
+		hydrate = hydrateIsland;
+		for (const island of pending) {
+			pending.delete(island);
+			hydrate(island);
+		}
+	});
+};
+customElements.define("yamf-island", class extends HTMLElement {
+	connectedCallback() {
+		if (hydrate) {
+			hydrate(this);
+			return;
+		}
+		pending.add(this);
+		loadRuntime();
+	}
+	disconnectedCallback() {
+		pending.delete(this);
+	}
+});
+//#endregion
+
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/client/index.ts"],"sourcesContent":["/**\n * Tiny bootstrap for the island runtime.\n *\n * Defines the <yamf-island> custom element and dynamically imports the real\n * hydration runtime (hono/jsx dom renderer, devalue, unhead client) only when\n * the document actually contains an island. Pages — or whole apps — without\n * islands never pay for it.\n */\n\nconst pending: Set<HTMLElement> = new Set();\n\ntype Hydrate = (island: HTMLElement) => void;\n\nlet hydrate: Hydrate | null = null;\nlet loading: boolean = false;\n\nconst loadRuntime = (): void => {\n\tif (loading) {\n\t\treturn;\n\t}\n\n\tloading = true;\n\n\tvoid import(\"../island/client\").then(({ hydrateIsland }) => {\n\t\thydrate = hydrateIsland;\n\n\t\tfor (const island of pending) {\n\t\t\tpending.delete(island);\n\t\t\thydrate(island);\n\t\t}\n\t});\n};\n\ncustomElements.define(\n\t\"yamf-island\",\n\tclass extends HTMLElement {\n\t\tpublic connectedCallback() {\n\t\t\tif (hydrate) {\n\t\t\t\thydrate(this);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tpending.add(this);\n\t\t\tloadRuntime();\n\t\t}\n\n\t\tpublic disconnectedCallback() {\n\t\t\tpending.delete(this);\n\t\t}\n\t},\n);\n"],"mappings":";;;;;;;;;AASA,MAAM,0BAA4B,IAAI,IAAI;AAI1C,IAAI,UAA0B;AAC9B,IAAI,UAAmB;AAEvB,MAAM,oBAA0B;CAC/B,IAAI,SACH;CAGD,UAAU;CAEV,OAAY,sBAAmB,CAAC,MAAM,EAAE,oBAAoB;EAC3D,UAAU;EAEV,KAAK,MAAM,UAAU,SAAS;GAC7B,QAAQ,OAAO,MAAM;GACrB,QAAQ,MAAM;EACf;CACD,CAAC;AACF;AAEA,eAAe,OACd,eACA,cAAc,YAAY;CACzB,oBAA2B;EAC1B,IAAI,SAAS;GACZ,QAAQ,IAAI;GACZ;EACD;EAEA,QAAQ,IAAI,IAAI;EAChB,YAAY;CACb;CAEA,uBAA8B;EAC7B,QAAQ,OAAO,IAAI;CACpB;AACD,CACD"}

package/dist/components/Head.d.ts

@@ -1,6 +1,6 @@
-import { ResolvableHead } from "unhead/types";
+import { YamfHead } from "../shared/head.js";
 //#region src/components/Head.d.ts
-export type HeadProps = ResolvableHead;
+export type HeadProps = YamfHead;
 export declare const Head: (props: HeadProps) => void;
 //#endregion
 //# sourceMappingURL=Head.d.ts.map

package/dist/components/Head.js.map

@@ -1 +1 @@
-{"version":3,"file":"Head.js","names":[],"sources":["../../src/components/Head.tsx"],"sourcesContent":["import type { ResolvableHead } from \"unhead/types\";\nimport { useHead } from \"#/hooks/useHead\";\n\nexport type HeadProps = ResolvableHead;\n\nexport const Head = (props: HeadProps): void => {\n\tuseHead(props);\n};\n"],"mappings":";;AAKA,MAAa,QAAQ,UAA2B;CAC/C,QAAQ,KAAK;AACd"}
+{"version":3,"file":"Head.js","names":[],"sources":["../../src/components/Head.tsx"],"sourcesContent":["import { useHead } from \"#/hooks/useHead\";\nimport type { YamfHead } from \"#/shared/head\";\n\nexport type HeadProps = YamfHead;\n\nexport const Head = (props: HeadProps): void => {\n\tuseHead(props);\n};\n"],"mappings":";;AAKA,MAAa,QAAQ,UAA2B;CAC/C,QAAQ,KAAK;AACd"}

package/dist/hooks/isPrerendering.d.ts

@@ -0,0 +1,12 @@
+//#region src/hooks/isPrerendering.d.ts
+/**
+ * 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 declare const isPrerendering: () => boolean;
+//#endregion
+//# sourceMappingURL=isPrerendering.d.ts.map

package/dist/hooks/isPrerendering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isPrerendering.d.ts","names":[],"sources":["../../src/hooks/isPrerendering.ts"],"mappings":";;;;;;;;;qBAUa"}

package/dist/hooks/isPrerendering.js

@@ -0,0 +1,17 @@
+import { useSSRContext } from "../context/ssr.js";
+//#region src/hooks/isPrerendering.ts
+/**
+* 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`.
+*/
+const isPrerendering = () => {
+	return useSSRContext()?.event.req.headers.has("x-nitro-prerender") ?? false;
+};
+//#endregion
+export { isPrerendering };
+
+//# sourceMappingURL=isPrerendering.js.map

package/dist/hooks/isPrerendering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isPrerendering.js","names":[],"sources":["../../src/hooks/isPrerendering.ts"],"sourcesContent":["import { useSSRContext } from \"#/context/ssr\";\n\n/**\n * Whether the current render runs inside Nitro's build-time prerender pass —\n * the prerenderer fetching the route to write it to disk as a static file.\n *\n * Always `false` in dev and at request time. Prefer this over\n * `import.meta.prerender`: pages are bundled by the vite ssr service, where\n * that flag is never replaced and would always read as `undefined`.\n */\nexport const isPrerendering = (): boolean => {\n\treturn useSSRContext()?.event.req.headers.has(\"x-nitro-prerender\") ?? false;\n};\n"],"mappings":";;;;;;;;;;AAUA,MAAa,uBAAgC;CAC5C,OAAO,cAAc,CAAC,EAAE,MAAM,IAAI,QAAQ,IAAI,mBAAmB,KAAK;AACvE"}

package/dist/hooks/useHead.d.ts

@@ -1,12 +1,18 @@
+import { YamfHead } from "../shared/head.js";
 import { ClientUnhead } from "unhead/client";
-import { ResolvableHead, UseSeoMetaInput } from "unhead/types";
+import { UseSeoMetaInput } from "unhead/types";
 //#region src/hooks/useHead.d.ts
+interface StreamQueue {
+  _q?: unknown[][];
+  push?: (batch: unknown[]) => void;
+}
 declare global {
   interface Window {
-    __UNHEAD__?: ClientUnhead;
+    __unhead__?: StreamQueue;
+    __yamfHead__?: ClientUnhead;
   }
 }
-export declare const useHead: (input?: ResolvableHead) => void;
+export declare const useHead: (input?: YamfHead) => void;
 export declare const useSeoMeta: (input?: UseSeoMetaInput) => void;
 //#endregion
 //# sourceMappingURL=useHead.d.ts.map

package/dist/hooks/useHead.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useHead.d.ts","names":[],"sources":["../../src/hooks/useHead.tsx"],"mappings":";;;QAMe;YACJ;IACT,aAAa;;;qBAQF,UAAW,QAAQ;qBAYnB,aAAc,QAAQ"}
+{"version":3,"file":"useHead.d.ts","names":[],"sources":["../../src/hooks/useHead.tsx"],"mappings":";;;;UAQU;EACT;EACA,QAAQ;;QAGM;YACJ;IACT,aAAa;IACb,eAAe;;;qBAqEJ,UAAW,QAAQ;qBA0BnB,aAAc,QAAQ"}

package/dist/hooks/useHead.js

@@ -1,19 +1,61 @@
 import { useSSRContext } from "../context/ssr.js";
+import { useEffect, useRef } from "hono/jsx";
 import { useHead, useSeoMeta } from "unhead";
 import { createHead } from "unhead/client";
 //#region src/hooks/useHead.tsx
-if (!import.meta.env.SSR) window.__UNHEAD__ = createHead();
+if (!import.meta.env.SSR) {
+	const head = createHead();
+	const drain = (batch) => {
+		for (const input of batch) head.push(input);
+	};
+	const queue = window.__unhead__?._q;
+	if (queue) for (const batch of queue) drain(batch);
+	window.__unhead__ = { push: drain };
+	window.__yamfHead__ = head;
+}
+/**
+* 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 = (input, createEntry) => {
+	const entryRef = useRef(null);
+	useEffect(() => {
+		const head = window.__yamfHead__;
+		if (!head || input === void 0) return;
+		const entry = createEntry(head, input);
+		entryRef.current = entry;
+		return () => {
+			entry.dispose();
+			entryRef.current = null;
+		};
+	}, []);
+	useEffect(() => {
+		if (input !== void 0) entryRef.current?.patch(input);
+	}, [input]);
+};
 const useHead$1 = (input) => {
 	if (import.meta.env.SSR) {
+		if (input === void 0) return;
 		const ctx = useSSRContext();
-		if (ctx?.head) useHead(ctx.head, input);
-	} else if (window.__UNHEAD__) useHead(window.__UNHEAD__, input);
+		if (ctx?.head) {
+			const { seo, ...rest } = input;
+			if (seo !== void 0) useSeoMeta(ctx.head, seo);
+			useHead(ctx.head, rest);
+		}
+		return;
+	}
+	useHeadEntryLifecycle(input, (head, resolved) => useHead(head, resolved));
 };
 const useSeoMeta$1 = (input) => {
 	if (import.meta.env.SSR) {
+		if (input === void 0) 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));
 };
 //#endregion
 export { useHead$1 as useHead, useSeoMeta$1 as useSeoMeta };

package/dist/hooks/useHead.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHead.js","names":["useHead","useSeoMeta"],"sources":["../../src/hooks/useHead.tsx"],"sourcesContent":["import { useHead as _useHead, useSeoMeta as _useSeoMeta } from \"unhead\";\nimport type { ClientUnhead } from \"unhead/client\";\nimport { createHead } from \"unhead/client\";\nimport type { ResolvableHead, UseSeoMetaInput } from \"unhead/types\";\nimport { useSSRContext } from \"#/context/ssr\";\n\ndeclare global {\n\tinterface Window {\n\t\t__UNHEAD__?: ClientUnhead;\n\t}\n}\n\nif (!import.meta.env.SSR) {\n\twindow.__UNHEAD__ = createHead();\n}\n\nexport const useHead = (input?: ResolvableHead): void => {\n\tif (import.meta.env.SSR) {\n\t\tconst ctx = useSSRContext();\n\n\t\tif (ctx?.head) {\n\t\t\t_useHead(ctx.head, input);\n\t\t}\n\t} else if (window.__UNHEAD__) {\n\t\t_useHead(window.__UNHEAD__, input);\n\t}\n};\n\nexport const useSeoMeta = (input?: UseSeoMetaInput): void => {\n\tif (import.meta.env.SSR) {\n\t\tconst ctx = useSSRContext();\n\n\t\tif (ctx?.head) {\n\t\t\t_useSeoMeta(ctx.head, input);\n\t\t}\n\t} else if (window.__UNHEAD__) {\n\t\t_useSeoMeta(window.__UNHEAD__, input);\n\t}\n};\n"],"mappings":";;;;AAYA,IAAI,CAAC,YAAY,IAAI,KACpB,OAAO,aAAa,WAAW;AAGhC,MAAaA,aAAW,UAAiC;CACxD,IAAI,YAAY,IAAI,KAAK;EACxB,MAAM,MAAM,cAAc;EAE1B,IAAI,KAAK,MACR,QAAS,IAAI,MAAM,KAAK;CAE1B,OAAO,IAAI,OAAO,YACjB,QAAS,OAAO,YAAY,KAAK;AAEnC;AAEA,MAAaC,gBAAc,UAAkC;CAC5D,IAAI,YAAY,IAAI,KAAK;EACxB,MAAM,MAAM,cAAc;EAE1B,IAAI,KAAK,MACR,WAAY,IAAI,MAAM,KAAK;CAE7B,OAAO,IAAI,OAAO,YACjB,WAAY,OAAO,YAAY,KAAK;AAEtC"}
+{"version":3,"file":"useHead.js","names":["useHead","_useHead","useSeoMeta","_useSeoMeta"],"sources":["../../src/hooks/useHead.tsx"],"sourcesContent":["import { useEffect, useRef } from \"hono/jsx\";\nimport { useHead as _useHead, useSeoMeta as _useSeoMeta } from \"unhead\";\nimport type { ClientUnhead } from \"unhead/client\";\nimport { createHead } from \"unhead/client\";\nimport type { ActiveHeadEntry, ResolvableHead, UseSeoMetaInput } from \"unhead/types\";\nimport { useSSRContext } from \"#/context/ssr\";\nimport type { YamfHead } from \"#/shared/head\";\n\ninterface StreamQueue {\n\t_q?: unknown[][];\n\tpush?: (batch: unknown[]) => void;\n}\n\ndeclare global {\n\tinterface Window {\n\t\t__unhead__?: StreamQueue;\n\t\t__yamfHead__?: ClientUnhead;\n\t}\n}\n\nif (!import.meta.env.SSR) {\n\tconst head = createHead();\n\n\tconst drain = (batch: unknown[]): void => {\n\t\tfor (const input of batch) {\n\t\t\thead.push(input as ResolvableHead);\n\t\t}\n\t};\n\n\t// inline scripts (the handshake payload and streamed suspense patches)\n\t// queue into window.__unhead__ while the document parses; this module is\n\t// part of the deferred client entry and runs after parsing, so by now the\n\t// queue holds everything the server sent — drain it into the client head\n\tconst queue = window.__unhead__?._q;\n\n\tif (queue) {\n\t\tfor (const batch of queue) {\n\t\t\tdrain(batch);\n\t\t}\n\t}\n\n\t// keep late patches (a stream that is still open) working\n\twindow.__unhead__ = { push: drain };\n\n\twindow.__yamfHead__ = head;\n}\n\n/**\n * Binds an unhead entry to the calling component's lifecycle: the entry is\n * created once on mount, patched on every re-render with the latest input,\n * and disposed on unmount. Without this, every re-render pushes a new entry\n * that is never removed — a leak and growing DOM render cost.\n */\nconst useHeadEntryLifecycle = <T,>(\n\tinput: T | undefined,\n\tcreateEntry: (head: ClientUnhead, input: T) => ActiveHeadEntry<T>,\n): void => {\n\tconst entryRef = useRef<ActiveHeadEntry<T> | null>(null);\n\n\tuseEffect(() => {\n\t\tconst head = window.__yamfHead__;\n\n\t\tif (!head || input === undefined) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst entry = createEntry(head, input);\n\n\t\tentryRef.current = entry;\n\n\t\treturn () => {\n\t\t\tentry.dispose();\n\t\t\tentryRef.current = null;\n\t\t};\n\t\t// mount-only: the entry is created once per component instance\n\t\t// oxlint-disable-next-line eslint(exhaustive-deps)\n\t}, []);\n\n\tuseEffect(() => {\n\t\tif (input !== undefined) {\n\t\t\tentryRef.current?.patch(input);\n\t\t}\n\t}, [input]);\n};\n\nexport const useHead = (input?: YamfHead): void => {\n\tif (import.meta.env.SSR) {\n\t\tif (input === undefined) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst ctx = useSSRContext();\n\n\t\tif (ctx?.head) {\n\t\t\t// the custom `seo` key is yamf sugar for useSeoMeta — process it\n\t\t\t// instead of passing an unknown key down to unhead\n\t\t\tconst { seo, ...rest } = input;\n\n\t\t\tif (seo !== undefined) {\n\t\t\t\t_useSeoMeta(ctx.head, seo);\n\t\t\t}\n\n\t\t\t_useHead(ctx.head, rest);\n\t\t}\n\n\t\treturn;\n\t}\n\n\tuseHeadEntryLifecycle(input, (head, resolved) => _useHead(head, resolved));\n};\n\nexport const useSeoMeta = (input?: UseSeoMetaInput): void => {\n\tif (import.meta.env.SSR) {\n\t\tif (input === undefined) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst ctx = useSSRContext();\n\n\t\tif (ctx?.head) {\n\t\t\t_useSeoMeta(ctx.head, input);\n\t\t}\n\n\t\treturn;\n\t}\n\n\tuseHeadEntryLifecycle(input, (head, resolved) => _useSeoMeta(head, resolved));\n};\n"],"mappings":";;;;;AAoBA,IAAI,CAAC,YAAY,IAAI,KAAK;CACzB,MAAM,OAAO,WAAW;CAExB,MAAM,SAAS,UAA2B;EACzC,KAAK,MAAM,SAAS,OACnB,KAAK,KAAK,KAAuB;CAEnC;CAMA,MAAM,QAAQ,OAAO,YAAY;CAEjC,IAAI,OACH,KAAK,MAAM,SAAS,OACnB,MAAM,KAAK;CAKb,OAAO,aAAa,EAAE,MAAM,MAAM;CAElC,OAAO,eAAe;AACvB;;;;;;;AAQA,MAAM,yBACL,OACA,gBACU;CACV,MAAM,WAAW,OAAkC,IAAI;CAEvD,gBAAgB;EACf,MAAM,OAAO,OAAO;EAEpB,IAAI,CAAC,QAAQ,UAAU,KAAA,GACtB;EAGD,MAAM,QAAQ,YAAY,MAAM,KAAK;EAErC,SAAS,UAAU;EAEnB,aAAa;GACZ,MAAM,QAAQ;GACd,SAAS,UAAU;EACpB;CAGD,GAAG,CAAC,CAAC;CAEL,gBAAgB;EACf,IAAI,UAAU,KAAA,GACb,SAAS,SAAS,MAAM,KAAK;CAE/B,GAAG,CAAC,KAAK,CAAC;AACX;AAEA,MAAaA,aAAW,UAA2B;CAClD,IAAI,YAAY,IAAI,KAAK;EACxB,IAAI,UAAU,KAAA,GACb;EAGD,MAAM,MAAM,cAAc;EAE1B,IAAI,KAAK,MAAM;GAGd,MAAM,EAAE,KAAK,GAAG,SAAS;GAEzB,IAAI,QAAQ,KAAA,GACX,WAAY,IAAI,MAAM,GAAG;GAG1B,QAAS,IAAI,MAAM,IAAI;EACxB;EAEA;CACD;CAEA,sBAAsB,QAAQ,MAAM,aAAaC,QAAS,MAAM,QAAQ,CAAC;AAC1E;AAEA,MAAaC,gBAAc,UAAkC;CAC5D,IAAI,YAAY,IAAI,KAAK;EACxB,IAAI,UAAU,KAAA,GACb;EAGD,MAAM,MAAM,cAAc;EAE1B,IAAI,KAAK,MACR,WAAY,IAAI,MAAM,KAAK;EAG5B;CACD;CAEA,sBAAsB,QAAQ,MAAM,aAAaC,WAAY,MAAM,QAAQ,CAAC;AAC7E"}

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 import { ImportAssetsResult, ImportAssetsResultRaw } from "./shared/assets.js";
 import { YamfHead } from "./shared/head.js";
-import { PageHandler, definePage } from "./page.js";
+import { PageCacheOptions, PageHandler, PageRenderer, definePage } from "./page.js";
+import { SafeAsyncFallbackProps, safeAsync } from "./safeAsync.js";
 import { useSSRContext } from "./context/ssr.js";
 import { useEvent } from "./hooks/useEvent.js";
+import { isPrerendering } from "./hooks/isPrerendering.js";
 import { useHead, useSeoMeta } from "./hooks/useHead.js";
 import { IslandClientDirective, IslandProps } from "./island/types.js";
 import { Head, HeadProps } from "./components/Head.js";
-export { Head, type HeadProps, type ImportAssetsResult, type ImportAssetsResultRaw, type IslandClientDirective, type IslandProps, type PageHandler, type YamfHead, definePage, useEvent, useHead, useSSRContext, useSeoMeta };
+import { Unhead } from "unhead/server";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+export { Head, type HeadProps, type ImportAssetsResult, type ImportAssetsResultRaw, type IslandClientDirective, type IslandProps, type PageCacheOptions, type PageHandler, type PageRenderer, type SafeAsyncFallbackProps, type StandardSchemaV1, type Unhead, type YamfHead, definePage, isPrerendering, safeAsync, useEvent, useHead, useSSRContext, useSeoMeta };

package/dist/index.js

@@ -1,6 +1,8 @@
 import { useSSRContext } from "./context/ssr.js";
 import { definePage } from "./page.js";
+import { safeAsync } from "./safeAsync.js";
 import { useEvent } from "./hooks/useEvent.js";
+import { isPrerendering } from "./hooks/isPrerendering.js";
 import { useHead, useSeoMeta } from "./hooks/useHead.js";
 import { Head } from "./components/Head.js";
-export { Head, definePage, useEvent, useHead, useSSRContext, useSeoMeta };
+export { Head, definePage, isPrerendering, safeAsync, useEvent, useHead, useSSRContext, useSeoMeta };

package/dist/island/client.js

@@ -18,44 +18,53 @@ const unobserve = (target) => {
 	observer.unobserve(target);
 	listeners.delete(target);
 };
-customElements.define("yamf-island", class extends HTMLElement {
-	connectedCallback() {
-		const islandProps = parse(this.getAttribute("island-props") ?? "{}");
-		const islandSrc = this.getAttribute("island-src");
-		const islandEntry = this.getAttribute("island-entry");
-		const islandClient = this.getAttribute("island-client") ?? "load";
-		if (!islandSrc) throw new Error("Missing island-src attribute");
-		if (!islandEntry) throw new Error("Missing island-entry attribute");
-		const hydrateIsland = (mod) => {
-			const Comp = mod[islandEntry];
-			if (!Comp) throw new Error(`Missing island entry ${islandEntry} in ${islandSrc}`);
-			hydrateRoot(this, /* @__PURE__ */ jsx(Comp, { ...islandProps }));
-		};
-		const initIsland = () => {
-			const src = withLeadingSlash(islandSrc);
-			__island_raw_import__(src).then(hydrateIsland);
-		};
-		switch (islandClient) {
-			case "true":
-			case "load":
-				initIsland();
-				break;
-			case "idle":
-				requestIdleCallback(initIsland);
-				break;
-			case "visible":
-				if (this.firstElementChild) observe(this.firstElementChild, initIsland);
-				else initIsland();
-				break;
-			case "false":
-			case "skip": break;
-			default: throw new Error(`Invalid island-client value: ${islandClient}`);
-		}
+const requestIdle = (callback) => {
+	const ric = window.requestIdleCallback;
+	if (typeof ric === "function") {
+		ric(callback);
+		return;
 	}
-	disconnectedCallback() {
-		unobserve(this);
+	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.
+*/
+const hydrateIsland = (island) => {
+	const rawProps = island.getAttribute("island-props");
+	const islandProps = rawProps === null ? [] : parse(rawProps);
+	const islandSrc = island.getAttribute("island-src");
+	const islandEntry = island.getAttribute("island-entry");
+	const islandClient = island.getAttribute("island-client") ?? "load";
+	if (!islandSrc) throw new Error("Missing island-src attribute");
+	if (!islandEntry) throw new Error("Missing island-entry attribute");
+	const hydrate = (mod) => {
+		const Comp = mod[islandEntry];
+		if (!Comp) throw new Error(`Missing island entry ${islandEntry} in ${islandSrc}`);
+		hydrateRoot(island, /* @__PURE__ */ jsx(Comp, { ...islandProps }));
+	};
+	const initIsland = () => {
+		const src = withLeadingSlash(islandSrc);
+		__yamf_raw_import__(src).then(hydrate);
+	};
+	switch (islandClient) {
+		case "true":
+		case "load":
+			initIsland();
+			break;
+		case "idle":
+			requestIdle(initIsland);
+			break;
+		case "visible":
+			if (island.firstElementChild) observe(island.firstElementChild, initIsland);
+			else initIsland();
+			break;
+		case "false":
+		case "skip": break;
+		default: throw new Error(`Invalid island-client value: ${islandClient}`);
 	}
-});
+};
 //#endregion
+export { hydrateIsland };
 
 //# sourceMappingURL=client.js.map

package/dist/island/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../../src/island/client.tsx"],"sourcesContent":["import { parse } from \"devalue\";\nimport type { FC } from \"hono/jsx\";\nimport { hydrateRoot } from \"hono/jsx/dom/client\";\nimport { withLeadingSlash } from \"ufo\";\nimport type { IslandClientDirectiveSerialized } from \"./types\";\n\ndeclare let __island_raw_import__: <T>(file: string) => Promise<T>;\n\nconst listeners = new WeakMap<Element, VoidFunction>();\n\nconst observer = new IntersectionObserver(entries => {\n\tfor (const entry of entries) {\n\t\tif (entry.isIntersecting) {\n\t\t\tlisteners.get(entry.target)?.();\n\t\t\tunobserve(entry.target);\n\t\t}\n\t}\n});\n\nconst observe = (target: Element, cb: VoidFunction) => {\n\tobserver.observe(target);\n\tlisteners.set(target, cb);\n};\n\nconst unobserve = (target: Element) => {\n\tobserver.unobserve(target);\n\tlisteners.delete(target);\n};\n\ncustomElements.define(\n\t\"yamf-island\",\n\tclass extends HTMLElement {\n\t\tpublic connectedCallback() {\n\t\t\tconst islandProps = parse(this.getAttribute(\"island-props\") ?? \"{}\");\n\t\t\tconst islandSrc = this.getAttribute(\"island-src\");\n\t\t\tconst islandEntry = this.getAttribute(\"island-entry\");\n\t\t\t// oxlint-disable-next-line typescript/no-unsafe-type-assertion\n\t\t\tconst islandClient = (this.getAttribute(\"island-client\") ??\n\t\t\t\t\"load\") as IslandClientDirectiveSerialized;\n\n\t\t\tif (!islandSrc) {\n\t\t\t\tthrow new Error(\"Missing island-src attribute\");\n\t\t\t}\n\n\t\t\tif (!islandEntry) {\n\t\t\t\tthrow new Error(\"Missing island-entry attribute\");\n\t\t\t}\n\n\t\t\tconst hydrateIsland = (mod: Record<string, FC>) => {\n\t\t\t\tconst Comp = mod[islandEntry];\n\n\t\t\t\tif (!Comp) {\n\t\t\t\t\tthrow new Error(`Missing island entry ${islandEntry} in ${islandSrc}`);\n\t\t\t\t}\n\n\t\t\t\thydrateRoot(this, <Comp {...islandProps} />);\n\t\t\t};\n\n\t\t\tconst initIsland = () => {\n\t\t\t\tconst src = withLeadingSlash(islandSrc);\n\t\t\t\tvoid __island_raw_import__<Record<string, FC>>(src).then(hydrateIsland);\n\t\t\t};\n\n\t\t\tswitch (islandClient) {\n\t\t\t\tcase \"true\":\n\t\t\t\tcase \"load\":\n\t\t\t\t\tinitIsland();\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"idle\":\n\t\t\t\t\trequestIdleCallback(initIsland);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"visible\":\n\t\t\t\t\t// yamf-island has `display: contents` which breaks IntersectionObserver\n\t\t\t\t\t// so we have to observe the first child instead if it exists\n\t\t\t\t\tif (this.firstElementChild) {\n\t\t\t\t\t\tobserve(this.firstElementChild, initIsland);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tinitIsland();\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"false\":\n\t\t\t\tcase \"skip\":\n\t\t\t\t\tbreak;\n\t\t\t\tdefault:\n\t\t\t\t\tislandClient satisfies never;\n\t\t\t\t\t// oxlint-disable-next-line typescript/restrict-template-expressions\n\t\t\t\t\tthrow new Error(`Invalid island-client value: ${islandClient}`);\n\t\t\t}\n\t\t}\n\n\t\tpublic disconnectedCallback() {\n\t\t\tunobserve(this);\n\t\t}\n\t},\n);\n"],"mappings":";;;;;AAQA,MAAM,4BAAY,IAAI,QAA+B;AAErD,MAAM,WAAW,IAAI,sBAAqB,YAAW;CACpD,KAAK,MAAM,SAAS,SACnB,IAAI,MAAM,gBAAgB;EACzB,UAAU,IAAI,MAAM,MAAM,CAAC,GAAG;EAC9B,UAAU,MAAM,MAAM;CACvB;AAEF,CAAC;AAED,MAAM,WAAW,QAAiB,OAAqB;CACtD,SAAS,QAAQ,MAAM;CACvB,UAAU,IAAI,QAAQ,EAAE;AACzB;AAEA,MAAM,aAAa,WAAoB;CACtC,SAAS,UAAU,MAAM;CACzB,UAAU,OAAO,MAAM;AACxB;AAEA,eAAe,OACd,eACA,cAAc,YAAY;CACzB,oBAA2B;EAC1B,MAAM,cAAc,MAAM,KAAK,aAAa,cAAc,KAAK,IAAI;EACnE,MAAM,YAAY,KAAK,aAAa,YAAY;EAChD,MAAM,cAAc,KAAK,aAAa,cAAc;EAEpD,MAAM,eAAgB,KAAK,aAAa,eAAe,KACtD;EAED,IAAI,CAAC,WACJ,MAAM,IAAI,MAAM,8BAA8B;EAG/C,IAAI,CAAC,aACJ,MAAM,IAAI,MAAM,gCAAgC;EAGjD,MAAM,iBAAiB,QAA4B;GAClD,MAAM,OAAO,IAAI;GAEjB,IAAI,CAAC,MACJ,MAAM,IAAI,MAAM,wBAAwB,YAAY,MAAM,WAAW;GAGtE,YAAY,MAAM,oBAAC,MAAD,EAAM,GAAI,YAAc,CAAA,CAAC;EAC5C;EAEA,MAAM,mBAAmB;GACxB,MAAM,MAAM,iBAAiB,SAAS;GACtC,sBAA+C,GAAG,CAAC,CAAC,KAAK,aAAa;EACvE;EAEA,QAAQ,cAAR;GACC,KAAK;GACL,KAAK;IACJ,WAAW;IACX;GACD,KAAK;IACJ,oBAAoB,UAAU;IAC9B;GACD,KAAK;IAGJ,IAAI,KAAK,mBACR,QAAQ,KAAK,mBAAmB,UAAU;SAE1C,WAAW;IAEZ;GACD,KAAK;GACL,KAAK,QACJ;GACD,SAGC,MAAM,IAAI,MAAM,gCAAgC,cAAc;EAChE;CACD;CAEA,uBAA8B;EAC7B,UAAU,IAAI;CACf;AACD,CACD"}
+{"version":3,"file":"client.js","names":[],"sources":["../../src/island/client.tsx"],"sourcesContent":["import { parse } from \"devalue\";\nimport type { FC } from \"hono/jsx\";\nimport { hydrateRoot } from \"hono/jsx/dom/client\";\nimport { withLeadingSlash } from \"ufo\";\nimport type { IslandClientDirectiveSerialized } from \"./types\";\n\ndeclare let __yamf_raw_import__: <T>(file: string) => Promise<T>;\n\nconst listeners: WeakMap<Element, VoidFunction> = new WeakMap();\n\nconst observer: IntersectionObserver = new IntersectionObserver(entries => {\n\tfor (const entry of entries) {\n\t\tif (entry.isIntersecting) {\n\t\t\tlisteners.get(entry.target)?.();\n\t\t\tunobserve(entry.target);\n\t\t}\n\t}\n});\n\nconst observe = (target: Element, cb: VoidFunction) => {\n\tobserver.observe(target);\n\tlisteners.set(target, cb);\n};\n\nconst unobserve = (target: Element) => {\n\tobserver.unobserve(target);\n\tlisteners.delete(target);\n};\n\n// Safari does not enable requestIdleCallback by default in any stable\n// release — without a fallback, client:idle islands never hydrate there\nconst requestIdle = (callback: () => void): void => {\n\tconst ric = window.requestIdleCallback;\n\n\tif (typeof ric === \"function\") {\n\t\tric(callback);\n\t\treturn;\n\t}\n\n\tsetTimeout(callback, 1);\n};\n\n/**\n * Hydrates a single <yamf-island> island. Called by the bootstrap custom\n * element (src/client/index.ts) once this runtime module has been loaded.\n */\nexport const hydrateIsland = (island: HTMLElement): void => {\n\t// skip islands omit the attribute entirely — parse after (and only if) it\n\t// exists, otherwise parse(\"{}\") would throw \"Invalid input\" and abort the\n\t// whole pending-hydration loop\n\tconst rawProps = island.getAttribute(\"island-props\");\n\tconst islandProps = rawProps === null ? [] : parse(rawProps);\n\tconst islandSrc = island.getAttribute(\"island-src\");\n\tconst islandEntry = island.getAttribute(\"island-entry\");\n\t// oxlint-disable-next-line typescript/no-unsafe-type-assertion\n\tconst islandClient = (island.getAttribute(\"island-client\") ??\n\t\t\"load\") as IslandClientDirectiveSerialized;\n\n\tif (!islandSrc) {\n\t\tthrow new Error(\"Missing island-src attribute\");\n\t}\n\n\tif (!islandEntry) {\n\t\tthrow new Error(\"Missing island-entry attribute\");\n\t}\n\n\tconst hydrate = (mod: Record<string, FC>) => {\n\t\tconst Comp = mod[islandEntry];\n\n\t\tif (!Comp) {\n\t\t\tthrow new Error(`Missing island entry ${islandEntry} in ${islandSrc}`);\n\t\t}\n\n\t\thydrateRoot(island, <Comp {...islandProps} />);\n\t};\n\n\tconst initIsland = () => {\n\t\tconst src = withLeadingSlash(islandSrc);\n\t\tvoid __yamf_raw_import__<Record<string, FC>>(src).then(hydrate);\n\t};\n\n\tswitch (islandClient) {\n\t\tcase \"true\":\n\t\tcase \"load\":\n\t\t\tinitIsland();\n\t\t\tbreak;\n\t\tcase \"idle\":\n\t\t\trequestIdle(initIsland);\n\t\t\tbreak;\n\t\tcase \"visible\":\n\t\t\t// yamf-island has `display: contents` which breaks IntersectionObserver\n\t\t\t// so we have to observe the first child instead if it exists\n\t\t\tif (island.firstElementChild) {\n\t\t\t\tobserve(island.firstElementChild, initIsland);\n\t\t\t} else {\n\t\t\t\tinitIsland();\n\t\t\t}\n\t\t\tbreak;\n\t\tcase \"false\":\n\t\tcase \"skip\":\n\t\t\tbreak;\n\t\tdefault:\n\t\t\tislandClient satisfies never;\n\t\t\t// oxlint-disable-next-line typescript/restrict-template-expressions\n\t\t\tthrow new Error(`Invalid island-client value: ${islandClient}`);\n\t}\n};\n"],"mappings":";;;;;AAQA,MAAM,4BAA4C,IAAI,QAAQ;AAE9D,MAAM,WAAiC,IAAI,sBAAqB,YAAW;CAC1E,KAAK,MAAM,SAAS,SACnB,IAAI,MAAM,gBAAgB;EACzB,UAAU,IAAI,MAAM,MAAM,CAAC,GAAG;EAC9B,UAAU,MAAM,MAAM;CACvB;AAEF,CAAC;AAED,MAAM,WAAW,QAAiB,OAAqB;CACtD,SAAS,QAAQ,MAAM;CACvB,UAAU,IAAI,QAAQ,EAAE;AACzB;AAEA,MAAM,aAAa,WAAoB;CACtC,SAAS,UAAU,MAAM;CACzB,UAAU,OAAO,MAAM;AACxB;AAIA,MAAM,eAAe,aAA+B;CACnD,MAAM,MAAM,OAAO;CAEnB,IAAI,OAAO,QAAQ,YAAY;EAC9B,IAAI,QAAQ;EACZ;CACD;CAEA,WAAW,UAAU,CAAC;AACvB;;;;;AAMA,MAAa,iBAAiB,WAA8B;CAI3D,MAAM,WAAW,OAAO,aAAa,cAAc;CACnD,MAAM,cAAc,aAAa,OAAO,CAAC,IAAI,MAAM,QAAQ;CAC3D,MAAM,YAAY,OAAO,aAAa,YAAY;CAClD,MAAM,cAAc,OAAO,aAAa,cAAc;CAEtD,MAAM,eAAgB,OAAO,aAAa,eAAe,KACxD;CAED,IAAI,CAAC,WACJ,MAAM,IAAI,MAAM,8BAA8B;CAG/C,IAAI,CAAC,aACJ,MAAM,IAAI,MAAM,gCAAgC;CAGjD,MAAM,WAAW,QAA4B;EAC5C,MAAM,OAAO,IAAI;EAEjB,IAAI,CAAC,MACJ,MAAM,IAAI,MAAM,wBAAwB,YAAY,MAAM,WAAW;EAGtE,YAAY,QAAQ,oBAAC,MAAD,EAAM,GAAI,YAAc,CAAA,CAAC;CAC9C;CAEA,MAAM,mBAAmB;EACxB,MAAM,MAAM,iBAAiB,SAAS;EACtC,oBAA6C,GAAG,CAAC,CAAC,KAAK,OAAO;CAC/D;CAEA,QAAQ,cAAR;EACC,KAAK;EACL,KAAK;GACJ,WAAW;GACX;EACD,KAAK;GACJ,YAAY,UAAU;GACtB;EACD,KAAK;GAGJ,IAAI,OAAO,mBACV,QAAQ,OAAO,mBAAmB,UAAU;QAE5C,WAAW;GAEZ;EACD,KAAK;EACL,KAAK,QACJ;EACD,SAGC,MAAM,IAAI,MAAM,gCAAgC,cAAc;CAChE;AACD"}

package/dist/page.d.ts

@@ -3,20 +3,47 @@ import { YamfHead } from "./shared/head.js";
 import { Child } from "hono/jsx";
 import { EventHandlerResponse, H3Event, HTTPResponse } from "nitro/h3";
 import { Unhead } from "unhead/server";
+import { StandardSchemaV1 } from "@standard-schema/spec";
 import { UseSeoMetaInput } from "unhead/types";
 //#region src/page.d.ts
 export type PageHandler = (event: H3Event, params: {
   assets: ImportAssetsResult;
   head?: YamfHead;
+  nonce?: string;
 }) => EventHandlerResponse;
-export type PageRenderer = (event: H3Event, params: {
+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 declare const definePage: (options: DefinePageOptions) => PageHandler;
+export declare const definePage: <P = unknown, Q = unknown>(options: DefinePageOptions<P, Q>) => PageHandler;
 //#endregion
 //# sourceMappingURL=page.d.ts.map

package/dist/page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page.d.ts","names":[],"sources":["../src/page.tsx"],"mappings":";;;;;;;YAiBY,eACX,OAAO,SACP;EACC,QAAQ;EACR,OAAO;MAEJ;YAEO,gBACX,OAAO,SACP;EACC,MAAM;EACN,UAAU,OAAO;MAEd,eAAe,QAAQ,QAAQ,QAAQ;UAElC;EACT,QAAQ;EACR;;qBAGY,aAAc,SAAS,sBAAoB"}
+{"version":3,"file":"page.d.ts","names":[],"sources":["../src/page.tsx"],"mappings":";;;;;;;;YAkBY,eACX,OAAO,SACP;EACC,QAAQ;EACR,OAAO;EACP;MAEG;YAEO,aAAa,aAAa,gBACrC,OAAO,SACP;EACC,MAAM;EACN,UAAU,OAAO;EACjB,QAAQ;EACR,OAAO;MAEJ,eAAe,QAAQ,QAAQ,QAAQ;iBAE3B;EAChB;EACA;EACA;;UAGS,kBAAkB,aAAa;EACxC,QAAQ,aAAa,GAAG;EACxB;;;;;;EAMA,iBAAiB;;;;;;EAMjB,SAAS,0BAA0B;;;;;;EAMnC,QAAQ,0BAA0B;;qBA4FtB,aAAc,aAAa,aACvC,SAAS,kBAAkB,GAAG,OAC5B"}

package/dist/page.js

@@ -2,17 +2,58 @@ import { SSRContext } from "./context/ssr.js";
 import { Fragment } from "hono/jsx";
 import { renderToReadableStream } from "hono/jsx/streaming";
 import { Hono } from "hono/tiny";
-import { HTTPResponse, withServerTiming } from "nitro/h3";
+import { HTTPError, HTTPResponse, withServerTiming } from "nitro/h3";
 import { useSeoMeta } from "unhead";
 import { transformHtmlTemplate } from "unhead/server";
-import { createStreamableHead, wrapStream } from "unhead/stream/server";
+import { createStreamableHead, renderSSRHeadSuspenseChunk, wrapStream } from "unhead/stream/server";
 import { Root } from "virtual:yamf:root";
 import { template } from "virtual:yamf:template";
 import { Router } from "wouter";
 import { jsx } from "hono/jsx/jsx-runtime";
 //#region src/page.tsx
+const cacheControlValue = (cache) => {
+	const options = typeof cache === "number" ? { maxAge: cache } : cache;
+	const parts = [options.private ? "private" : "public", `max-age=${options.maxAge}`];
+	if (options.swr !== void 0) parts.push(`stale-while-revalidate=${options.swr}`);
+	return parts.join(", ");
+};
+const unwrapEntryInput = (input) => {
+	return typeof input === "function" ? input() : input;
+};
+const collectHeadInputs = (head) => {
+	const inputs = [];
+	for (const entry of head.entries.values()) inputs.push(unwrapEntryInput(entry.input));
+	return inputs;
+};
+const serializeHeadPayload = (inputs) => {
+	return JSON.stringify(inputs).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+};
+const scriptNonceAttr = (nonce) => {
+	return nonce ? ` nonce="${nonce.replace(/"/g, "&quot;")}"` : "";
+};
+const headPayloadScript = (inputs, nonce) => {
+	if (!inputs.length) return "";
+	return `<script${scriptNonceAttr(nonce)}>window.__unhead__&&window.__unhead__.push(${serializeHeadPayload(inputs)})<\/script>`;
+};
+const injectHeadPayload = (template, script) => {
+	if (!script) return template;
+	if (/<body[^>]*>/.test(template)) return template.replace(/<body[^>]*>/, (match) => `${match}${script}`);
+	return template.replace("</head>", `</head>${script}`);
+};
+const validateWithSchema = async (schema, value, status, what) => {
+	if (!schema) return value;
+	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;
+};
 const definePage = (options) => {
-	return async (event, { assets, head: headInit }) => {
+	return async (event, { assets, head: headInit, nonce }) => {
+		if (options.cache !== void 0) 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) => useSeoMeta(head, input);
 		seoHead(headInit?.seo);
@@ -31,9 +72,13 @@ const definePage = (options) => {
 		});
 		const content = await options.render(event, {
 			head,
-			seoHead
+			seoHead,
+			params,
+			query
 		});
 		if (content instanceof HTTPResponse) return content;
+		const payloadScript = headPayloadScript(collectHeadInputs(head), nonce);
+		const templateWithPayload = injectHeadPayload(template, payloadScript);
 		const Root$1 = Root ?? Fragment;
 		const App = async () => /* @__PURE__ */ jsx(SSRContext, {
 			value: {
@@ -49,10 +94,19 @@ const definePage = (options) => {
 		const responseInit = { headers: { "Content-Type": "text/html; charset=utf-8" } };
 		if (!options.stream) return new Hono().get("/", async (c) => withServerTiming(event, "#render", async () => {
 			let html = await (await c.html(/* @__PURE__ */ jsx(App, {}))).text();
-			html = transformHtmlTemplate(head, template.replace("<!--ssr-outlet-->", html ?? ""));
+			html = transformHtmlTemplate(head, templateWithPayload.replace("<!--ssr-outlet-->", html ?? ""));
 			return new Response(html, responseInit);
 		})).request("/");
-		const stream = wrapStream(head, renderToReadableStream(/* @__PURE__ */ jsx(App, {})), template);
+		const stream = wrapStream(head, renderToReadableStream(/* @__PURE__ */ jsx(App, {})), templateWithPayload, void 0, { flushChunk: () => {
+			let chunk;
+			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);
 	};
 };