@pyreon/zero 0.16.0 → 0.19.0

package/lib/server.js

@@ -1,7 +1,7 @@
-import { _ as render404Page, a as detectLocaleFromHeader, c as vercelAdapter, d as netlifyAdapter, f as cloudflareAdapter, g as createServer, h as resolveConfig, i as createLocaleContext, l as staticAdapter, m as defineConfig, o as i18nRouting, p as bunAdapter, r as zeroPlugin, s as resolveAdapter, t as getZeroPluginConfig, u as nodeAdapter, v as createApp } from "./vite-plugin-xjWZwudX.js";
-import { i as generateRouteModule, o as parseFileRoutes, r as generateMiddlewareModule, s as scanRouteFiles, t as filePathToUrlPath } from "./fs-router-MewHc5SB.js";
-import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { _ as render404Page, a as detectLocaleFromHeader, c as vercelAdapter, d as netlifyAdapter, f as cloudflareAdapter, g as createServer, h as resolveConfig, i as createLocaleContext, l as staticAdapter, m as defineConfig, o as i18nRouting, p as bunAdapter, r as zeroPlugin, s as resolveAdapter, t as getZeroPluginConfig, u as nodeAdapter, v as createApp } from "./vite-plugin-8TXXFqdP.js";
+import { i as generateRouteModule, o as parseFileRoutes, r as generateMiddlewareModule, s as scanRouteFiles, t as filePathToUrlPath } from "./fs-router-BVY4lTH_.js";
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { readFile, rm, writeFile } from "node:fs/promises";
 
 //#region src/isr.ts
