@pyreon/zero 0.16.0 → 0.19.0

package/src/icons-plugin.ts

@@ -0,0 +1,296 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, relative } from 'node:path'
+import type { Plugin } from 'vite'
+
+import type { IconMode } from './icon'
+
+// ─── iconsPlugin — folder → strictly-typed icon set ─────────────────────────
+//
+// Point it at a folder of `*.svg` files; it writes a generated `icons.gen.tsx`
+// that exports a strictly-typed `<Icon name="…" />`. Add an svg → the `name`
+// union widens; remove one → a now-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).
+//
+// Two render modes (per the colorful-vs-system split):
+//   • mode: 'inline' (default) — system icons. Each svg inlined as raw markup;
+//     `currentColor`-themeable, recolor via CSS `color`.
+//   • mode: 'image'            — colorful / brand icons. Each svg emitted as a
+//     static asset, rendered `<img>`. NO mutation, original colors preserved.
+//
+//   import { iconsPlugin } from '@pyreon/zero/server'
+//   iconsPlugin({ dir: './src/icons' })            // → src/icons.gen.tsx
+//   // app:
+//   import { Icon } from './icons.gen'
+//   <span style="width:2rem"><Icon name="check-circle" /></span>
+
+/** One named set in the multi-set form. */
+export 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
+}
+
+export 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`. */
+export function componentNameFromSetKey(key: string): string {
+  const pascal = key
+    .split(/[-_/\s]+/)
+    .filter(Boolean)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('')
+  const safe = pascal.replace(/[^A-Za-z0-9_$]/g, '')
+  const base = /^[A-Za-z_$]/.test(safe) ? safe : `Set${safe}`
+  return `${base}Icon`
+}
+
+/** Filename stem → registry key. `Check-Circle.svg` → `check-circle`. */
+export function iconNameFromFile(file: string): string {
+  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: string): string {
+  const camel = name.replace(/[-/](.)/g, (_, c: string) => c.toUpperCase())
+  const safe = camel.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. */
+export function scanIconDir(dir: string): string[] {
+  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.
+ */
+export function generateIconSetSource(
+  files: string[],
+  opts: { mode: IconMode; importDir: string },
+): string {
+  const query = opts.mode === 'image' ? '' : '?raw'
+  const seen = new Map<string, string>() // binding → name (collision guard)
+  const entries: { key: string; binding: string; file: string }[] = []
+  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')
+}
+
+/** One resolved set for the multi-set generator. */
+export 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.
+ */
+export function generateNamedIconSetsSource(sets: NamedSetInput[]): string {
+  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: string[] = []
+  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 = new Set<string>()
+    const entries: { key: string; binding: string; file: string }[] = []
+    for (const file of set.files) {
+      const k = iconNameFromFile(file)
+      // Per-set binding prefix → no cross-set collision even on shared names.
+      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: IconsPluginConfig, root: string): string {
+  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`)
+  }
+  // Multi-set form with no explicit `out`.
+  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.
+ */
+export function iconsPlugin(cfg: IconsPluginConfig): Plugin {
+  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: IconMode = cfg.mode ?? 'inline'
+
+  /** Relative `./…` import dir from the generated file to a scanned folder. */
+  function rel(out: string, scanned: string): string {
+    const r = relative(dirname(out), scanned).split('\\').join('/')
+    return r.startsWith('.') ? r : `./${r}`
+  }
+
+  async function regenerate(): Promise<void> {
+    const out = resolveOut(cfg, root)
+    let source: string
+    if (hasSets) {
+      const sets: NamedSetInput[] = 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),
+          }
+        },
+      )
+      source = generateNamedIconSetsSource(sets)
+    } else {
+      const scanned = join(root, cfg.dir as string)
+      source = generateIconSetSource(scanIconDir(scanned), {
+        mode,
+        importDir: rel(out, scanned),
+      })
+    }
+    // Idempotent — never rewrite identical content (avoids an HMR loop).
+    const current = existsSync(out) ? await readFile(out, 'utf8') : null
+    if (current !== source) await writeFile(out, source, 'utf8')
+  }
+
+  const watchDirs = (): string[] =>
+    hasSets
+      ? Object.values(cfg.sets ?? {}).map((s) => join(root, s.dir))
+      : [join(root, cfg.dir as string)]
+
+  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: string): void => {
+        if (
+          file.toLowerCase().endsWith('.svg') &&
+          dirs.some((d) => file.startsWith(d))
+        ) {
+          void regenerate()
+        }
+      }
+      server.watcher.on('add', onChange)
+      server.watcher.on('unlink', onChange)
+    },
+  }
+}

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
@@ -253,7 +293,12 @@ export default function SvgComponent(props) {
       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 +308,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 +324,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 +354,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 +365,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 +411,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 +438,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 +463,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 +625,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, {