npm - @pyreon/zero - Versions diffs - 0.18.0 → 0.20.0 - Mend

@pyreon/zero 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/lib/{api-routes-Ci0kVmM4.js → api-routes-CMsLztoj.js} +5 -3
package/lib/api-routes.js +4 -2
package/lib/favicon.js +57 -3
package/lib/{fs-router-MewHc5SB.js → fs-router-Bacdhsq-.js} +4 -3
package/lib/image-plugin.js +90 -19
package/lib/index.js +96 -3
package/lib/rate-limit.js +5 -0
package/lib/seo.js +11 -6
package/lib/server.js +2888 -147
package/lib/testing.js +4 -2
package/lib/types/config.d.ts +9 -0
package/lib/types/favicon.d.ts +17 -1
package/lib/types/i18n-routing.d.ts +2 -4
package/lib/types/image-plugin.d.ts +65 -7
package/lib/types/index.d.ts +91 -7
package/lib/types/link.d.ts +2 -4
package/lib/types/server.d.ts +89 -5
package/lib/types/theme.d.ts +1 -2
package/package.json +10 -10
package/src/api-routes.ts +12 -2
package/src/favicon.ts +84 -2
package/src/fs-router.ts +7 -1
package/src/icon.tsx +182 -0
package/src/icons-plugin.ts +296 -0
package/src/image-plugin.ts +200 -32
package/src/index.ts +2 -0
package/src/isr.ts +54 -10
package/src/manifest.ts +99 -0
package/src/rate-limit.ts +16 -0
package/src/seo.ts +19 -4
package/src/server.ts +2 -0
package/src/sharp.d.ts +6 -0
package/src/ssg-plugin.ts +47 -8
package/src/types.ts +9 -0
package/lib/vite-plugin-y0NmCLJA.js +0 -2476

package/src/favicon.ts CHANGED Viewed

@@ -1,8 +1,43 @@
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Plugin } from 'vite'
+/**
+ * Stable content hash (FNV-1a, 32-bit) of the favicon source file(s),
+ * rendered as a `?v=<hex>` cache-bust query for the injected `<head>`
+ * links. Browsers cache favicons extremely aggressively (often per-
+ * session / effectively forever), so with a stable URL a changed icon
+ * is never re-fetched by returning visitors. Same source bytes →
+ * identical query (no needless cache churn); changed bytes → new query
+ * → browser re-downloads. Falls back to `''` (no query, prior
+ * behaviour) if a source can't be read — never break the build over a
+ * cache-bust nicety. NOTE: this versions everything referenced via
+ * `<link>` (svg/png/apple-touch/manifest). The bare `/favicon.ico`
+ * convention request (browsers fetch it with no link tag) and the
+ * `site.webmanifest`'s internal icon entries keep stable URLs — those
+ * rely on host cache headers / are re-resolved on PWA (re)install.
+ */
+export function faviconVersionQuery(paths: string[]): string {
+  let h = 0x811c9dc5
+  let any = false
+  for (const p of paths) {
+    let buf: Buffer
+    try {
+      buf = readFileSync(p)
+    } catch {
+      continue
+    }
+    any = true
+    for (let i = 0; i < buf.length; i++) {
+      h ^= buf[i]!
+      h = Math.imul(h, 0x01000193)
+    }
+  }
+  if (!any) return ''
+  return `?v=${(h >>> 0).toString(16).padStart(8, '0')}`
+}
 let sharpWarned = false
 function warnSharpMissing() {
   if (sharpWarned) return
@@ -126,6 +161,17 @@ export function faviconPlugin(config: FaviconPluginConfig): Plugin {
   let root = ''
   let isBuild = false
+  // Lazily computed once per build/dev session (source rarely changes
+  // within a run; recomputing per index.html transform is wasteful).
+  let versionQuery: string | null = null
+  function getVersionQuery(): string {
+    if (versionQuery === null) {
+      const paths = [join(root, config.source)]
+      if (config.darkSource) paths.push(join(root, config.darkSource))
+      versionQuery = faviconVersionQuery(paths)
+    }
+    return versionQuery
+  }
   return {
     name: 'pyreon-zero-favicon',
@@ -156,7 +202,11 @@ export function faviconPlugin(config: FaviconPluginConfig): Plugin {
       }
       server.middlewares.use(async (req, res, next) => {
-        const url = req.url ?? ''
+        // Strip the `?v=<hash>` cache-bust query (and any query) before
+        // matching — the injected links carry it; dev serves fresh
+        // (`Cache-Control: no-cache`) so the version is irrelevant here,
+        // but a query in the path would break every name match below.
+        const url = (req.url ?? '').split('?')[0]!
         // Resolve locale-specific source
         const localeSource = resolveLocaleSource(url, config, root)
@@ -316,12 +366,44 @@ export function faviconPlugin(config: FaviconPluginConfig): Plugin {
         } as any)
       }
+      // Cache-bust: stamp the source content hash onto every injected
+      // favicon/manifest link href so a changed icon is actually
+      // re-downloaded by returning visitors (theme-swap toggles `media`,
+      // not `href`, so this is orthogonal to the light/dark variants).
+      const v = getVersionQuery()
+      if (v) {
+        for (const t of tags) {
+          if (t.tag === 'link' && t.attrs.href) t.attrs.href += v
+        }
+      }
       return tags
     },
     async generateBundle() {
       if (!isBuild) return
+      // `faviconPlugin` is in the plugin list and a `source` is configured
+      // (it's a required field), so the user clearly WANTS favicons. If
+      // `sharp` is missing, the old behaviour was a single swallow-able
+      // `console.warn` + emit nothing — i.e. silently ship a production
+      // site with zero favicons. That's the footgun. Fail the build loudly
+      // with an actionable message instead. Dev keeps the soft warning
+      // (see `warnSharpMissing`) so local iteration isn't blocked.
+      try {
+        await import('sharp')
+      } catch {
+        this.error(
+          '[Pyreon] faviconPlugin: a favicon `source` is configured but ' +
+            '`sharp` is not installed — NO favicons would be generated and ' +
+            'the production build would silently ship none.\n' +
+            '  Fix:    bun add -D sharp   (or: npm i -D sharp)\n' +
+            `  Source: ${config.source}\n` +
+            'To intentionally build without favicons, remove faviconPlugin() ' +
+            'from your Vite plugins.',
+        )
+      }
       // Generate favicons for the base (default) source
       await generateFaviconSet.call(this, root, config.source, config.darkSource, '', config, themeColor, backgroundColor, generateManifest)

package/src/fs-router.ts CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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} />
+  }
+}

package/src/icons-plugin.ts ADDED Viewed

@@ -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)
+    },
+  }
+}