@@ -22,6 +22,10 @@ function createISRHandler(handler, config) {
 	const cache = /* @__PURE__ */ new Map();
 	const revalidating = /* @__PURE__ */ new Set();
 	const revalidateMs = config.revalidate * 1e3;
+	const REVALIDATE_TIMEOUT_MS = Math.max(1, config.revalidateTimeoutMs ?? 3e4);
+	function isCacheable(res) {
+		return res.status >= 200 && res.status < 300 && !res.headers.has("set-cookie");
+	}
 	const maxEntries = Math.max(1, config.maxEntries ?? 1e3);
 	const deriveKey = typeof config.cacheKey === "function" ? (req, _url) => config.cacheKey(req) : (_req, url) => url.pathname;
 	function set(key, entry) {
@@ -46,20 +50,23 @@ function createISRHandler(handler, config) {
 		if (revalidating.has(key)) return;
 		revalidating.add(key);
 		try {
-			const res = await handler(new Request(url.href, {
+			const req = new Request(url.href, {
 				method: "GET",
 				headers: originalReq.headers
-			}));
-			const html = await res.text();
-			const headers = {};
-			res.headers.forEach((v, k) => {
-				headers[k] = v;
-			});
-			set(key, {
-				html,
-				headers,
-				timestamp: Date.now()
 			});
+			const res = await Promise.race([handler(req), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("[Pyreon ISR] revalidation timeout")), REVALIDATE_TIMEOUT_MS))]);
+			if (isCacheable(res)) {
+				const html = await res.text();
+				const headers = {};
+				res.headers.forEach((v, k) => {
+					headers[k] = v;
+				});
+				set(key, {
+					html,
+					headers,
+					timestamp: Date.now()
+				});
+			}
 		} catch {} finally {
 			revalidating.delete(key);
 		}
@@ -88,6 +95,14 @@ function createISRHandler(handler, config) {
 		res.headers.forEach((v, k) => {
 			headers[k] = v;
 		});
+		if (!isCacheable(res)) return new Response(html, {
+			status: res.status,
+			statusText: res.statusText,
+			headers: {
+				...headers,
+				"x-isr-cache": "BYPASS"
+			}
+		});
 		set(key, {
 			html,
 			headers,
@@ -817,6 +832,190 @@ async function addDevBadgeToPng(pngBuffer, size) {
 	}
 }
 
+//#endregion
+//#region src/icons-plugin.ts
+/** Set key → exported component name. `ui` → `UiIcon`, `brand-marks` → `BrandMarksIcon`. */
+function componentNameFromSetKey(key) {
+	const safe = key.split(/[-_/\s]+/).filter(Boolean).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("").replace(/[^A-Za-z0-9_$]/g, "");
+	return `${/^[A-Za-z_$]/.test(safe) ? safe : `Set${safe}`}Icon`;
+}
+/** Filename stem → registry key. `Check-Circle.svg` → `check-circle`. */
+function iconNameFromFile(file) {
+	return basename(file, ".svg").replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+/** Registry key → safe JS import binding. `check-circle` → `checkCircle`. */
+function bindingFromName(name) {
+	const safe = name.replace(/[-/](.)/g, (_, c) => c.toUpperCase()).replace(/[^A-Za-z0-9_$]/g, "_");
+	return /^[A-Za-z_$]/.test(safe) ? safe : `_${safe}`;
+}
+/** List the `*.svg` filenames in `dir` (sorted, stable). Empty if missing. */
+function scanIconDir(dir) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir).filter((f) => f.toLowerCase().endsWith(".svg")).sort();
+}
+/**
+* Render the generated `.tsx` source for a set of svg filenames. Pure —
+* unit-tested directly; the plugin only adds fs + watch around it.
+*/
+function generateIconSetSource(files, opts) {
+	const query = opts.mode === "image" ? "" : "?raw";
+	const seen = /* @__PURE__ */ new Map();
+	const entries = [];
+	for (const file of files) {
+		const key = iconNameFromFile(file);
+		let binding = bindingFromName(key);
+		while (seen.has(binding)) binding = `${binding}_`;
+		seen.set(binding, key);
+		entries.push({
+			key,
+			binding,
+			file
+		});
+	}
+	const header = [
+		"// AUTO-GENERATED by @pyreon/zero iconsPlugin — do not edit.",
+		`// Add / remove .svg files in ${opts.importDir} and this regenerates.`,
+		"/// <reference types=\"vite/client\" />",
+		"import { createNamedIcon } from '@pyreon/zero'"
+	];
+	const imports = entries.map((e) => `import ${e.binding} from '${opts.importDir}/${e.file}${query}'`);
+	const registry = [
+		"const REGISTRY = {",
+		...entries.map((e) => `  ${JSON.stringify(e.key)}: ${e.binding},`),
+		"} as const"
+	];
+	const tail = [
+		"export type IconName = keyof typeof REGISTRY",
+		`export const Icon = createNamedIcon(REGISTRY${opts.mode === "image" ? ", { mode: 'image' }" : ""})`,
+		""
+	];
+	return [
+		...header,
+		"",
+		...imports,
+		"",
+		...registry,
+		"",
+		...tail
+	].join("\n");
+}
+/**
+* Render the generated `.tsx` for the NAMED MULTI-SET form. One file, one
+* `createNamedIcon` import, one strictly-typed component PER set with
+* namespaced types (`UiIcon`/`UiIconName`, `BrandIcon`/`BrandIconName`) so
+* sets never clash. Bindings are per-set-prefixed so two sets sharing a
+* glyph filename don't collide.
+*/
+function generateNamedIconSetsSource(sets) {
+	const header = [
+		"// AUTO-GENERATED by @pyreon/zero iconsPlugin — do not edit.",
+		"// Add / remove .svg files in the configured set folders and this regenerates.",
+		"/// <reference types=\"vite/client\" />",
+		"import { createNamedIcon } from '@pyreon/zero'"
+	];
+	const blocks = [];
+	for (const set of sets) {
+		const component = componentNameFromSetKey(set.key);
+		const typeName = `${component}Name`;
+		const registry = `${component}_REGISTRY`;
+		const query = set.mode === "image" ? "" : "?raw";
+		const seen = /* @__PURE__ */ new Set();
+		const entries = [];
+		for (const file of set.files) {
+			const k = iconNameFromFile(file);
+			let binding = `${bindingFromName(set.key)}_${bindingFromName(k)}`;
+			while (seen.has(binding)) binding = `${binding}_`;
+			seen.add(binding);
+			entries.push({
+				key: k,
+				binding,
+				file
+			});
+		}
+		const imports = entries.map((e) => `import ${e.binding} from '${set.importDir}/${e.file}${query}'`);
+		blocks.push([
+			`// ── set "${set.key}" → <${component} name="…" /> ──`,
+			...imports,
+			`const ${registry} = {`,
+			...entries.map((e) => `  ${JSON.stringify(e.key)}: ${e.binding},`),
+			"} as const",
+			`export type ${typeName} = keyof typeof ${registry}`,
+			`export const ${component} = createNamedIcon(${registry}${set.mode === "image" ? ", { mode: 'image' }" : ""})`
+		].join("\n"));
+	}
+	return [
+		...header,
+		"",
+		blocks.join("\n\n"),
+		""
+	].join("\n");
+}
+function resolveOut(cfg, root) {
+	if (cfg.out) return join(root, cfg.out);
+	if (cfg.dir) {
+		const dir = join(root, cfg.dir);
+		return join(dirname(dir), `${basename(dir)}.gen.tsx`);
+	}
+	return join(root, "src", "icons.gen.tsx");
+}
+/**
+* Vite plugin: scan `dir` for `*.svg`, write a strictly-typed
+* `icons.gen.tsx`, regenerate on add / unlink in dev.
+*/
+function iconsPlugin(cfg) {
+	const hasDir = typeof cfg.dir === "string";
+	const hasSets = !!cfg.sets && Object.keys(cfg.sets).length > 0;
+	if (hasDir === hasSets) throw new Error("[Pyreon] iconsPlugin: provide EXACTLY ONE of `dir` (single set) or `sets` (named multi-set). " + (hasDir ? "Both were given." : "Neither was given (or `sets` is empty)."));
+	let root = process.cwd();
+	const mode = cfg.mode ?? "inline";
+	/** Relative `./…` import dir from the generated file to a scanned folder. */
+	function rel(out, scanned) {
+		const r = relative(dirname(out), scanned).split("\\").join("/");
+		return r.startsWith(".") ? r : `./${r}`;
+	}
+	async function regenerate() {
+		const out = resolveOut(cfg, root);
+		let source;
+		if (hasSets) source = generateNamedIconSetsSource(Object.entries(cfg.sets ?? {}).map(([key, sc]) => {
+			const scanned = join(root, sc.dir);
+			return {
+				key,
+				files: scanIconDir(scanned),
+				mode: sc.mode ?? "inline",
+				importDir: rel(out, scanned)
+			};
+		}));
+		else {
+			const scanned = join(root, cfg.dir);
+			source = generateIconSetSource(scanIconDir(scanned), {
+				mode,
+				importDir: rel(out, scanned)
+			});
+		}
+		if ((existsSync(out) ? await readFile(out, "utf8") : null) !== source) await writeFile(out, source, "utf8");
+	}
+	const watchDirs = () => hasSets ? Object.values(cfg.sets ?? {}).map((s) => join(root, s.dir)) : [join(root, cfg.dir)];
+	return {
+		name: "pyreon:zero-icons",
+		async configResolved(resolved) {
+			root = resolved.root;
+			await regenerate();
+		},
+		async buildStart() {
+			await regenerate();
+		},
+		configureServer(server) {
+			const dirs = watchDirs();
+			for (const d of dirs) server.watcher.add(d);
+			const onChange = (file) => {
+				if (file.toLowerCase().endsWith(".svg") && dirs.some((d) => file.startsWith(d))) regenerate();
+			};
+			server.watcher.on("add", onChange);
+			server.watcher.on("unlink", onChange);
+		}
+	};
+}
+
 //#endregion
 //#region src/seo.ts
 /**
@@ -830,7 +1029,7 @@ async function addDevBadgeToPng(pngBuffer, size) {
 */
 function generateSitemap(routeFiles, config, i18n) {
 	const { origin, exclude = [], changefreq = "weekly", priority = .7 } = config;
-	const clusters = clusterPathsByLocale([...routeFiles.filter((f) => {
+	const paths = routeFiles.filter((f) => {
 		const name = f.split("/").pop()?.replace(/\.\w+$/, "");
 		return name !== "_layout" && name !== "_error" && name !== "_loading";
 	}).map((f) => {
@@ -839,11 +1038,16 @@ function generateSitemap(routeFiles, config, i18n) {
 		path = path.replace(/\([\w-]+\)\//g, "");
 		if (!path.startsWith("/")) path = `/${path}`;
 		return path;
-	}).filter((p) => p !== null).filter((p) => !exclude.some((e) => p.startsWith(e))).map((p) => ({
-		path: p,
-		changefreq,
-		priority
-	})), ...config.additionalPaths ?? []], i18n);
+	}).filter((p) => p !== null).filter((p) => !exclude.some((e) => p.startsWith(e)));
+	const clusters = clusterPathsByLocale((() => {
+		const byPath = /* @__PURE__ */ new Map();
+		for (const e of [...paths.map((p) => ({
+			path: p,
+			changefreq,
+			priority
+		})), ...config.additionalPaths ?? []]) if (!byPath.has(e.path)) byPath.set(e.path, e);
+		return [...byPath.values()];
+	})(), i18n);
 	return `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${i18n != null && i18n.locales.length > 0 ? " xmlns:xhtml=\"http://www.w3.org/1999/xhtml\"" : ""}>
 ${clusters.map((cluster) => renderClusterEntry(cluster, origin, changefreq, priority, i18n)).join("\n")}
@@ -1049,7 +1253,7 @@ function seoPlugin(config = {}) {
 		},
 		async generateBundle(_, _bundle) {
 			if (config.sitemap && !useSsgPaths) {
-				const { scanRouteFiles } = await import("./fs-router-MewHc5SB.js").then((n) => n.n);
+				const { scanRouteFiles } = await import("./fs-router-BVY4lTH_.js").then((n) => n.n);
 				const routesDir = `${process.cwd()}/src/routes`;
 				try {
 					const files = await scanRouteFiles(routesDir);
@@ -1073,7 +1277,7 @@ function seoPlugin(config = {}) {
 		},
 		async closeBundle() {
 			if (!config.sitemap || !useSsgPaths) return;
-			const { scanRouteFiles } = await import("./fs-router-MewHc5SB.js").then((n) => n.n);
+			const { scanRouteFiles } = await import("./fs-router-BVY4lTH_.js").then((n) => n.n);
 			const routesDir = `${process.cwd()}/src/routes`;
 			const manifestPath = join(distDir, "_pyreon-ssg-paths.json");
 			try {
@@ -1111,7 +1315,7 @@ function seoMiddleware(config = {}) {
 	return async (ctx) => {
 		if (ctx.url.pathname === "/robots.txt" && config.robots) return new Response(generateRobots(config.robots), { headers: { "Content-Type": "text/plain" } });
 		if (ctx.url.pathname === "/sitemap.xml" && config.sitemap) try {
-			const { scanRouteFiles } = await import("./fs-router-MewHc5SB.js").then((n) => n.n);
+			const { scanRouteFiles } = await import("./fs-router-BVY4lTH_.js").then((n) => n.n);
 			const sitemap = generateSitemap(await scanRouteFiles(`${process.cwd()}/src/routes`), config.sitemap);
 			return new Response(sitemap, { headers: { "Content-Type": "application/xml" } });
 		} catch {}
@@ -1756,5 +1960,5 @@ function capitalize(s) {
 }
 
 //#endregion
-export { _resetVercelRevalidateHandlerCache, aiPlugin, bunAdapter, cloudflareAdapter, compose, createApp, createISRHandler, createLocaleContext, createServer, zeroPlugin as default, defineConfig, detectLocaleFromHeader, faviconLinks, faviconPlugin, filePathToUrlPath, generateLlmsFullTxt, generateLlmsTxt, generateMiddlewareModule, generateRobots, generateRouteModule, generateSitemap, getContext, getZeroPluginConfig, i18nRouting, inferJsonLd, jsonLd, netlifyAdapter, nodeAdapter, ogImagePath, ogImagePlugin, parseFileRoutes, render404Page, resolveAdapter, resolveConfig, scanRouteFiles, seoMiddleware, seoPlugin, staticAdapter, vercelAdapter, vercelRevalidateHandler };
+export { _resetVercelRevalidateHandlerCache, aiPlugin, bunAdapter, cloudflareAdapter, componentNameFromSetKey, compose, createApp, createISRHandler, createLocaleContext, createServer, zeroPlugin as default, defineConfig, detectLocaleFromHeader, faviconLinks, faviconPlugin, filePathToUrlPath, generateIconSetSource, generateLlmsFullTxt, generateLlmsTxt, generateMiddlewareModule, generateNamedIconSetsSource, generateRobots, generateRouteModule, generateSitemap, getContext, getZeroPluginConfig, i18nRouting, iconNameFromFile, iconsPlugin, inferJsonLd, jsonLd, netlifyAdapter, nodeAdapter, ogImagePath, ogImagePlugin, parseFileRoutes, render404Page, resolveAdapter, resolveConfig, scanIconDir, scanRouteFiles, seoMiddleware, seoPlugin, staticAdapter, vercelAdapter, vercelRevalidateHandler };
 //# sourceMappingURL=server.js.map

package/lib/testing.js

@@ -7,17 +7,19 @@ function matchApiRoute(pattern, path) {
 	const patternParts = pattern.split("/").filter(Boolean);
 	const pathParts = path.split("/").filter(Boolean);
 	const params = {};
+	const isUnsafeParam = (name) => name === "__proto__" || name === "constructor" || name === "prototype";
 	for (let i = 0; i < patternParts.length; i++) {
 		const pp = patternParts[i];
 		if (!pp) continue;
 		if (pp.endsWith("*")) {
 			const paramName = pp.slice(1, -1);
-			params[paramName] = pathParts.slice(i).join("/");
+			if (!isUnsafeParam(paramName)) params[paramName] = pathParts.slice(i).join("/");
 			return params;
 		}
 		if (i >= pathParts.length) return null;
 		if (pp.startsWith(":")) {
-			params[pp.slice(1)] = pathParts[i];
+			const paramName = pp.slice(1);
+			if (!isUnsafeParam(paramName)) params[paramName] = pathParts[i];
 			continue;
 		}
 		if (pp !== pathParts[i]) return null;

package/lib/types/config.d.ts

@@ -25,6 +25,15 @@ interface ISRConfig {
    * space (e.g. `/user/:id` where `:id` is free-form).
    */
   maxEntries?: number;
+  /**
+   * Max wall-time (ms) for a single background revalidation before it is
+   * abandoned. Without a bound, a handler that hangs leaves its key
+   * pinned in the in-flight set forever — every later request for that
+   * key short-circuits the de-dupe guard and the entry can never
+   * recover from stale. Default: `30000` (matches the Suspense
+   * streaming timeout).
+   */
+  revalidateTimeoutMs?: number;
   /**
    * Cache-key derivation function. The default keys cache entries by
    * `url.pathname` ONLY — query strings, cookies, and headers are
@@ -210,6 +219,38 @@ interface ZeroConfig {
       currentPath: string;
       elapsed: number;
     }) => void | Promise<void>;
+    /**
+     * Route-level code splitting in SSG mode. Default `true`.
+     *
+     * When `true` (default), each route file becomes its own dynamic-import
+     * chunk via `lazy(() => import("..."))` — only the route the user
+     * lands on plus its dependencies ship in the initial bundle, the
+     * rest fetch on navigation. Matches the SSR/SPA-mode behaviour zero
+     * has always had; brings parity to SSG.
+     *
+     * When `false`, every route is bundled statically into the main
+     * client chunk (the pre-2026-Q3 SSG behaviour). Useful for tiny
+     * sites (2-5 pages) where the single-chunk-then-instant-nav trade
+     * is preferable — the chunk-fetch cost on navigation is gone, and
+     * the marginal bytes are negligible.
+     *
+     * Crossover point: ~5-8 routes. Below that, single-chunk is fine.
+     * Above that, lazy() shrinks the initial bundle by a meaningful
+     * amount (a 50-route docs site might drop from 200 KB to 80 KB on
+     * first paint).
+     *
+     * Underlying mechanism is the same 3-tier generator zero already
+     * uses for SSR/SPA mode (`fs-router.ts:generateRouteEntry`): lazy
+     * component + inlined metadata when possible, lazy + lazy-thunked
+     * function exports when not, namespace-import fallback for cases
+     * the literal-extractor can't reach.
+     *
+     * @example
+     * ssg: {
+     *   splitChunks: false, // bundle-everything for a 3-page marketing site
+     * }
+     */
+    splitChunks?: boolean;
   };
   /** ISR config — only used when mode is "isr". */
   isr?: ISRConfig;

package/lib/types/image-plugin.d.ts

@@ -17,8 +17,32 @@ declare const cdnProviders: {
   readonly vercel: () => ImageCdnProvider; /** Bunny CDN: `https://{pullZone}.b-cdn.net/...?width=...&quality=...` */
   readonly bunny: (pullZone: string) => ImageCdnProvider;
 };
-/** Placeholder generation strategy. */
-type PlaceholderStrategy = 'blur' | 'dominant-color' | 'none';
+/**
+ * Placeholder generation strategy.
+ *
+ * - `'blur'` — tiny downscaled + blurred WebP data URI (a few hundred bytes).
+ *   The richest preview; faithfully previews the image's content.
+ * - `'color'` — the image's dominant colour as a ~200-byte flat SVG data
+ *   URI. Constant size regardless of source complexity (a blurred WebP
+ *   grows with image content; this doesn't), zero decode, instant paint,
+ *   zero layout shift. For real photos it's far smaller than `'blur'`; for
+ *   trivial/solid sources `'blur'` can be the smaller of the two. Best when
+ *   you want a clean solid backdrop rather than a blurry preview.
+ * - `'none'` — no placeholder (`placeholder: ''`). Skips all placeholder work.
+ *
+ * `'dominant-color'` is a deprecated alias of `'color'` — it was typed from
+ * the plugin's inception but never implemented (the build + dev paths always
+ * fell through to blur). It now resolves to `'color'`; prefer the shorter
+ * name in new code.
+ */
+type PlaceholderStrategy = 'blur' | 'color' | 'dominant-color' | 'none';
+/** Quality per output format (1-100), or a single number applied to all. */
+type ImageQuality = number | Partial<Record<ImageFormat, number>>;
+/**
+ * Normalize the public {@link PlaceholderStrategy} to an internal kind.
+ * @internal Exported for testing.
+ */
+declare function normalizePlaceholder(s: PlaceholderStrategy): 'blur' | 'color' | 'none';
 /** SVG processing options for ?component imports. */
 interface SvgOptions {
   /** Replace fill/stroke with currentColor. Default: true */
@@ -33,11 +57,23 @@ interface ImagePluginConfig {
   widths?: number[];
   /** Output formats. Default: ["webp"] */
   formats?: ImageFormat[];
-  /** Quality for lossy formats (1-100). Default: 80 */
-  quality?: number;
-  /** Blur placeholder size in px. Default: 16 */
+  /**
+   * Quality for lossy formats (1-100). Default: 80.
+   *
+   * Accepts a single number applied to every format, OR a per-format map so
+   * you can tune each codec independently — AVIF tolerates a much lower
+   * number than WebP/JPEG for the same perceived quality:
+   *
+   * ```ts
+   * imagePlugin({ formats: ['avif', 'webp'], quality: { avif: 55, webp: 75 } })
+   * ```
+   *
+   * Formats omitted from the map fall back to 80.
+   */
+  quality?: ImageQuality;
+  /** Blur placeholder size in px (only used by the `'blur'` strategy). Default: 16 */
   placeholderSize?: number;
-  /** Placeholder strategy. Default: "blur" */
+  /** Placeholder strategy. Default: `"blur"`. See {@link PlaceholderStrategy}. */
   placeholder?: PlaceholderStrategy;
   /** File patterns to process. Default: /\.(jpe?g|png|webp|avif)$/i */
   include?: RegExp;
@@ -126,6 +162,28 @@ declare function parseWebPDimensions(buffer: Buffer): {
   width: number;
   height: number;
 };
+/**
+ * Resolve the public {@link ImageQuality} config into a per-format lookup.
+ *
+ * - `undefined` → every format gets {@link DEFAULT_QUALITY}.
+ * - `number` → that number for every format (backward-compatible).
+ * - `Partial<Record<ImageFormat, number>>` → per-format; formats omitted
+ *   from the map fall back to {@link DEFAULT_QUALITY}.
+ *
+ * @internal Exported for testing.
+ */
+declare function resolveQuality(q: ImageQuality | undefined): (format: ImageFormat) => number;
+/**
+ * Dispatch placeholder generation by strategy. Single source of truth used
+ * by every code path (CDN / dev / build) — pre-fix each path open-coded
+ * `generateBlurPlaceholder`, so `'none'` was honoured only in the CDN path
+ * and `'dominant-color'` (typed since the plugin's inception) was never
+ * implemented anywhere — the exact typed-but-unimplemented bug class the
+ * `audit-types` gate exists to catch.
+ *
+ * @internal Exported for testing.
+ */
+declare function generatePlaceholder(input: string, strategy: 'blur' | 'color' | 'none', size: number): Promise<string>;
 //#endregion
-export { FormatSource, ImageCdnProvider, ImageFormat, ImagePluginConfig, PlaceholderStrategy, ProcessedImage, SvgOptions, cdnProviders, imagePlugin, parseJpegDimensions, parseWebPDimensions };
+export { FormatSource, ImageCdnProvider, ImageFormat, ImagePluginConfig, ImageQuality, PlaceholderStrategy, ProcessedImage, SvgOptions, cdnProviders, generatePlaceholder, imagePlugin, normalizePlaceholder, parseJpegDimensions, parseWebPDimensions, resolveQuality };
 //# sourceMappingURL=image-plugin2.d.ts.map

package/lib/types/index.d.ts

@@ -1,9 +1,86 @@
 import * as _$_pyreon_core0 from "@pyreon/core";
-import { ComponentFn, Ref, VNodeChild } from "@pyreon/core";
+import { ComponentFn, Ref, SvgAttributes, VNodeChild } from "@pyreon/core";
 import * as _$_pyreon_reactivity0 from "@pyreon/reactivity";
 import { LoaderContext, NavigationGuard } from "@pyreon/router";
 import { Middleware } from "@pyreon/server";
 
+//#region src/icon.d.ts
+/** An imported SVG component (`import X from './x.svg?component'`). */
+type SvgComponent = (props: SvgAttributes) => VNodeChild;
+/**
+ * Props for {@link Icon}. The standard `<svg>` attribute surface
+ * (`fill`, `class`, `style`, `aria-*`, `onClick`, …) — every one passed
+ * straight through and overriding the container-fill defaults — plus the
+ * two source props.
+ */
+interface IconProps extends SvgAttributes {
+  /**
+   * An imported SVG component, e.g. `import X from './icon.svg?component'`.
+   * Rendered directly with no host wrapper. Recommended over `svg`.
+   */
+  as?: SvgComponent | undefined;
+  /**
+   * A full `<svg>…</svg>` markup string, e.g.
+   * `import x from './icon.svg?raw'`. Inlined inside a single `<span>` host.
+   */
+  svg?: string | undefined;
+}
+/**
+ * Render a loaded SVG — container-filling, theme-aware, props-transparent.
+ *
+ * @example
+ * import Check from './check.svg?component'
+ * <span style="width:2rem"><Icon as={Check} /></span>
+ *
+ * @example
+ * import check from './check.svg?raw'
+ * <span style="width:2rem"><Icon svg={check} /></span>
+ */
+declare function Icon(props: IconProps): VNodeChild;
+/**
+ * Build a reusable icon component from a loaded svg — a markup string OR an
+ * imported SVG component. The result is still just `<Icon>`, so it's
+ * container-sizable + theme-aware with every prop passed through.
+ *
+ * @example
+ * import check from './check.svg?raw'
+ * export const Check = createIcon(check)
+ *
+ * import StarSvg from './star.svg?component'
+ * export const Star = createIcon(StarSvg)
+ *
+ * // …sized + themed entirely by the consumer:
+ * <span style="width:48px"><Check class="text-green-600" /></span>
+ */
+declare function createIcon(source: string | SvgComponent): (props: SvgAttributes) => VNodeChild;
+/** How a named icon set renders each entry. */
+type IconMode = 'inline' | 'image';
+/** Props of a component built by {@link createNamedIcon}. */
+type NamedIconProps<R extends Record<string, string>> = {
+  /** A name from the scanned set — strictly typed to the available files. */name: keyof R & string; /** `<img>` alt text (image mode). Defaults to `""` (decorative). */
+  alt?: string;
+} & Omit<IconProps, 'as' | 'svg'>;
+/**
+ * Build a strictly-typed `<Icon name="…" />` from a name→source registry.
+ *
+ * - `mode: 'inline'` (default) — `source` is raw `<svg>` markup; rendered via
+ *   {@link Icon} so it's `currentColor`-themeable (system icons you recolor).
+ * - `mode: 'image'` — `source` is an asset URL; rendered as `<img>` with NO
+ *   svg mutation, original colors preserved (colorful / brand icons).
+ *
+ * Either way it stays container-filling + props-transparent. Not called by
+ * hand normally — `iconsPlugin` emits the generated file that calls it.
+ *
+ * @example
+ * // icons.gen.tsx (auto-generated):
+ * export const Icon = createNamedIcon({ 'check-circle': '<svg…' })
+ * // app:
+ * <span style="width:2rem"><Icon name="check-circle" /></span>
+ */
+declare function createNamedIcon<R extends Record<string, string>>(registry: R, options?: {
+  mode?: IconMode;
+}): (props: NamedIconProps<R>) => VNodeChild;
+//#endregion
 //#region src/image-plugin.d.ts
 /** Per-format source set for <picture> <source> elements. */
 interface FormatSource {
@@ -443,6 +520,15 @@ interface ISRConfig {
    * space (e.g. `/user/:id` where `:id` is free-form).
    */
   maxEntries?: number;
+  /**
+   * Max wall-time (ms) for a single background revalidation before it is
+   * abandoned. Without a bound, a handler that hangs leaves its key
+   * pinned in the in-flight set forever — every later request for that
+   * key short-circuits the de-dupe guard and the entry can never
+   * recover from stale. Default: `30000` (matches the Suspense
+   * streaming timeout).
+   */
+  revalidateTimeoutMs?: number;
   /**
    * Cache-key derivation function. The default keys cache entries by
    * `url.pathname` ONLY — query strings, cookies, and headers are
@@ -628,6 +714,38 @@ interface ZeroConfig {
       currentPath: string;
       elapsed: number;
     }) => void | Promise<void>;
+    /**
+     * Route-level code splitting in SSG mode. Default `true`.
+     *
+     * When `true` (default), each route file becomes its own dynamic-import
+     * chunk via `lazy(() => import("..."))` — only the route the user
+     * lands on plus its dependencies ship in the initial bundle, the
+     * rest fetch on navigation. Matches the SSR/SPA-mode behaviour zero
+     * has always had; brings parity to SSG.
+     *
+     * When `false`, every route is bundled statically into the main
+     * client chunk (the pre-2026-Q3 SSG behaviour). Useful for tiny
+     * sites (2-5 pages) where the single-chunk-then-instant-nav trade
+     * is preferable — the chunk-fetch cost on navigation is gone, and
+     * the marginal bytes are negligible.
+     *
+     * Crossover point: ~5-8 routes. Below that, single-chunk is fine.
+     * Above that, lazy() shrinks the initial bundle by a meaningful
+     * amount (a 50-route docs site might drop from 200 KB to 80 KB on
+     * first paint).
+     *
+     * Underlying mechanism is the same 3-tier generator zero already
+     * uses for SSR/SPA mode (`fs-router.ts:generateRouteEntry`): lazy
+     * component + inlined metadata when possible, lazy + lazy-thunked
+     * function exports when not, namespace-import fallback for cases
+     * the literal-extractor can't reach.
+     *
+     * @example
+     * ssg: {
+     *   splitChunks: false, // bundle-everything for a 3-page marketing site
+     * }
+     */
+    splitChunks?: boolean;
   };
   /** ISR config — only used when mode is "isr". */
   isr?: ISRConfig;
@@ -1135,5 +1253,5 @@ declare function ogImagePlugin(..._: unknown[]): never;
 /** @deprecated Import from `@pyreon/zero/ai` instead */
 declare function aiPlugin(..._: unknown[]): never;
 //#endregion
-export { type Adapter, type AdapterBuildOptions, type FileRoute, type I18nRoutingConfig, type ISRConfig, Image, type ImageProps, type ImageRenderProps, type ImageSource, Link, type LinkProps, type LinkRenderProps, type LoaderContext, type LocaleContext, Meta, type MetaProps, type RenderMode, type RouteMeta, type RouteMiddlewareEntry, type RouteModule, Script, type ScriptProps, type ScriptRenderProps, type ScriptStrategy, type Theme, ThemeToggle, type UseImageReturn, type UseLinkReturn, type UseScriptReturn, type ZeroConfig, aiPlugin, buildLocalePath, buildMetaTags, createImage, createLink, createScript, createServer, defineConfig, extractLocaleFromPath, faviconPlugin, initTheme, ogImagePlugin, prefetchRoute, resolvedTheme, seoPlugin, setLocale, setSSRThemeDefault, setTheme, theme, themeScript, toggleTheme, useImage, useLink, useLocale, useScript, validateEnv };
+export { type Adapter, type AdapterBuildOptions, type FileRoute, type I18nRoutingConfig, type ISRConfig, Icon, type IconMode, type IconProps, Image, type ImageProps, type ImageRenderProps, type ImageSource, Link, type LinkProps, type LinkRenderProps, type LoaderContext, type LocaleContext, Meta, type MetaProps, type NamedIconProps, type RenderMode, type RouteMeta, type RouteMiddlewareEntry, type RouteModule, Script, type ScriptProps, type ScriptRenderProps, type ScriptStrategy, type SvgComponent, type Theme, ThemeToggle, type UseImageReturn, type UseLinkReturn, type UseScriptReturn, type ZeroConfig, aiPlugin, buildLocalePath, buildMetaTags, createIcon, createImage, createLink, createNamedIcon, createScript, createServer, defineConfig, extractLocaleFromPath, faviconPlugin, initTheme, ogImagePlugin, prefetchRoute, resolvedTheme, seoPlugin, setLocale, setSSRThemeDefault, setTheme, theme, themeScript, toggleTheme, useImage, useLink, useLocale, useScript, validateEnv };
 //# sourceMappingURL=index2.d.ts.map