@pyreon/zero 0.16.0 → 0.19.0

package/lib/types/server.d.ts

@@ -146,6 +146,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
@@ -331,6 +340,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;
@@ -1074,6 +1115,83 @@ declare function faviconLinks(locale: string | undefined, config: FaviconPluginC
   href: string;
 }>;
 //#endregion
+//#region src/icon.d.ts
+/** How a named icon set renders each entry. */
+type IconMode = 'inline' | 'image';
+//#endregion
+//#region src/icons-plugin.d.ts
+/** One named set in the multi-set form. */
+interface IconSetConfig {
+  /** Folder of `*.svg` files to scan for this set. */
+  dir: string;
+  /**
+   * `'inline'` (default — system icons, `currentColor`-themeable) or
+   * `'image'` (colorful / brand icons, rendered `<img>`, no mutation).
+   */
+  mode?: IconMode;
+}
+interface IconsPluginConfig {
+  /**
+   * Single-set form: a folder of `*.svg` files → one `<Icon name="…" />`
+   * with a single `IconName` union. Mutually exclusive with `sets`.
+   */
+  dir?: string;
+  /**
+   * Named multi-set form: `{ ui: { dir }, brand: { dir, mode } }` → one
+   * generated file exporting a strictly-typed component PER set with
+   * NAMESPACED types so they never clash:
+   *   `ui` → `<UiIcon name="…" />` + `type UiIconName`
+   *   `brand` → `<BrandIcon name="…" />` + `type BrandIconName`
+   * Mutually exclusive with `dir`.
+   */
+  sets?: Record<string, IconSetConfig>;
+  /**
+   * Where to write the generated `.tsx`. Single-set default: `icons.gen.tsx`
+   * next to `dir` (e.g. `src/icons` → `src/icons.gen.tsx`). Multi-set
+   * default: `src/icons.gen.tsx` under the project root. Recommend
+   * gitignoring it — it's a build artifact.
+   */
+  out?: string;
+  /** Single-set form only — render mode (`'inline'` default | `'image'`). */
+  mode?: IconMode;
+}
+/** Set key → exported component name. `ui` → `UiIcon`, `brand-marks` → `BrandMarksIcon`. */
+declare function componentNameFromSetKey(key: string): string;
+/** Filename stem → registry key. `Check-Circle.svg` → `check-circle`. */
+declare function iconNameFromFile(file: string): string;
+/** List the `*.svg` filenames in `dir` (sorted, stable). Empty if missing. */
+declare function scanIconDir(dir: string): string[];
+/**
+ * Render the generated `.tsx` source for a set of svg filenames. Pure —
+ * unit-tested directly; the plugin only adds fs + watch around it.
+ */
+declare function generateIconSetSource(files: string[], opts: {
+  mode: IconMode;
+  importDir: string;
+}): string;
+/** One resolved set for the multi-set generator. */
+interface NamedSetInput {
+  /** Set key (`ui`) — becomes `<UiIcon>` + `type UiIconName`. */
+  key: string;
+  files: string[];
+  mode: IconMode;
+  /** Relative import dir from the generated file to this set's folder. */
+  importDir: string;
+}
+/**
+ * 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.
+ */
+declare function generateNamedIconSetsSource(sets: NamedSetInput[]): string;
+/**
+ * Vite plugin: scan `dir` for `*.svg`, write a strictly-typed
+ * `icons.gen.tsx`, regenerate on add / unlink in dev.
+ */
+declare function iconsPlugin(cfg: IconsPluginConfig): Plugin;
+//#endregion
 //#region src/seo.d.ts
 interface SitemapConfig {
   /** Base URL of the site (required). e.g. "https://example.com" */
@@ -1467,5 +1585,5 @@ declare function inferJsonLd(options: InferJsonLdOptions): Record<string, unknow
  */
 declare function aiPlugin(config: AiPluginConfig): Plugin;
 //#endregion
-export { type AiPluginConfig, type CreateAppOptions, type CreateServerOptions, type FaviconLocaleConfig, type FaviconPluginConfig, type GenerateRouteModuleOptions, type GetStaticPaths, type InferJsonLdOptions, type OgImageLayer, type OgImagePluginConfig, type OgImageTemplate, type RobotsConfig, type SeoPluginConfig, type SitemapConfig, type VercelRevalidateHandlerOptions, _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 { type AiPluginConfig, type CreateAppOptions, type CreateServerOptions, type FaviconLocaleConfig, type FaviconPluginConfig, type GenerateRouteModuleOptions, type GetStaticPaths, type IconSetConfig, type IconsPluginConfig, type InferJsonLdOptions, type NamedSetInput, type OgImageLayer, type OgImagePluginConfig, type OgImageTemplate, type RobotsConfig, type SeoPluginConfig, type SitemapConfig, type VercelRevalidateHandlerOptions, _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=server2.d.ts.map

package/lib/{vite-plugin-xjWZwudX.js → vite-plugin-8TXXFqdP.js}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-CjeV3_4I.js";
-import { i as matchApiRoute, n as createApiMiddleware, r as generateApiRouteModule } from "./api-routes-Ci0kVmM4.js";
-import { a as generateRouteModuleFromRoutes, c as scanRouteFilesWithExports, o as parseFileRoutes, r as generateMiddlewareModule, s as scanRouteFiles } from "./fs-router-MewHc5SB.js";
+import { i as matchApiRoute, n as createApiMiddleware, r as generateApiRouteModule } from "./api-routes-CQiOi3q5.js";
+import { a as generateRouteModuleFromRoutes, c as scanRouteFilesWithExports, o as parseFileRoutes, r as generateMiddlewareModule, s as scanRouteFiles } from "./fs-router-BVY4lTH_.js";
 import { Fragment, createContext, h } from "@pyreon/core";
 import { HeadProvider } from "@pyreon/head";
 import { RouterProvider, RouterView, createRouter, getRedirectInfo } from "@pyreon/router";
 import { createHandler } from "@pyreon/server";
 import { renderToString } from "@pyreon/runtime-server";
 import { existsSync, readdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { mkdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { signal } from "@pyreon/reactivity";
@@ -1450,9 +1450,12 @@ const SSR_ENTRY_FILENAME = "__pyreon-zero-ssg-entry.js";
 function expandUrlPattern(pattern, params) {
 	return pattern.split("/").map((seg) => {
 		if (!seg.startsWith(":")) return seg;
-		const name = seg.endsWith("*") ? seg.slice(1, -1) : seg.slice(1);
+		const isCatchAll = seg.endsWith("*");
+		const name = isCatchAll ? seg.slice(1, -1) : seg.slice(1);
 		const value = params[name];
 		if (value === void 0 || value === "") throw new Error(`[zero:ssg] getStaticPaths for "${pattern}" returned params without "${name}"`);
+		const segs = isCatchAll ? value.split("/") : [value];
+		if (!isCatchAll && value.includes("/") || segs.some((s) => s === "." || s === "..")) throw new Error(`[zero:ssg] getStaticPaths for "${pattern}" produced an unsafe "${name}" value (${JSON.stringify(value)}): a ${isCatchAll ? "catch-all" : "dynamic"} segment must not contain path-traversal ("." / "..")${isCatchAll ? "" : " or \"/\""}.`);
 		return value;
 	}).join("/");
 }
@@ -1493,7 +1496,8 @@ async function autoDetectStaticPaths(routesDir, registry, errors = [], i18n) {
 			});
 		}
 	}
-	return out.length > 0 ? out : ["/"];
+	const deduped = [...new Set(out)];
+	return deduped.length > 0 ? deduped : ["/"];
 }
 async function resolvePaths(config, routesDir, registry, errors = []) {
 	const explicit = config.ssg?.paths;
@@ -1615,6 +1619,20 @@ function resolveOutputPath(distDir, path) {
 	return join(distDir, path, "index.html");
 }
 /**
+* Path-containment check that is SEPARATOR-TERMINATED. A bare
+* `resolve(filePath).startsWith(resolve(distDir))` is a string-prefix
+* test, not a path test: with distDir `/app/dist`, a traversed filePath
+* resolving to the SIBLING `/app/dist-evil/x` passes
+* `'/app/dist-evil/x'.startsWith('/app/dist')` → true and the build
+* writes outside the intended output root. `path` derives from caller
+* route params (CMS slugs via `getStaticPaths`), so this is reachable.
+*/
+function isInsideDist(distDir, filePath) {
+	const root = resolve(distDir);
+	const target = resolve(filePath);
+	return target === root || target.startsWith(root + sep);
+}
+/**
 * Render Netlify / Cloudflare Pages `_redirects` file content. One line
 * per redirect, format: `<from> <to> <status>`. Both platforms parse this
 * format identically; Vercel ignores it (use the JSON below). Lines with
@@ -1925,8 +1943,7 @@ function ssgPlugin(userConfig = {}) {
 						});
 						if (config.ssg?.redirectsAsHtml === "meta-refresh") {
 							const filePath = resolveOutputPath(distDir, p);
-							const resolvedOut = resolve(distDir);
-							if (!resolve(filePath).startsWith(resolvedOut)) {
+							if (!isInsideDist(distDir, filePath)) {
 								errors.push({
 									path: p,
 									error: /* @__PURE__ */ new Error(`Path traversal detected: "${p}"`)
@@ -1940,8 +1957,7 @@ function ssgPlugin(userConfig = {}) {
 					}
 					const html = injectIntoTemplate(template, result);
 					const filePath = resolveOutputPath(distDir, p);
-					const resolvedOut = resolve(distDir);
-					if (!resolve(filePath).startsWith(resolvedOut)) {
+					if (!isInsideDist(distDir, filePath)) {
 						errors.push({
 							path: p,
 							error: /* @__PURE__ */ new Error(`Path traversal detected: "${p}"`)
@@ -1963,8 +1979,7 @@ function ssgPlugin(userConfig = {}) {
 						const fallbackHtml = await config.ssg.onPathError(p, error);
 						if (typeof fallbackHtml === "string") {
 							const filePath = resolveOutputPath(distDir, p);
-							const resolvedOut = resolve(distDir);
-							if (!resolve(filePath).startsWith(resolvedOut)) {
+							if (!isInsideDist(distDir, filePath)) {
 								errors.push({
 									path: p,
 									error: /* @__PURE__ */ new Error(`Path traversal detected: "${p}"`)
@@ -2073,6 +2088,7 @@ function ssgPlugin(userConfig = {}) {
 //#endregion
 //#region src/vite-plugin.ts
 var vite_plugin_exports = /* @__PURE__ */ __exportAll({
+	argvHasPortFlag: () => argvHasPortFlag,
 	getZeroPluginConfig: () => getZeroPluginConfig,
 	zeroPlugin: () => zeroPlugin
 });
@@ -2129,6 +2145,25 @@ function getZeroPluginConfig(plugin) {
 	return zeroPluginConfigMap.get(plugin);
 }
 /**
+* Detects `--port` / `--port=N` / `-p N` / `-p=N` in `process.argv`.
+* Used by the plugin's `config()` hook to decide whether to apply the
+* default port — when the CLI was invoked with `--port`, the plugin
+* must skip its default so the CLI flag wins (see the comment at the
+* port-handling block in `zeroPlugin()` for the full precedence model).
+*
+* Exported for testing only (the plugin uses it internally).
+*
+* @internal
+*/
+function argvHasPortFlag(argv = process.argv) {
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--port" || a === "-p") return true;
+		if (a !== void 0 && (a.startsWith("--port=") || a.startsWith("-p="))) return true;
+	}
+	return false;
+}
+/**
 * Zero Vite plugin — adds file-based routing and zero-config conventions
 * on top of @pyreon/vite-plugin.
 *
@@ -2160,7 +2195,9 @@ function zeroPlugin(userConfig = {}) {
 		async load(id) {
 			if (id === RESOLVED_VIRTUAL_ROUTES_ID) try {
 				const baseRoutes = await scanRouteFilesWithExports(routesDir, config.mode);
-				return generateRouteModuleFromRoutes(config.i18n ? expandRoutesForLocales(baseRoutes, config.i18n) : baseRoutes, routesDir, { staticImports: config.mode === "ssg" });
+				const routes = config.i18n ? expandRoutesForLocales(baseRoutes, config.i18n) : baseRoutes;
+				const ssgSplitDisabled = config.mode === "ssg" && config.ssg?.splitChunks === false;
+				return generateRouteModuleFromRoutes(routes, routesDir, { staticImports: ssgSplitDisabled });
 			} catch (_err) {
 				return `export const routes = []`;
 			}
@@ -2289,7 +2326,7 @@ function zeroPlugin(userConfig = {}) {
 					...runtimeServerAlias ? { alias: { "@pyreon/runtime-server": runtimeServerAlias } } : {}
 				} },
 				optimizeDeps: { exclude: pyreonExclude },
-				...userConfig.port !== void 0 ? { server: { port: config.port } } : {},
+				...userConfig.port === void 0 && argvHasPortFlag() ? {} : { server: { port: config.port } },
 				base: config.base,
 				define: {
 					__ZERO_MODE__: JSON.stringify(config.mode),
@@ -2451,4 +2488,4 @@ function flattenRoutePatterns(routes) {
 
 //#endregion
 export { render404Page as _, detectLocaleFromHeader as a, vercelAdapter as c, netlifyAdapter as d, cloudflareAdapter as f, createServer as g, resolveConfig as h, createLocaleContext as i, staticAdapter as l, defineConfig as m, vite_plugin_exports as n, i18nRouting as o, bunAdapter as p, zeroPlugin as r, resolveAdapter as s, getZeroPluginConfig as t, nodeAdapter as u, createApp as v };
-//# sourceMappingURL=vite-plugin-xjWZwudX.js.map
+//# sourceMappingURL=vite-plugin-8TXXFqdP.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/zero",
-  "version": "0.16.0",
+  "version": "0.19.0",
   "description": "Pyreon Zero — zero-config full-stack framework powered by Pyreon and Vite",
   "license": "MIT",
   "author": "Vit Bokisch",
@@ -168,15 +168,15 @@
     "lint": "oxlint ."
   },
   "dependencies": {
-    "@pyreon/core": "^0.16.0",
-    "@pyreon/head": "^0.16.0",
-    "@pyreon/meta": "^0.16.0",
-    "@pyreon/reactivity": "^0.16.0",
-    "@pyreon/router": "^0.16.0",
-    "@pyreon/runtime-dom": "^0.16.0",
-    "@pyreon/runtime-server": "^0.16.0",
-    "@pyreon/server": "^0.16.0",
-    "@pyreon/vite-plugin": "^0.16.0",
+    "@pyreon/core": "^0.19.0",
+    "@pyreon/head": "^0.19.0",
+    "@pyreon/meta": "^0.19.0",
+    "@pyreon/reactivity": "^0.19.0",
+    "@pyreon/router": "^0.19.0",
+    "@pyreon/runtime-dom": "^0.19.0",
+    "@pyreon/runtime-server": "^0.19.0",
+    "@pyreon/server": "^0.19.0",
+    "@pyreon/vite-plugin": "^0.19.0",
     "vite": "^8.0.0"
   },
   "devDependencies": {

package/src/api-routes.ts

@@ -52,6 +52,15 @@ export function matchApiRoute(pattern: string, path: string): Record<string, str
   const pathParts = path.split('/').filter(Boolean)
   const params: Record<string, string> = {}
 
+  // A param NAME comes from the route pattern (file-based route like
+  // `[__proto__].ts`) — developer-controlled, so this is defense-in-depth
+  // rather than an attacker vector, but assigning `params['__proto__'] =
+  // …` still mutates the result object's prototype instead of setting a
+  // param. Skip the dangerous names (consistent with reconcile / i18n
+  // deepMerge guards) so a stray route name can't pollute.
+  const isUnsafeParam = (name: string): boolean =>
+    name === '__proto__' || name === 'constructor' || name === 'prototype'
+
   for (let i = 0; i < patternParts.length; i++) {
     const pp = patternParts[i]
     if (!pp) continue
@@ -59,7 +68,7 @@ export function matchApiRoute(pattern: string, path: string): Record<string, str
     // Catch-all: :param*
     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
     }
 
@@ -68,7 +77,8 @@ export function matchApiRoute(pattern: string, path: string): Record<string, str
 
     // Dynamic segment: :param
     if (pp.startsWith(':')) {
-      params[pp.slice(1)] = pathParts[i]!
+      const paramName = pp.slice(1)
+      if (!isUnsafeParam(paramName)) params[paramName] = pathParts[i]!
       continue
     }
 

package/src/fs-router.ts

@@ -1100,7 +1100,13 @@ export function generateRouteModuleFromRoutes(
     const opts: string[] = []
     if (loadingName) opts.push(`loading: ${loadingName}`)
     if (errorName) opts.push(`error: ${errorName}`)
-    const optsStr = opts.length > 0 ? `, { ${opts.join(', ')} }` : ''
+    // `hmrId` lets `@pyreon/router`'s dev HMR coordinator map a
+    // hot-updated module back to its route record(s) for an in-place
+    // component swap (no page reload, signals preserved). Inert in
+    // production — the coordinator is only registered in a dev browser,
+    // so `_hmrId` is dead metadata once built.
+    opts.push(`hmrId: ${JSON.stringify(fullPath)}`)
+    const optsStr = `, { ${opts.join(', ')} }`
     imports.push(`const ${name} = lazy(() => import("${fullPath}")${optsStr})`)
     return name
   }

package/src/icon.tsx

@@ -0,0 +1,182 @@
+import type { PyreonHTMLAttributes, SvgAttributes, VNodeChild } from '@pyreon/core'
+import { splitProps } from '@pyreon/core'
+
+// ─── Icon ───────────────────────────────────────────────────────────────────
+//
+// Renders a FULL, already-complete SVG that you loaded — it does NOT
+// synthesize its own <svg> wrapper around hand-authored <path> children.
+// You load an svg (it contains the <svg> root itself); Icon renders it and
+// makes it container-sizable + theme-aware.
+//
+// Two ways to hand it the loaded svg (you chose: support both):
+//   • `as`  — an imported SVG *component* (`import X from './x.svg?component'`).
+//             Rendered directly — NO host wrapper. Recommended form: it's a
+//             real <svg> element, so container-fill is reliable.
+//   • `svg` — the raw `<svg>…</svg>` *markup string*
+//             (`import x from './x.svg?raw'`). Inlined via a single `<span>`
+//             host (a markup string can't mount without a parent element —
+//             this one host is unavoidable for the string form).
+//
+// Either way:
+//   • Container-filling defaults (`fill="currentColor"`,
+//     `display:block;width:100%;height:100%`) — every consumer prop spreads
+//     through and OVERRIDES them (`style`, `class`, `fill`, `aria-*`, …).
+//   • No fixed size → it fills its container; the consumer's wrapper
+//     (`<span style="width:2rem"><Icon/></span>`, a flex/grid cell,
+//     `font-size`) controls the size.
+//   • `fill="currentColor"` → CSS `color` themes it (dark mode for free).
+//
+// Two layers (mirrors createLink/Link, createImage/Image):
+//   1. createIcon(source) — factory: one component per loaded glyph
+//   2. Icon               — generic shell for a one-off loaded svg
+//
+// There is intentionally no `useIcon` — an icon has no composable behaviour
+// (no async, no state, no router). A hook layer would be surface for its
+// own sake.
+
+const FILL_STYLE = 'display:block;width:100%;height:100%'
+
+/** An imported SVG component (`import X from './x.svg?component'`). */
+export 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.
+ */
+export 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>
+ */
+export function Icon(props: IconProps): VNodeChild {
+  const [own, rest] = splitProps(props, ['as', 'svg'])
+
+  // Component form — render the imported SVG directly, no host wrapper.
+  // Defaults first so consumer `rest` (spread) overrides them; JSX spread
+  // is reactivity-safe (compiler wraps it with `_wrapSpread`).
+  if (own.as) {
+    const As = own.as
+    return <As fill="currentColor" style={FILL_STYLE} {...rest} />
+  }
+
+  // Raw-markup form — the string already contains its own <svg>, so we
+  // inline it via a single <span> host. `dangerouslySetInnerHTML` last so
+  // it can't be clobbered by a stray spread key.
+  if (own.svg) {
+    // svg-only props (`fill`, `viewBox`, …) are inapplicable to the host
+    // span AND can't reach the opaque inlined markup — only host-level
+    // attrs (`class`, `style`, `aria-*`, events) are meaningfully
+    // forwardable here. Narrow the spread to the host's real surface.
+    const hostRest = rest as unknown as PyreonHTMLAttributes<HTMLElement>
+    return (
+      <span
+        style={FILL_STYLE}
+        {...hostRest}
+        dangerouslySetInnerHTML={{ __html: own.svg }}
+      />
+    )
+  }
+
+  return null
+}
+
+/**
+ * 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>
+ */
+export function createIcon(
+  source: string | SvgComponent,
+): (props: SvgAttributes) => VNodeChild {
+  return (props: SvgAttributes) =>
+    typeof source === 'string' ? (
+      <Icon svg={source} {...props} />
+    ) : (
+      <Icon as={source} {...props} />
+    )
+}
+
+// ─── createNamedIcon — typed icon-set runtime ────────────────────────────────
+//
+// The runtime half of `iconsPlugin`. The plugin scans a folder and writes a
+// generated file that calls this with a registry literal; `keyof typeof
+// REGISTRY` makes `name` a strict union (autocompletes, rejects typos) and
+// gives real go-to-definition — zero per-app wiring.
+
+/** How a named icon set renders each entry. */
+export type IconMode = 'inline' | 'image'
+
+/** Props of a component built by {@link createNamedIcon}. */
+export 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>
+ */
+export function createNamedIcon<R extends Record<string, string>>(
+  registry: R,
+  options: { mode?: IconMode } = {},
+): (props: NamedIconProps<R>) => VNodeChild {
+  const mode = options.mode ?? 'inline'
+  return (props: NamedIconProps<R>) => {
+    const [own, rest] = splitProps(props, ['name', 'alt'])
+    const source = registry[own.name]
+    if (mode === 'image') {
+      // svg-only props can't apply to an <img>; only host attrs forward.
+      const hostRest = rest as unknown as PyreonHTMLAttributes<HTMLImageElement>
+      return (
+        <img src={source} alt={own.alt ?? ''} style={FILL_STYLE} {...hostRest} />
+      )
+    }
+    return <Icon svg={source} {...rest} />
+  }
+}