@pyreon/zero 0.18.0 → 0.20.0

package/src/image-plugin.ts

@@ -58,8 +58,36 @@ export const cdnProviders = {
     `https://${pullZone}.b-cdn.net/${src}?width=${width}&quality=${quality}`,
 } as const
 
-/** Placeholder generation strategy. */
-export 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.
+ */
+export type PlaceholderStrategy = 'blur' | 'color' | 'dominant-color' | 'none'
+
+/** Quality per output format (1-100), or a single number applied to all. */
+export type ImageQuality = number | Partial<Record<ImageFormat, number>>
+
+/**
+ * Normalize the public {@link PlaceholderStrategy} to an internal kind.
+ * @internal Exported for testing.
+ */
+export function normalizePlaceholder(s: PlaceholderStrategy): 'blur' | 'color' | 'none' {
+  return s === 'dominant-color' ? 'color' : s
+}
 
 /** SVG processing options for ?component imports. */
 export interface SvgOptions {
@@ -76,11 +104,23 @@ export 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
@@ -163,9 +203,9 @@ const IMAGE_EXT_RE = /\.(jpe?g|png|webp|avif)$/i
 export function imagePlugin(config: ImagePluginConfig = {}): Plugin {
   const defaultWidths = config.widths ?? [640, 1024, 1920]
   const defaultFormats = config.formats ?? ['webp']
-  const quality = config.quality ?? 80
+  const qualityFor = resolveQuality(config.quality)
   const placeholderSize = config.placeholderSize ?? 16
-  const placeholderStrategy = config.placeholder ?? 'blur'
+  const placeholderStrategy = normalizePlaceholder(config.placeholder ?? 'blur')
   const outSubDir = config.outDir ?? 'assets/img'
   const include = config.include ?? IMAGE_EXT_RE
   const cdn = config.cdn
@@ -189,23 +229,45 @@ export function imagePlugin(config: ImagePluginConfig = {}): Plugin {
       isBuild = resolvedConfig.command === 'build'
     },
 
-    async resolveId(id) {
-      // SVG as component: import Logo from './logo.svg?component'
-      if (svgOpts && id.includes('?component') && id.split('?')[0]!.endsWith('.svg')) {
-        return `\0virtual:zero-svg:${id}`
-      }
-      // Handle ?optimize query on image imports
-      if (id.includes('?optimize') && include.test(id.split('?')[0]!)) {
-        return `\0virtual:zero-image:${id}`
-      }
-      return null
+    async resolveId(id, importer) {
+      const isSvgComponent =
+        svgOpts && id.includes('?component') && id.split('?')[0]!.endsWith('.svg')
+      const isOptimize =
+        id.includes('?optimize') && include.test(id.split('?')[0]!)
+      if (!isSvgComponent && !isOptimize) return null
+
+      // Resolve the bare specifier to an ABSOLUTE fs path the way Vite
+      // resolves `?url` — importer-relative + alias-aware. The old code
+      // embedded the raw unresolved id, so `load()` had to guess: a
+      // relative `./img.png?optimize` resolved against cwd (≠ the
+      // importer's dir → ENOENT), and an aliased `~/x.png?optimize`
+      // arrived already-absolute and got `join(root,'public',…)`-doubled.
+      // `this.resolve` (skipSelf so we don't recurse into our own
+      // resolveId) handles relative + aliases + extensions. A public-dir
+      // web path (`/foo.png?optimize`) doesn't resolve to a module →
+      // null → keep the original id so load()'s public/ fallback applies.
+      const qIdx = id.indexOf('?')
+      const bare = qIdx === -1 ? id : id.slice(0, qIdx)
+      const query = qIdx === -1 ? '' : id.slice(qIdx)
+      const resolved = await this.resolve(bare, importer, { skipSelf: true })
+      const carried = resolved ? `${resolved.id}${query}` : id
+
+      if (isSvgComponent) return `\0virtual:zero-svg:${carried}`
+      return `\0virtual:zero-image:${carried}`
     },
 
     async load(id) {
       // SVG component loading
       if (id.startsWith('\0virtual:zero-svg:')) {
         const rawPath = id.replace('\0virtual:zero-svg:', '').split('?')[0] ?? id
-        const absPath = rawPath.startsWith('/') ? join(root, rawPath) : rawPath
+        // resolveId now carries an absolute fs path for relative/aliased
+        // imports → trust it if it exists. Only a public-dir web path
+        // (`/logo.svg`, unresolved) falls back to root-join.
+        const absPath = existsSync(rawPath)
+          ? rawPath
+          : rawPath.startsWith('/')
+            ? join(root, rawPath)
+            : rawPath
         if (!existsSync(absPath)) return null
 
         let svg = await readFile(absPath, 'utf-8')
@@ -247,13 +309,27 @@ export default function SvgComponent(props) {
       if (!id.startsWith('\0virtual:zero-image:')) return null
 
       const rawPath = id.replace('\0virtual:zero-image:', '').split('?')[0] ?? id
-      const absPath = rawPath.startsWith('/') ? join(root, 'public', rawPath) : rawPath
+      // resolveId now carries an absolute fs path for relative/aliased
+      // imports (the `./img.png?optimize` and `~/img.png?optimize` cases
+      // that used to ENOENT / double-`public`). Trust an existing
+      // absolute path; only an unresolved public-dir web path
+      // (`/foo.png?optimize`) falls back to `<root>/public/…`.
+      const absPath = existsSync(rawPath)
+        ? rawPath
+        : rawPath.startsWith('/')
+          ? join(root, 'public', rawPath)
+          : rawPath
 
       // CDN mode — rewrite URLs, no local processing
       if (cdn) {
         const metadata = await getImageMetadata(absPath)
         const sources = defaultWidths.map((w) => ({
-          src: cdn(rawPath, { width: w, quality, format: defaultFormats[0]! }) ?? rawPath,
+          src:
+            cdn(rawPath, {
+              width: w,
+              quality: qualityFor(defaultFormats[0]!),
+              format: defaultFormats[0]!,
+            }) ?? rawPath,
           width: w,
           format: defaultFormats[0]! as string,
         }))
@@ -263,12 +339,14 @@ export default function SvgComponent(props) {
           srcset,
           width: metadata.width,
           height: metadata.height,
-          placeholder: placeholderStrategy === 'none' ? ''
-            : await generateBlurPlaceholder(absPath, placeholderSize),
+          placeholder: await generatePlaceholder(absPath, placeholderStrategy, placeholderSize),
           formats: defaultFormats.map((fmt) => ({
             type: `image/${fmt}`,
             srcset: defaultWidths
-              .map((w) => `${cdn(rawPath, { width: w, quality, format: fmt }) ?? rawPath} ${w}w`)
+              .map(
+                (w) =>
+                  `${cdn(rawPath, { width: w, quality: qualityFor(fmt), format: fmt }) ?? rawPath} ${w}w`,
+              )
               .join(', '),
           })),
           sources,
@@ -277,14 +355,20 @@ export default function SvgComponent(props) {
       }
 
       if (!isBuild) {
-        const result = await loadDevImage(absPath, rawPath, placeholderSize)
+        const result = await loadDevImage(
+          absPath,
+          rawPath,
+          placeholderStrategy,
+          placeholderSize,
+        )
         return `export default ${JSON.stringify(result)}`
       }
 
       const processed = await processImage(absPath, {
         widths: defaultWidths,
         formats: defaultFormats,
-        quality,
+        qualityFor,
+        placeholderStrategy,
         placeholderSize,
         outSubDir,
         outDir: join(root, outDir),
@@ -301,6 +385,7 @@ export default function SvgComponent(props) {
 async function loadDevImage(
   absPath: string,
   rawPath: string,
+  strategy: 'blur' | 'color' | 'none',
   placeholderSize: number,
 ): Promise<ProcessedImage> {
   const metadata = await getImageMetadata(absPath)
@@ -311,7 +396,7 @@ async function loadDevImage(
     srcset: '',
     width: metadata.width,
     height: metadata.height,
-    placeholder: await generateBlurPlaceholder(absPath, placeholderSize),
+    placeholder: await generatePlaceholder(absPath, strategy, placeholderSize),
     formats: [],
     sources: [{ src: publicPath, width: metadata.width, format: 'original' }],
   }
@@ -357,7 +442,8 @@ function rebuildFormatSrcsets(processed: ProcessedImage, fallbackPath: string) {
 interface ProcessOptions {
   widths: number[]
   formats: ImageFormat[]
-  quality: number
+  qualityFor: (format: ImageFormat) => number
+  placeholderStrategy: 'blur' | 'color' | 'none'
   placeholderSize: number
   outSubDir: string
   outDir: string
@@ -383,7 +469,7 @@ async function processImage(absPath: string, opts: ProcessOptions): Promise<Proc
       const outName = `${name}-${width}.${format}`
       const outPath = join(processedDir, outName)
 
-      await resizeImage(absPath, outPath, width, format, opts.quality)
+      await resizeImage(absPath, outPath, width, format, opts.qualityFor(format))
       sources.push({ src: outPath, width, format })
     }
   }
@@ -408,8 +494,14 @@ async function processImage(absPath: string, opts: ProcessOptions): Promise<Proc
   const fallbackFormat = formats[formats.length - 1]
   const fallbackSources = formatGroups.get([...formatGroups.keys()].pop()!)!
 
-  // Generate blur placeholder
-  const placeholder = await generateBlurPlaceholder(absPath, opts.placeholderSize)
+  // Generate the placeholder per the configured strategy. Pre-fix this
+  // hard-coded `generateBlurPlaceholder`, so `placeholder: 'none'` was
+  // ignored in build mode and `'dominant-color'` never resolved anywhere.
+  const placeholder = await generatePlaceholder(
+    absPath,
+    opts.placeholderStrategy,
+    opts.placeholderSize,
+  )
 
   return {
     src: fallbackSources[fallbackSources.length - 1]?.src ?? absPath,
@@ -564,6 +656,82 @@ async function generateBlurPlaceholder(input: string, size: number): Promise<str
     return `data:image/webp;base64,${buffer.toString('base64')}`
   } catch {
     // sharp not available — return a transparent placeholder
-    return "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='1' height='1'%3E%3C/svg%3E"
+    return TRANSPARENT_PLACEHOLDER
+  }
+}
+
+/** 1×1 transparent SVG — the no-sharp fallback for every strategy. */
+const TRANSPARENT_PLACEHOLDER =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='1' height='1'%3E%3C/svg%3E"
+
+const DEFAULT_QUALITY = 80
+
+/**
+ * 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.
+ */
+export function resolveQuality(
+  q: ImageQuality | undefined,
+): (format: ImageFormat) => number {
+  if (q === undefined) return () => DEFAULT_QUALITY
+  if (typeof q === 'number') return () => q
+  return (format) => q[format] ?? DEFAULT_QUALITY
+}
+
+/**
+ * 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.
+ */
+export async function generatePlaceholder(
+  input: string,
+  strategy: 'blur' | 'color' | 'none',
+  size: number,
+): Promise<string> {
+  if (strategy === 'none') return ''
+  if (strategy === 'color') return generateColorPlaceholder(input)
+  return generateBlurPlaceholder(input, size)
+}
+
+/**
+ * Generate a dominant-colour placeholder: a ~200-byte flat-fill SVG data URI.
+ *
+ * Uses sharp's `.stats()` `dominant` swatch — a histogram-binned colour,
+ * not a naive average (averaging a photo trends muddy grey). Note the
+ * swatch is approximate by design: a pure-red source resolves to ~#f80808,
+ * not #ff0000. The SVG is a constant ~200 bytes regardless of source
+ * complexity and needs zero image decode, at the cost of showing a solid
+ * colour instead of a blurry preview of the content.
+ */
+async function generateColorPlaceholder(input: string): Promise<string> {
+  try {
+    const sharp = await import('sharp').then((m) => m.default ?? m)
+    const { dominant } = await sharp(input).stats()
+    const hex =
+      '#' +
+      [dominant.r, dominant.g, dominant.b]
+        .map((c) => Math.max(0, Math.min(255, c)).toString(16).padStart(2, '0'))
+        .join('')
+    // Inline SVG with the colour as a single rect — URL-encoded so it needs
+    // no base64 inflation. preserveAspectRatio + viewBox let it scale to any
+    // container the way an <img> placeholder is expected to.
+    const svg =
+      `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1 1' preserveAspectRatio='none'>` +
+      `<rect width='1' height='1' fill='${hex}'/></svg>`
+    return `data:image/svg+xml,${encodeURIComponent(svg)}`
+  } catch {
+    // sharp not available — transparent fallback (same as the blur path).
+    return TRANSPARENT_PLACEHOLDER
   }
 }

package/src/index.ts

@@ -13,6 +13,8 @@
 
 // ─── Components (browser-safe) ──────────────────────────────────────────────
 
+export type { IconMode, IconProps, NamedIconProps, SvgComponent } from "./icon";
+export { createIcon, createNamedIcon, Icon } from "./icon";
 export type { ImageProps, ImageRenderProps, ImageSource, UseImageReturn } from "./image";
 export { createImage, Image, useImage } from "./image";
 export type { LinkProps, LinkRenderProps, UseLinkReturn } from "./link";

package/src/isr.ts

@@ -28,6 +28,25 @@ export function createISRHandler(
   const cache = new Map<string, CacheEntry>()
   const revalidating = new Set<string>()
   const revalidateMs = config.revalidate * 1000
+  // Bounded background-revalidation timeout. Without it, a handler that
+  // hangs forever leaves its key permanently in `revalidating` (the
+  // `finally` that clears it never runs), so EVERY later request for
+  // that key short-circuits the `revalidating.has(key)` guard and the
+  // entry stays stale for the rest of the process lifetime — it can
+  // never recover. 30s default matches the Suspense streaming timeout;
+  // overridable via ISRConfig.revalidateTimeoutMs.
+  const REVALIDATE_TIMEOUT_MS = Math.max(1, config.revalidateTimeoutMs ?? 30_000)
+
+  // Only 2xx, cookie-free responses may be cached. Caching a transient
+  // 5xx/3xx/404 and replaying it as a 200 for the whole revalidate
+  // window is a self-inflicted outage / cache-poisoning bug. Caching a
+  // `Set-Cookie` response and replaying it to every visitor leaks one
+  // user's session/CSRF cookie cross-user — not covered by the
+  // documented "ISR-without-cacheKey is for non-personalized pages"
+  // caveat (that caveat is about key variance, not header stripping).
+  function isCacheable(res: Response): boolean {
+    return res.status >= 200 && res.status < 300 && !res.headers.has('set-cookie')
+  }
   const maxEntries = Math.max(1, config.maxEntries ?? 1000)
   // M1.1 — cache-key derivation. Default keys by pathname only (the
   // pre-M1 behaviour). User-supplied `cacheKey` opts in to varying
@@ -76,16 +95,29 @@ export function createISRHandler(
         method: 'GET',
         headers: originalReq.headers,
       })
-      const res = await handler(req)
-      const html = await res.text()
-      const headers: Record<string, string> = {}
-      res.headers.forEach((v, k) => {
-        headers[k] = v
-      })
-
-      set(key, { html, headers, timestamp: Date.now() })
+      // Bound the revalidation so a hung handler can't pin `key` in
+      // `revalidating` forever (which would freeze the entry stale).
+      const res = await Promise.race([
+        handler(req),
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(new Error('[Pyreon ISR] revalidation timeout')),
+            REVALIDATE_TIMEOUT_MS,
+          ),
+        ),
+      ])
+      // Never overwrite a good stale entry with a bad re-render
+      // (5xx/3xx) or poison it with a Set-Cookie response.
+      if (isCacheable(res)) {
+        const html = await res.text()
+        const headers: Record<string, string> = {}
+        res.headers.forEach((v, k) => {
+          headers[k] = v
+        })
+        set(key, { html, headers, timestamp: Date.now() })
+      }
     } catch {
-      // Revalidation failed — stale cache entry remains valid
+      // Revalidation failed / timed out — stale cache entry remains valid
     } finally {
       revalidating.delete(key)
     }
@@ -123,7 +155,11 @@ export function createISRHandler(
       })
     }
 
-    // Cache miss — render, cache, and return
+    // Cache miss — render. Only cache (and only normalize to a 200
+    // text/html response) when the render is actually cacheable; a
+    // transient error / redirect / Set-Cookie response is passed
+    // through verbatim with its ORIGINAL status + headers and is NOT
+    // stored, so it can't be replayed as a 200 to later visitors.
     const res = await handler(req)
     const html = await res.text()
     const headers: Record<string, string> = {}
@@ -131,6 +167,14 @@ export function createISRHandler(
       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, timestamp: Date.now() })
 
     return new Response(html, {

package/src/manifest.ts

@@ -475,6 +475,105 @@ const ButtonLink = createLink((props) => (
       seeAlso: ['Link', 'useLink'],
     },
 
+    {
+      name: 'Icon',
+      kind: 'component',
+      signature: '<Icon as={ImportedSvgComponent} | svg={rawSvgMarkupString} {...hostProps} />',
+      summary:
+        "Renders a FULL loaded SVG — it does NOT synthesize its own `<svg>` around hand-authored `<path>` children. You load an svg (it already contains the `<svg>` root) and Icon makes it container-sizable + theme-aware. Two source props: `as` — an imported SVG *component* (`import X from './x.svg?component'`), rendered DIRECTLY with no host wrapper (recommended; it's a real `<svg>` 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 needs a parent to mount — this one host is unavoidable for the string form). Defaults (`fill=\"currentColor\"`, `display:block;width:100%;height:100%`) are overridable — consumer props spread through and win. No fixed size → fills its container; `fill=\"currentColor\"` themes via CSS `color`. Intentionally no `useIcon` hook (an icon has no composable behaviour); two layers: `createIcon` (one component per loaded glyph) + `Icon` (one-off).",
+      example: `import { Icon } from '@pyreon/zero'
+import Check from './check.svg?component'
+import checkRaw from './check.svg?raw'
+
+// Component form — rendered directly, no wrapper, reliable fill:
+<span style="width:2rem"><Icon as={Check} /></span>
+
+// Raw-markup form — inlined inside one <span> host:
+<span style="width:2rem"><Icon svg={checkRaw} /></span>`,
+      mistakes: [
+        "Expecting `<Icon>` to synthesize an `<svg>` from `<path>` children — it does NOT. Pass a loaded svg via `as` (imported `?component`) or `svg` (imported `?raw` string). Children are not the API",
+        "Expecting `<Icon>` to size itself — it has NO intrinsic size; it fills its container. Wrap + size it (`<span style=\"width:1.5rem\">`) or use a sized flex/grid cell",
+        "Hardcoding `fill=\"#000\"` — breaks theming. Leave the `currentColor` default; drive colour with CSS `color` so dark mode + hover work for free. Only the `as` form forwards `fill` to the real svg — the `svg`-string form's markup is opaque, so colour it via `currentColor` inside the asset",
+        "Expecting svg-only props (`viewBox`, `fill`) to apply in the `svg`-string form — they can't reach the opaque inlined markup; only host attrs (`class`, `style`, `aria-*`, events) forward. Use the `as` form when you need to drive svg attributes",
+        "Reaching for a `useIcon` hook — there isn't one, by design. Use `createIcon` or inline `<Icon>`; an icon has no behaviour worth a hook layer",
+        "Preferring `svg` (raw string) for the wrapper-free guarantee — it's the opposite: `svg` ALWAYS adds a `<span>` host (unavoidable for string inlining); `as` is the zero-wrapper form",
+      ],
+      seeAlso: ['createIcon', 'IconProps', 'Image'],
+    },
+    {
+      name: 'createIcon',
+      kind: 'function',
+      signature: 'function createIcon(source: string | SvgComponent): (props: SvgAttributes) => VNodeChild',
+      summary:
+        "Builds a reusable icon component from a LOADED svg — a raw `<svg>…</svg>` markup string (`?raw`) OR an imported SVG component (`?component`). The result is still just `<Icon>` (string → `svg` prop, component → `as` prop), so it's container-sizable + theme-aware with every prop passed through. A generated icon set is `createIcon`-per-glyph with zero per-icon boilerplate. Mirrors the `createLink`/`createImage` factory layer, minus a hook (icons have no composable behaviour).",
+      example: `import { createIcon } from '@pyreon/zero'
+import StarSvg from './star.svg?component'
+import checkRaw from './check.svg?raw'
+
+export const Star = createIcon(StarSvg)     // component → rendered directly
+export const Check = createIcon(checkRaw)   // raw string → inlined via <span>
+
+// Sized + themed entirely by the consumer:
+<span style="width:48px"><Check class="text-green-600" aria-label="done" /></span>`,
+      mistakes: [
+        "Calling `createIcon` inside a component body — define icon components at module scope (like `createLink`/`createImage`). Re-creating the component every render defeats identity-based reconciliation",
+        "Passing hand-built `<path>` JSX as `source` — `source` is a full loaded svg: a `?raw` markup string OR a `?component` import. It does NOT take individual shapes; the loaded asset already contains its own `<svg>` root",
+        "Assuming the `?raw` form has no wrapper — the string form ALWAYS adds one `<span>` host (unavoidable for inlining markup). Use the `?component` form for the zero-wrapper, attribute-forwarding path",
+      ],
+      seeAlso: ['Icon', 'IconProps', 'createNamedIcon', 'iconsPlugin'],
+    },
+    {
+      name: 'iconsPlugin',
+      kind: 'function',
+      signature: "iconsPlugin({ dir | sets, out?, mode?: 'inline' | 'image' }): Plugin",
+      summary:
+        "Vite plugin (from `@pyreon/zero/server`): point it at a folder of `*.svg` files and it writes a strictly-typed generated `icons.gen.tsx` exporting `<Icon name=\"…\" />`. Add an svg → the `name` union widens; remove one → an invalid `name` fails typecheck. The generated file calls `createNamedIcon(REGISTRY)`, so `keyof typeof REGISTRY` IS the type surface (autocomplete + real go-to-definition, zero per-app wiring — same one-touch shape as fs-router / islands auto-registry). Regenerates on add/unlink in dev (idempotent write — never rewrites identical content). **Named multi-set form** (`sets: { ui: { dir }, brand: { dir, mode } }`, mutually exclusive with `dir`): one generated file exports a strictly-typed component PER set with NAMESPACED types so they never clash — `ui` → `<UiIcon name=\"…\" />` + `type UiIconName`, `brand` → `<BrandIcon name=\"…\" />` + `type BrandIconName`; per-set binding prefixes mean two sets sharing a glyph filename don't collide. Two render modes per the colorful-vs-system split (settable per-set): `mode: 'inline'` (default — system icons; each svg inlined as raw `?raw` markup, `currentColor`-themeable, recolor via CSS `color`) and `mode: 'image'` (colorful / brand icons; each svg emitted as a static asset, rendered `<img>`, NO mutation, original colors preserved). Default `out` is `icons.gen.tsx` next to `dir` for the single-set form (`src/icons` → `src/icons.gen.tsx`) or `src/icons.gen.tsx` for the multi-set form — recommend gitignoring it (build artifact). It writes a real file (NOT a virtual module) deliberately: the published `@pyreon/zero` package can't `import` a plugin virtual module — Rolldown resolves static imports before plugin `resolveId` (the same constraint that makes islands need `hydrateIslandsAuto(registry)` with an explicit import).",
+      example: `// vite.config.ts — single set:
+import { iconsPlugin } from '@pyreon/zero/server'
+iconsPlugin({ dir: './src/icons' })
+// app: import { Icon } from './icons.gen'; <Icon name="check-circle" />
+
+// Named multi-set — per-set typed components, no IconName clash:
+iconsPlugin({ sets: {
+  ui:    { dir: './src/icons/ui' },
+  brand: { dir: './src/icons/brand', mode: 'image' },
+}})
+// app: import { UiIcon, BrandIcon } from './icons.gen'
+// <UiIcon name="arrow-left" />  <BrandIcon name="logo-mark" />`,
+      mistakes: [
+        "Passing BOTH `dir` and `sets` (or neither) — exactly one is required; the plugin throws `[Pyreon] iconsPlugin: provide EXACTLY ONE of dir or sets` at config time",
+        "Using `mode: 'inline'` (default) for multicolor / brand SVGs — inline mode is for monochrome system icons you recolor via `currentColor`. A multicolor logo's hardcoded fills survive but you lose nothing by using `mode: 'image'`, which is the correct choice for no-mutation colorful assets",
+        "Using `mode: 'image'` for icons you need to recolor — `<img>` can't be themed via CSS `color`; the svg is opaque. Recolorable system icons need `mode: 'inline'`",
+        "Editing the generated `icons.gen.tsx` by hand — it's regenerated on every add/unlink. Add/remove `.svg` files in the set folder(s) instead; commit the gitignore entry, not the file",
+        "Expecting a virtual `import 'virtual:zero/icons'` — there isn't one (Rolldown import-ordering constraint). The plugin writes a REAL file you import by path; that's what gives go-to-definition + zero wiring",
+        "Pointing a set `dir` at a folder that doesn't exist yet — `scanIconDir` returns empty and the generated `*IconName` is `never` (every `name` fails typecheck). Create the folder + drop at least one `.svg` first",
+        "Forgetting `vite/client` types — the generated file's `?raw` imports rely on Vite's ambient `*.svg?raw` module declaration; the generated file emits `/// <reference types=\"vite/client\" />` but the consuming tsconfig must still resolve `vite/client`",
+      ],
+      seeAlso: ['createNamedIcon', 'Icon', 'IconProps'],
+    },
+    {
+      name: 'createNamedIcon',
+      kind: 'function',
+      signature:
+        "function createNamedIcon<R extends Record<string, string>>(registry: R, options?: { mode?: 'inline' | 'image' }): (props: { name: keyof R & string } & …) => VNodeChild",
+      summary:
+        "Runtime half of `iconsPlugin` — builds a strictly-typed `<Icon name=\"…\" />` from a name→source registry. `keyof R` makes `name` a precise string union (the generated file passes a literal registry so the union infers there → autocomplete + go-to-definition). `mode: 'inline'` (default) treats each `source` as raw `<svg>` markup rendered via `Icon` (`currentColor`-themeable system icons); `mode: 'image'` treats each `source` as an asset URL rendered `<img>` with NO mutation (colorful / brand icons). Either way it stays container-filling + props-transparent. Not normally hand-called — `iconsPlugin` emits the generated file that calls it; call it directly only for a hand-maintained set.",
+      example: `// icons.gen.tsx (auto-generated by iconsPlugin):
+import { createNamedIcon } from '@pyreon/zero'
+export const Icon = createNamedIcon({ 'check-circle': '<svg…>…</svg>' })
+
+// image mode (hand-maintained colorful set):
+import logo from './logo.svg' // Vite → URL
+export const Brand = createNamedIcon({ logo }, { mode: 'image' })
+<Brand name="logo" alt="Company" />`,
+      mistakes: [
+        "Passing a `Record<string, string>` typed loosely (e.g. `: Record<string, string>`) — that widens `keyof R` to `string` and you lose the typed `name`. Pass the object literal directly (or `as const`) so the keys infer",
+        "Using `mode: 'image'` then expecting `fill` / svg props to apply — the `<img>` is opaque; only host attrs (`class`, `style`, `alt`, events) forward. Use `mode: 'inline'` for svg-attribute control",
+        "Omitting `alt` in `mode: 'image'` — it defaults to `\"\"` (decorative). Pass a real `alt` for meaningful icons; screen readers skip empty-alt images",
+        "Calling `createNamedIcon` inside a component body — define the set once at module scope (the generated file does). Re-creating it per render defeats identity-based reconciliation",
+      ],
+      seeAlso: ['iconsPlugin', 'Icon', 'IconProps'],
+    },
     {
       name: 'Image',
       kind: 'component',

package/src/rate-limit.ts

@@ -62,6 +62,22 @@ export function rateLimitMiddleware(config: RateLimitConfig = {}): Middleware {
     for (const [key, entry] of store) {
       if (entry.resetAt <= now) store.delete(key)
     }
+    // HARD cap. The expired-sweep above only removes entries whose
+    // window has elapsed. An attacker flooding unique keys WITHIN one
+    // window (spoofed `X-Forwarded-For` / proxy header — `defaultKeyFn`
+    // trusts request headers) produces only fresh entries, so the sweep
+    // frees nothing and `store.set` grows the Map without bound — an
+    // unauthenticated memory-exhaustion DoS. `MAX_STORE_SIZE` was a
+    // declared constant used ONLY as a sweep trigger, never enforced.
+    // Map preserves insertion order, so evicting from the front drops
+    // the oldest trackers first (acceptable: an evicted attacker key
+    // simply gets a fresh window — no bypass of legitimate limits since
+    // a real client re-inserts and is immediately re-tracked).
+    while (store.size > MAX_STORE_SIZE) {
+      const oldest = store.keys().next().value
+      if (oldest === undefined) break
+      store.delete(oldest)
+    }
   }
 
   return (ctx: MiddlewareContext) => {

package/src/seo.ts

@@ -135,10 +135,25 @@ export function generateSitemap(
     .filter((p): p is string => p !== null)
     .filter((p) => !exclude.some((e) => p.startsWith(e)))
 
-  const allPaths: SitemapEntry[] = [
-    ...paths.map((p) => ({ path: p, changefreq, priority })),
-    ...(config.additionalPaths ?? []),
-  ]
+  // Dedup by path (first-wins, order-preserving). The same static route
+  // routinely appears in BOTH the file-system route scan AND
+  // `additionalPaths` (e.g. SSG-emitted paths merged in via
+  // `seoPlugin`), which previously produced a DUPLICATE `<url>` entry —
+  // the i18n branch of `clusterPathsByLocale` dedups via `byUnPrefixed`,
+  // but the non-i18n branch is a raw 1:1 `entries.map(...)`, so without
+  // this the duplicate reached the emitted sitemap. Dedup here covers
+  // both branches at the single source. The route-scan entry wins so its
+  // configured `changefreq`/`priority` is kept over a bare dup.
+  const allPaths: SitemapEntry[] = (() => {
+    const byPath = new Map<string, SitemapEntry>()
+    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()]
+  })()
 
   // PR K: when i18n is set, cluster URLs by their un-prefixed (default-
   // locale) form so each `<url>` entry can carry the hreflang siblings

package/src/server.ts

@@ -70,6 +70,8 @@ export { compose, getContext } from "./middleware";
 export { zeroPlugin as default, getZeroPluginConfig } from "./vite-plugin";
 export type { FaviconPluginConfig, FaviconLocaleConfig } from "./favicon";
 export { faviconPlugin, faviconLinks } from "./favicon";
+export type { IconsPluginConfig, IconSetConfig, NamedSetInput } from "./icons-plugin";
+export { iconsPlugin, iconNameFromFile, scanIconDir, generateIconSetSource, generateNamedIconSetsSource, componentNameFromSetKey } from "./icons-plugin";
 export type { SeoPluginConfig, SitemapConfig, RobotsConfig } from "./seo";
 export { seoPlugin, generateSitemap, generateRobots, jsonLd, seoMiddleware } from "./seo";
 export type { OgImagePluginConfig, OgImageTemplate, OgImageLayer } from "./og-image";

package/src/sharp.d.ts

@@ -9,6 +9,12 @@ declare module 'sharp' {
     toFile(path: string): Promise<void>
     toBuffer(): Promise<Buffer>
     metadata(): Promise<{ width?: number; height?: number; format?: string }>
+    /**
+     * Image statistics. `dominant` is the histogram-mode RGB swatch —
+     * the basis of the `'color'` / `'dominant-color'` placeholder
+     * strategy (a flat-fill SVG, not a muddy channel average).
+     */
+    stats(): Promise<{ dominant: { r: number; g: number; b: number } }>
   }
 
   function sharp(input: string | Buffer): SharpInstance