@pyreon/zero 0.24.4 → 0.24.6

package/src/manifest.ts

@@ -1,787 +0,0 @@
-import { defineManifest } from '@pyreon/manifest'
-
-/**
- * @pyreon/zero manifest — feeds llms.txt / llms-full.txt / MCP
- * api-reference.ts via `bun run gen-docs`. Scope: the SSG roadmap
- * surface (zero(), i18n, ISR, adapters, getStaticPaths,
- * expandRoutesForLocales, plus the core plugin APIs that compose with
- * them). Other zero subpath exports (`/image`, `/font`, `/cache`, etc.)
- * stay in CLAUDE.md until a real consumer-side foot-gun surfaces — the
- * manifest is for the surface AI agents need to discover, not an
- * exhaustive enumeration.
- */
-export default defineManifest({
-  name: '@pyreon/zero',
-  title: 'Zero — Full-Stack Meta-Framework',
-  tagline:
-    'Full-stack meta-framework: fs-routing, SSR/SSG/ISR/SPA, API routes, server actions, adapters, i18n',
-  description:
-    "Pyreon's full-stack meta-framework. Single `zero({ mode, base, ssg, i18n })` plugin chooses rendering mode (`ssg` / `ssr` / `isr` / `spa`), wires file-system routing under `src/routes/`, and composes with seo / favicon / og-image / ai / i18n-routing / csp plugins. Per-route exports for `meta`, `getStaticPaths`, `revalidate`, `validateSearch`, `loader`. Deployment via per-platform adapters (Vercel / Cloudflare Pages / Netlify / Node / Bun / static).",
-  category: 'server',
-  longExample: `import { defineConfig } from 'vite'
-import pyreon from '@pyreon/vite-plugin'
-import zero from '@pyreon/zero/server'
-import { vercelAdapter, seoPlugin, aiPlugin } from '@pyreon/zero/server'
-
-// SSG + i18n + dynamic-route × locale cross-product + hreflang sitemap.
-// Single zero() call wires routing, mode, base, locales, adapter; the
-// composed plugins (seoPlugin/aiPlugin) auto-detect i18n config from the
-// SSG manifest, so consumers configure locales once.
-export default defineConfig({
-  plugins: [
-    pyreon(),
-    zero({
-      mode: 'ssg',
-      i18n: {
-        locales: ['en', 'de', 'cs'],
-        defaultLocale: 'en',
-        strategy: 'prefix-except-default',  // default-locale unprefixed for SEO
-      },
-      ssg: {
-        concurrency: 8,                     // PR D — parallel render workers
-        onProgress: ({ completed, total }) => console.log(\`\${completed}/\${total}\`),
-      },
-      adapter: vercelAdapter(),             // PR J — emits .vercel/output/config.json
-    }),
-    seoPlugin({ sitemap: { useSsgPaths: true, hreflang: true } }),
-    aiPlugin(),
-  ],
-})
-
-// src/routes/posts/[id].tsx — dynamic route with getStaticPaths
-// produces 3 IDs × 3 locales = 9 prerendered HTML files under SSG+i18n.
-import type { GetStaticPaths } from '@pyreon/zero/server'
-
-export const getStaticPaths: GetStaticPaths<{ id: string }> = () =>
-  POSTS.map((p) => ({ params: { id: String(p.id) } }))
-
-export const revalidate = 60  // PR I — wires platform ISR per-route (Vercel/Cloudflare/Netlify)
-
-export default function PostPage() { /* component body */ }`,
-  features: [
-    'mode: ssg / ssr / isr / spa — single config field',
-    'i18n route duplication (prefix / prefix-except-default strategies)',
-    'getStaticPaths per route — dynamic-route × locale compounds at SSG',
-    'Per-route revalidate — wires platform ISR via Adapter.revalidate',
-    'Concurrent SSG render loop with onProgress callback',
-    'Adapter.build() auto-invoked in SSG closeBundle — emits platform routing config',
-    'Per-locale 404 + hreflang sitemap (auto-detects i18n config)',
-    'Loader-thrown redirect → _redirects manifest (Netlify/Cloudflare/Vercel)',
-    'Subpath / base-path single source of truth — zero({ base }) propagates to Vite + router',
-  ],
-  // MCP-density entries: dense summary + 6+ mistakes per flagship API.
-  // Scope: the SSG roadmap surface (i18n, ISR, adapter, getStaticPaths,
-  // expandRoutesForLocales) + core zero() entry. Subpath plugins
-  // (seoPlugin, aiPlugin, faviconPlugin, ogImagePlugin) get smaller
-  // entries — they compose with zero but aren't the i18n/SSG primary
-  // discovery surface.
-  api: [
-    {
-      name: 'zero',
-      kind: 'function',
-      signature:
-        'function zero(config?: ZeroConfig): Plugin[] // default export of @pyreon/zero/server',
-      summary:
-        "Top-level Vite plugin chain for @pyreon/zero. Single config object selects rendering mode (`'ssr' | 'ssg' | 'isr' | 'spa'`), subpath base (`base: '/blog/'`), SSG settings (paths, concurrency, onProgress, emit404, emitRedirects), i18n config (locales / defaultLocale / strategy), and deployment adapter. Returns `Plugin[]` because the SSG mode adds a companion `ssgPlugin()` automatically — Vite's plugins array natively flattens nested arrays so `plugins: [pyreon(), zero()]` works without spread.",
-      example: `import zero from '@pyreon/zero/server'
-
-// SPA (default) — no special config needed
-plugins: [pyreon(), zero()]
-
-// SSG with auto-detected paths + i18n + adapter
-plugins: [pyreon(), zero({
-  mode: 'ssg',
-  i18n: { locales: ['en','de','cs'], defaultLocale: 'en' },
-  adapter: vercelAdapter(),
-})]
-
-// Subpath deploy (e.g. served at /blog/)
-plugins: [pyreon(), zero({ base: '/blog/', mode: 'ssg' })]`,
-      mistakes: [
-        "Setting `base` in BOTH `vite.config.base` AND `zero({ base })` and expecting them to merge — user's explicit `vite.config.base` overrides the plugin-returned base. Set base ONCE via `zero({ base })`; let it propagate to Vite + router automatically",
-        "Passing `layout` to `createApp` / `startClient` when fs-router already emits `_layout.tsx` as a parent route — double-mounts the layout. Drop the explicit option; `_layout.tsx` is the canonical layout registration",
-        "Mixing `mode: 'ssg'` with a runtime adapter that has no SSG branch (e.g. expecting `nodeAdapter` to write platform routing config under SSG) — node/bun/static adapters no-op for SSG; use vercel/cloudflare/netlify if you need platform routing emission",
-        "Configuring `ssg.paths` AND per-route `getStaticPaths` together for the same dynamic route — both produce the same path list and the SSG plugin renders each path TWICE (the second pass overwrites). Pick one: `ssg.paths` for top-down explicit lists, `getStaticPaths` for per-route enumerators",
-        'Forgetting that `mode: \'ssg\'` returns `Plugin[]` (not a single Plugin) — any downstream test code that does `plugins: [zeroPlugin().name]` instead of `plugins: zeroPlugin()` breaks',
-        "Setting `ssg.concurrency` higher than the data layer's connection ceiling — loaders running concurrently overwhelm the upstream (db pool, external API rate limit). Default `4` is safe; raise after profiling, lower to `1` for serial-required loaders",
-      ],
-      seeAlso: ['I18nRoutingConfig', 'GetStaticPaths', 'Adapter', 'createISRHandler'],
-    },
-    {
-      name: 'I18nRoutingConfig',
-      kind: 'type',
-      signature:
-        "interface I18nRoutingConfig { locales: string[]; defaultLocale: string; strategy?: 'prefix' | 'prefix-except-default' }",
-      summary:
-        "Configuration shape for `zero({ i18n })`. `locales` is the supported BCP-47 list (validated against path-traversal — `..`, `/`, backslash, `.`, leading-dot, NUL chars rejected). `defaultLocale` is the canonical / SEO-primary locale. `strategy` selects URL shape — `'prefix-except-default'` (default) keeps `/about` unprefixed for the default locale + emits `/de/about` etc. for non-defaults (best for SEO-on-default-locale apps); `'prefix'` prefixes every locale including default (`/en/about`, `/de/about`) for apps with no primary locale.",
-      example: `// Prefix-except-default (canonical SEO shape — default unprefixed)
-zero({ i18n: { locales: ['en','de','cs'], defaultLocale: 'en' } })
-// Emits: /about, /de/about, /cs/about
-// Default locale's index.html: dist/about/index.html (NOT dist/en/about/...)
-
-// Prefix (every locale prefixed)
-zero({ i18n: { locales: ['en','de','cs'], defaultLocale: 'en', strategy: 'prefix' } })
-// Emits: /en/about, /de/about, /cs/about
-// NO unprefixed /about exists`,
-      mistakes: [
-        "Configuring locale strings with `.`, `..`, `/`, backslash, or NUL — rejected by `validateLocale` (PR L2 guard). Common BCP-47 shapes pass: `en`, `de-AT`, `en-US`, `zh-Hans`, `pt-BR`",
-        "Expecting `<RouterLink to='/posts/1'>` rendered inside `/de/posts` to emit `/de/posts/1` automatically — RouterLinks emit LITERAL hrefs; cross-locale navigation falls through to the default-locale route. Locale-aware navigation is a separate API (not yet shipped)",
-        "Assuming the framework runtime-detects locale from URL prefix — it doesn't. The router matches `/de/about` to the duplicated route record; consumer code reads locale from URL parsing OR from `i18nRouting()` middleware (request-time Accept-Language detection)",
-        "Using `prefix-except-default` and then duplicating the root `_layout.tsx` per locale — `expandRoutesForLocales` deliberately SKIPS root-layout duplication under this strategy because the unprefixed root layout already wraps locale-prefixed children via hierarchical match. Under `prefix` strategy the skip does NOT apply (no unprefixed default to inherit from)",
-        "Single-locale `locales: ['en']` + `prefix-except-default` — short-circuits to a no-op (no other locales to prefix). Use `prefix` strategy if you want `/en/about` for SEO consistency with future multi-locale expansion",
-        "Hand-writing per-locale routes (`src/routes/de/about.tsx`) instead of letting `expandRoutesForLocales` duplicate from a single source file — the framework's duplication wires hierarchical layouts + loader-data hydration + hreflang sitemap clustering correctly; hand-written variants miss the cross-cuts",
-      ],
-      seeAlso: ['zero', 'expandRoutesForLocales', 'i18nRouting'],
-    },
-    {
-      name: 'expandRoutesForLocales',
-      kind: 'function',
-      signature:
-        'function expandRoutesForLocales(routes: FileRoute[], config: I18nRoutingConfig): FileRoute[] // server-only',
-      summary:
-        "Fans a flat route list into per-locale variants based on `I18nRoutingConfig`. Each non-default locale gets a full subtree duplicate — layouts, error boundaries, loading components, 404 pages, dynamic params (`[id]` → `:id`), catch-all routes (`[...slug]` → `:slug*`) all compose naturally with the locale prefix. Source `filePath` is preserved so the duplicated routes share the same component module; only `urlPath` / `dirPath` / `depth` change. `getStaticPaths` inherits across duplicates so dynamic-route × locale cross-products work automatically (3 IDs × 3 locales = 9 SSG outputs). Root-layout skip under `prefix-except-default` prevents double-mount.",
-      example: `import { expandRoutesForLocales } from '@pyreon/zero/server'
-import { parseFileRoutes, scanRouteFiles } from '@pyreon/zero/server'
-
-const files = await scanRouteFiles('./src/routes')
-const baseRoutes = parseFileRoutes(files)
-const fileRoutes = expandRoutesForLocales(baseRoutes, {
-  locales: ['en', 'de', 'cs'],
-  defaultLocale: 'en',
-  strategy: 'prefix-except-default',
-})
-// fileRoutes now contains: original routes + /de/* + /cs/* subtrees`,
-      mistakes: [
-        "Calling this from CLIENT code — server-only export from `@pyreon/zero/server`. Importing from `@pyreon/zero` (the client entry) gives a clear server-only error stub",
-        "Expecting hand-written `src/routes/de/about.tsx` to compose with duplicated `/de/about` from `/about` — the helper does NOT detect collisions today; a user-defined route at `/de/profile` + locale `de` produces two records at the same urlPath (router matches first)",
-        "Modifying the returned `FileRoute[]` and expecting `getStaticPaths` inheritance to update — the duplicates carry frozen `exports` references at duplication time; later mutations don't propagate to the SSG enumerator",
-        "Setting `strategy: 'prefix'` and expecting `/about` (unprefixed) to ALSO render — under `prefix` every locale is prefixed; the default-locale unprefixed URL does NOT exist as a dist file. Use `prefix-except-default` if you need both",
-        "Passing user-controlled strings as locales without validation — the helper validates against path-traversal (`..`, `/`, backslash, `.`, NUL) but does NOT validate BCP-47 shape; an invalid locale silently produces oddly-shaped URLs",
-      ],
-      seeAlso: ['I18nRoutingConfig', 'zero', 'parseFileRoutes'],
-    },
-    {
-      name: 'GetStaticPaths',
-      kind: 'type',
-      signature:
-        'type GetStaticPaths<TParams> = () => Array<{ params: TParams }> | Promise<Array<{ params: TParams }>>',
-      summary:
-        'Per-route export type for dynamic-route enumeration at SSG build time (PR A of the SSG roadmap). Route files at `src/routes/posts/[id].tsx` export `getStaticPaths` returning the concrete param values; the SSG plugin expands the URL pattern (`/posts/:id` × `[1, 2, 3]` → `/posts/1`, `/posts/2`, `/posts/3`). Sync or async return; errors during enumeration land in `PrerenderResult.errors` without aborting other routes. Catch-all routes (`[...slug].tsx`) work via `{ params: { slug: "a/b" } }` → `/blog/a/b`.',
-      example: `import type { GetStaticPaths } from '@pyreon/zero/server'
-
-// src/routes/posts/[id].tsx
-export const getStaticPaths: GetStaticPaths<{ id: string }> = () =>
-  POSTS.map((p) => ({ params: { id: String(p.id) } }))
-
-// Async loader-driven enumeration
-export const getStaticPaths: GetStaticPaths<{ slug: string }> = async () => {
-  const posts = await db.query('SELECT slug FROM posts WHERE published = true')
-  return posts.map((p) => ({ params: { slug: p.slug } }))
-}`,
-      mistakes: [
-        "Returning param values as numbers instead of strings (`{ id: 1 }` instead of `{ id: '1' }`) — URL segments are always strings; the type enforces this but a runtime cast (`as any`) silently produces wrong paths",
-        "Forgetting to handle the no-i18n vs i18n cardinality — with `zero({ i18n })` the cross-product is `paths × locales`; a 100-path enumerator with 3 locales produces 300 dist files. Pair with `ssg.concurrency` to avoid serial-render blowup",
-        "Throwing in `getStaticPaths` and expecting the build to abort — errors are CAPTURED into `PrerenderResult.errors` and the build continues for other routes. Check `dist/_pyreon-ssg-errors.json` after the build (PR G)",
-        "Mixing `getStaticPaths` and `ssg.paths` for the same dynamic route — both produce paths and the SSG plugin renders each twice",
-        'Reading external state in `getStaticPaths` without await — the function is async-aware; missing await produces "[object Promise]" segments in the URL',
-      ],
-      seeAlso: ['zero', 'I18nRoutingConfig'],
-    },
-    {
-      name: 'Adapter',
-      kind: 'type',
-      signature:
-        'interface Adapter { name: string; build?(options: AdapterBuildOptions): Promise<void>; revalidate?(path: string): Promise<AdapterRevalidateResult> }',
-      summary:
-        "Deployment adapter contract. `build()` is auto-invoked by SSG's `closeBundle` AFTER the path render loop (PR J) and writes platform-specific routing config: Vercel emits `.vercel/output/config.json`; Cloudflare emits `_routes.json` with zero-function `exclude: ['/*']`; Netlify emits `netlify.toml` with `publish = '.'` + asset cache headers. `revalidate(path)` is the runtime hook for build-time ISR (PR I) — Vercel POSTs to a revalidation webhook, Cloudflare purges the edge cache, Netlify triggers a Build Hook. Static / node / bun adapters no-op for SSG.",
-      example: `import { vercelAdapter, cloudflareAdapter, netlifyAdapter, staticAdapter } from '@pyreon/zero/server'
-
-// Vercel — emits .vercel/output/config.json v3 STATIC variant
-plugins: [pyreon(), zero({ mode: 'ssg', adapter: vercelAdapter() })]
-
-// Cloudflare — emits _routes.json (zero-function deploy)
-plugins: [pyreon(), zero({ mode: 'ssg', adapter: cloudflareAdapter() })]
-
-// Netlify — emits netlify.toml with publish="." + cache headers
-plugins: [pyreon(), zero({ mode: 'ssg', adapter: netlifyAdapter() })]
-
-// ISR revalidation webhook handler (Vercel-side)
-await vercelAdapter().revalidate?.('/posts/123')
-// → { regenerated: true } on success`,
-      mistakes: [
-        "Calling `adapter.revalidate(path)` without the platform's env vars set (e.g. `VERCEL_DEPLOYMENT_URL` + `VERCEL_REVALIDATE_TOKEN`) — returns `{ regenerated: false }` with a dev-mode warning. The webhook is a no-op without credentials",
-        'Expecting `nodeAdapter` / `bunAdapter` to emit platform routing config under SSG — they no-op (no platform routing to configure). Use vercel/cloudflare/netlify if you need a routing config emitted',
-        "Setting `mode: 'ssg'` + `adapter: vercelAdapter()` and ALSO writing `.vercel/output/config.json` manually — the adapter overwrites it. Pick one source of truth",
-        'Calling adapter methods from CLIENT code — server-only. Import from `@pyreon/zero/server`',
-        "Forgetting that Netlify's revalidate triggers a FULL-SITE rebuild (Build Hook semantics) — Netlify doesn't expose per-page ISR. The `path` arg flows into `trigger_title` for audit logs but doesn't scope the rebuild",
-      ],
-      seeAlso: ['zero', 'createISRHandler', 'vercelAdapter'],
-    },
-    {
-      name: 'createISRHandler',
-      kind: 'function',
-      signature:
-        'function createISRHandler(handler: (req: Request) => Promise<Response>, config: ISRConfig): ISRHandler',
-      summary:
-        "Runtime ISR — on-demand SSR caching with stale-while-revalidate. Wraps an SSR handler so pages are rendered on the FIRST request, cached per-URL (or per-`cacheKey`-derived key), and served stale until expiry while a background revalidate fires. The returned `ISRHandler` is still a callable `(req) => Promise<Response>` for `Bun.serve({ fetch: ... })`, but ALSO exposes imperative invalidation: `.revalidateNow(key)` drops one entry (returns `{ dropped: boolean }`), `.revalidateAll()` drops everything (when the store implements `clear()`). Pair with webhooks for CMS-driven cache busting — no stale window between content update and propagation. Distinct from build-time ISR (per-route `revalidate` export + `Adapter.revalidate`): runtime ISR caches at request time; build-time ISR triggers platform rebuilds. They can coexist: a `mode: 'isr'` app with per-route `revalidate` exports gets BOTH.",
-      example: `import { createISRHandler, createServer } from '@pyreon/zero/server'
-
-const ssrHandler = createServer({ routes })
-const isr = createISRHandler(ssrHandler, { revalidate: 60 })
-
-// Use as the request handler
-Bun.serve({ fetch: isr })
-
-// CMS webhook: drop one entry
-app.post('/api/webhooks/post-updated', async (req) => {
-  const { postId } = await req.json()
-  const result = await isr.revalidateNow(\`/posts/\${postId}\`)
-  return Response.json(result) // { dropped: true | false }
-})
-
-// Admin "purge cache" endpoint
-app.post('/admin/purge', async () => {
-  await isr.revalidateAll()
-  return new Response('ok')
-})`,
-      mistakes: [
-        'Treating the returned handler as a plain function — it ALSO carries `.revalidateNow(key)` and `.revalidateAll()` methods. Webhook-driven invalidation is the canonical way to bust the cache; waiting for the TTL is the fallback',
-        'Calling `.revalidateAll()` against a store that does not implement `clear()` — throws a clear error. External stores (Redis with TTL-only) must opt in by implementing the method',
-        'Expecting `revalidateNow(key)` against a store without `delete?()` to physically drop the entry — returns `{ dropped: false }` honestly; such stores rely on TTL for eviction',
-        'Sharing the ISR handler across server instances without external cache — each server\'s in-memory cache diverges. For multi-instance deploys, swap `config.store` to a shared cache layer (Redis / Vercel KV / Cloudflare KV)',
-        'Setting `revalidate: 0` and expecting "never cache" — pass-through is the explicit handler call (no `createISRHandler` wrapper). Use `revalidate: Number.MAX_SAFE_INTEGER` for "cache forever, invalidate only via `revalidateNow`"',
-      ],
-      seeAlso: ['zero', 'Adapter', 'ISRStore', 'createMemoryStore'],
-    },
-    {
-      name: 'vercelAdapter',
-      kind: 'function',
-      signature: 'function vercelAdapter(): Adapter',
-      summary:
-        'Vercel deployment adapter. SSG branch emits `.vercel/output/config.json` v3 STATIC variant (no functions, asset cache headers). Does NOT copy files into `.vercel/output/static/` — Vercel CLI auto-detects dist. ISR `revalidate(path)` POSTs to `<VERCEL_DEPLOYMENT_URL>/api/_pyreon-revalidate?path=…&secret=<token>`; user-side webhook validates secret + calls `res.revalidate()`.',
-      example: 'plugins: [pyreon(), zero({ mode: \'ssg\', adapter: vercelAdapter() })]',
-      seeAlso: ['Adapter', 'zero'],
-    },
-    {
-      name: 'cloudflareAdapter',
-      kind: 'function',
-      signature: 'function cloudflareAdapter(): Adapter',
-      summary:
-        "Cloudflare Pages adapter. SSG branch emits `_routes.json` with `{ version: 1, include: [], exclude: ['/*'] }` — i.e. \"every URL is static, never invoke a Pages Function\" (zero-function deploy). Without this file Pages defaults to running the worker on every request, wasting paid-plan compute. ISR `revalidate(path)` POSTs to Cloudflare's zone purge_cache API.",
-      example: 'plugins: [pyreon(), zero({ mode: \'ssg\', adapter: cloudflareAdapter() })]',
-      seeAlso: ['Adapter', 'zero'],
-    },
-    {
-      name: 'netlifyAdapter',
-      kind: 'function',
-      signature: 'function netlifyAdapter(): Adapter',
-      summary:
-        'Netlify adapter. SSG branch emits `netlify.toml` with `publish = "."` + `Cache-Control` headers for `/assets/*`. PR B\'s `dist/_redirects` covers loader-thrown redirects (Netlify reads the file natively). ISR `revalidate(path)` POSTs to a Build Hook URL with `trigger_title=revalidate:<path>` for audit-log traceability (Netlify queues a full-site partial rebuild — no per-page ISR API).',
-      example: 'plugins: [pyreon(), zero({ mode: \'ssg\', adapter: netlifyAdapter() })]',
-      seeAlso: ['Adapter', 'zero'],
-    },
-    {
-      name: 'seoPlugin',
-      kind: 'function',
-      signature:
-        'function seoPlugin(config: SeoPluginConfig): Plugin // server-only',
-      summary:
-        "SEO plugin — emits `sitemap.xml`, `robots.txt`, JSON-LD, and hreflang cross-references. `sitemap.useSsgPaths: true` auto-detects from SSG output manifest (paths from `getStaticPaths` × locale variants flow in automatically). `sitemap.hreflang: true` auto-detects i18n config from the SSG manifest → clusters per-locale URLs into ONE `<url>` with `<xhtml:link rel='alternate' hreflang>` siblings + `x-default` entry. Falls back to fs-router walk when SSG manifest is absent.",
-      example: `seoPlugin({
-  sitemap: {
-    baseUrl: 'https://example.com',
-    useSsgPaths: true,      // PR F — auto-detect SSG paths
-    hreflang: true,         // PR K — auto-detect i18n + emit cross-refs
-  },
-  robots: { sitemap: 'https://example.com/sitemap.xml' },
-})`,
-      mistakes: [
-        "Setting `useSsgPaths: true` in non-SSG mode — silently falls back to fs-router walk (no SSG manifest to read). Same effect as omitting the flag",
-        "Setting `hreflang: true` without `zero({ i18n })` — emits a plain single-URL sitemap (no clustering). Configure i18n on zero() to activate hreflang",
-        "Expecting `hreflang: I18nRoutingConfig` (explicit form) to override the SSG manifest's i18n config — explicit wins, but typically the auto-detect is the right shape. Use explicit only if you want a different locale set in the sitemap than in routing",
-      ],
-      seeAlso: ['aiPlugin', 'zero'],
-    },
-    {
-      name: 'aiPlugin',
-      kind: 'function',
-      signature: 'function aiPlugin(config?: AiPluginConfig): Plugin // server-only',
-      summary:
-        'AI integration plugin — generates `llms.txt`, `llms-full.txt`, and JSON-LD inference metadata at build time. Designed for sites that want to be AI-readable (search engines, model trainers, agentic crawlers). The generated files are themselves Pyreon\'s on-publish artifacts; the plugin runs `inferJsonLd` per route to extract structured data from `meta` exports.',
-      example: 'plugins: [pyreon(), zero(), seoPlugin({ ... }), aiPlugin()]',
-      seeAlso: ['seoPlugin', 'zero'],
-    },
-    {
-      name: 'i18nRouting',
-      kind: 'function',
-      signature:
-        'function i18nRouting(config: I18nRoutingConfig): Plugin // server-only',
-      summary:
-        'Vite plugin for REQUEST-TIME locale detection — Accept-Language header, cookie, root-path redirect to detected locale. Orthogonal to BUILD-TIME route duplication (`expandRoutesForLocales`); both can be used together. The plugin sets a request-context locale that components read via `createLocaleContext`.',
-      example: `import { i18nRouting } from '@pyreon/zero/server'
-
-plugins: [pyreon(), zero({ i18n: { locales, defaultLocale } }), i18nRouting({ locales, defaultLocale })]
-// Same config object shape — accepts the i18n already passed to zero() if you keep one source of truth`,
-      mistakes: [
-        "Confusing this plugin with route duplication — they're separate concerns. `zero({ i18n })` controls BUILD-TIME duplication; `i18nRouting()` plugin controls REQUEST-TIME detection",
-        'Using `i18nRouting()` under SSG mode without a server runtime — request-time middleware needs a live request handler. SSG only emits static files. Use `mode: \'ssr\'` for request-time locale detection',
-      ],
-      seeAlso: ['zero', 'I18nRoutingConfig', 'createLocaleContext'],
-    },
-    {
-      name: 'validateEnv',
-      kind: 'function',
-      signature:
-        'function validateEnv<T>(schema: T, env?: ProcessEnv): ValidatedEnv<T> // server-only',
-      summary:
-        "Env-variable validation with type coercion. Schema accepts primitives (`String`, `Number`, `Boolean`) for default coercion + `schema()` for custom parsers. `publicEnv()` returns a client-safe subset (no secrets). Catches missing-required-env errors at startup instead of mid-request runtime crashes.",
-      example: `import { validateEnv, publicEnv, schema } from '@pyreon/zero/server'
-
-const env = validateEnv({
-  PORT: 3000,
-  DEBUG: false,
-  API_KEY: String,        // required string
-  API_URL: schema((v) => new URL(v)),
-})
-// env.PORT → number; env.API_KEY → string; env.API_URL → URL
-
-const pub = publicEnv(env, ['API_URL'])  // omit secrets`,
-      seeAlso: ['zero'],
-    },
-    {
-      name: 'cspMiddleware',
-      kind: 'function',
-      signature:
-        'function cspMiddleware(config: { directives: CspDirectives }): Middleware // server-only',
-      summary:
-        'CSP (Content Security Policy) middleware — emits `Content-Security-Policy` header per request with configurable directives. Pair with `useNonce()` for inline scripts (nonce is generated per-request and embedded in CSP `script-src \'nonce-XXX\'`). Server-only; SPA mode without a request handler can\'t emit per-request nonces.',
-      example: `import { cspMiddleware } from '@pyreon/zero/server'
-
-plugins: [pyreon(), zero({
-  middleware: [cspMiddleware({
-    directives: {
-      'default-src': ["'self'"],
-      'script-src': ["'self'", "'nonce-{{nonce}}'"],
-    },
-  })],
-})]`,
-      seeAlso: ['useRequestLocals'],
-    },
-    {
-      name: 'useRequestLocals',
-      kind: 'hook',
-      signature: 'function useRequestLocals<T = unknown>(): T',
-      summary:
-        'Bridge middleware-attached request locals into the component tree. Middleware sets `ctx.locals.user = currentUser`; components call `useRequestLocals()` to read. Reactive context — locale-aware re-reads work inside `effect()` / JSX thunks.',
-      example: `// middleware
-async function authMiddleware(ctx, next) {
-  ctx.locals.user = await verifyToken(ctx.req.headers.get('authorization'))
-  return next()
-}
-
-// component
-const { user } = useRequestLocals<{ user: User | null }>()`,
-      seeAlso: ['cspMiddleware'],
-    },
-
-    // ─── Three-layer extensibility: Link / Image / Script ──────────────
-    // Each component ships THREE layers: a `useX(props)` hook for full
-    // control, a `createX(Component)` HOC for wrapping any component
-    // with the optimization behavior, and a default `X` component that
-    // covers the 90% case. Same pattern across all three so consumers
-    // build mental model once. Reference: link.tsx, image.tsx, script.tsx.
-
-    {
-      name: 'Link',
-      kind: 'component',
-      signature:
-        '<Link href={path} prefetch="hover" activeClass={cls}>{children}</Link>',
-      summary:
-        "Default navigation link built on an `<a>` tag — client-side push via `router.push()`, hover/viewport prefetch, `aria-current=\"page\"` on exact match, `activeClass` / `exactActiveClass` for nav-state styling. Built on `createLink` so consumers can swap the rendered element via `createLink(MyCustomLink)` without losing the prefetch + active-state behavior.",
-      example: `import { Link } from '@pyreon/zero/link'
-
-<Link href="/about" prefetch="viewport" activeClass="nav-active">About</Link>
-<Link href="/external" external>External</Link>  // target="_blank" rel="noopener noreferrer"`,
-      mistakes: [
-        "Using `<a href={path} onClick={() => router.push(path)}>` instead of `<Link>` — manual approach skips prefetch, active-state class merging, and the keyboard-modifier guard (Cmd+click should open new tab, not navigate in-place)",
-        "Setting `prefetch=\"hover\"` (default) and expecting prefetch on mobile — mobile devices don't fire mouseenter; use `prefetch=\"viewport\"` for IntersectionObserver-based prefetch (or accept that touchstart triggers prefetch too)",
-        "Passing `class` AND `activeClass` — both are MERGED via `cx` (not overridden); the user-provided `class` always applies, `activeClass` is appended when `isActive()` is true",
-        "`<Link to={...}>` — Link uses `href`, NOT `to` (RouterLink from `@pyreon/router` uses `to`; Link from `@pyreon/zero/link` uses `href` to match HTML anchor convention)",
-        "Expecting `external: true` to skip prefetch — `external` controls click handling (opens in new tab via `target=\"_blank\"`), not prefetch. Use `prefetch=\"none\"` if you want to skip prefetch for an internal link",
-        "Building a custom anchor wrapper from scratch instead of using `createLink` or `useLink` — the prefetch cache, keyboard-modifier guard, active-state class composition, and SSR-safe document.head injection are non-trivial",
-      ],
-      seeAlso: ['useLink', 'createLink', 'prefetchRoute'],
-    },
-    {
-      name: 'useLink',
-      kind: 'hook',
-      signature: 'function useLink(props: LinkProps): UseLinkReturn',
-      summary:
-        'Composable that returns all link behavior — `{ ref, handleClick, handleMouseEnter, handleTouchStart, isActive, isExactActive, classes }`. Use when `createLink` is too opinionated (e.g. you need a `<button>` link, a card-shaped link, or want to compose with another framework primitive). Internals: hover/viewport prefetch via IntersectionObserver, keyboard-modifier guard (Cmd+click opens new tab), active/exact-active path matching, class-string composition.',
-      example: `import { useLink } from '@pyreon/zero/link'
-
-function CardLink(props: LinkProps) {
-  const link = useLink(props)
-  return (
-    <div
-      ref={link.ref}
-      class={() => \`card \${link.classes()}\`}
-      onClick={link.handleClick}
-      onMouseEnter={link.handleMouseEnter}
-      onTouchStart={link.handleTouchStart}
-    >
-      {props.children}
-    </div>
-  )
-}`,
-      mistakes: [
-        "Reading `link.classes` as a plain string — it's a `() => string` accessor. Call it inside reactive scopes (JSX expression thunks, `class={link.classes}`) so the active class updates on route change",
-        "Forgetting to wire `link.ref` to the root element under `prefetch=\"viewport\"` — without the ref the IntersectionObserver has nothing to observe; viewport-based prefetch never fires",
-        "Calling `link.handleClick(e)` synchronously in the component body — handlers are meant to be JSX event props (`onClick={link.handleClick}`); synchronous invocation in the render body triggers `router.push` during render which the lint rule `no-imperative-navigate-in-render` flags",
-        "Mixing `useLink` + a router instance from a different `RouterProvider` — `useLink` reads the nearest router context; multi-router apps need explicit context boundaries",
-        "Treating `useLink` as setup-only (calling it conditionally inside an effect) — like all hooks, call it at the top of the component body. The ref / handlers are stable across re-renders",
-        "Forgetting that `external: true` bypasses the click handler entirely — `useLink` still returns handlers but `handleClick`'s body short-circuits when `props.external` is true; the wrapped element should let the native anchor `target=\"_blank\"` semantics handle the rest",
-      ],
-      seeAlso: ['Link', 'createLink', 'UseLinkReturn'],
-    },
-    {
-      name: 'createLink',
-      kind: 'function',
-      signature:
-        'function createLink(Component: (p: LinkRenderProps) => any): (props: LinkProps) => any',
-      summary:
-        'HOC that wraps any component with link behavior. The wrapped component receives `LinkRenderProps` with all handlers + state pre-wired (`href`, `ref`, `onClick`, `onMouseEnter`, `onTouchStart`, `isActive`, `isExactActive`, `class`, `target`, `rel`). Use this to build styled link variants (button-links, card-links, design-system anchors) without re-implementing the prefetch + active-state machine.',
-      example: `import { createLink } from '@pyreon/zero/link'
-
-const ButtonLink = createLink((props) => (
-  <button
-    ref={props.ref}
-    class={props.class}
-    onClick={props.onClick}
-    onMouseEnter={props.onMouseEnter}
-  >
-    {props.children}
-  </button>
-))
-
-<ButtonLink href="/dashboard" activeClass="active">Dashboard</ButtonLink>`,
-      mistakes: [
-        "Not forwarding `props.ref` to the rendered element — the prefetch IntersectionObserver and active-state observer both need a real DOM ref to attach to",
-        "Calling the user-provided `props.class` as a function in JSX (`class={props.class()}`) — `class` is a string-or-accessor union; pass it directly (`class={props.class}`) and let the renderer call it if needed",
-        "Forgetting `onTouchStart` — mobile devices don't fire mouseenter; without `onTouchStart` mobile users get no prefetch benefit",
-        "Re-rendering the wrapped component on every router event — the HOC calls `useLink` ONCE per component instance, returns stable handlers, and the route signal is reactive at the granularity of `isActive` / `classes`. Don't memoize the wrapper output manually",
-        "Building separate wrappers for `<button>` vs `<a>` vs `<div>` instead of having ONE styled wrapper that accepts a `tag` prop — `createLink` only handles the link logic; the rendered tag choice is the consumer's structural decision",
-        "Expecting `createLink` to handle `external: true` semantics on a non-anchor component — `target` and `rel` are forwarded as RenderProps but `<button target=\"_blank\">` does nothing; for external links rendered as buttons, the consumer must handle `window.open()` explicitly",
-      ],
-      seeAlso: ['Link', 'useLink', 'LinkRenderProps'],
-    },
-    {
-      name: 'prefetchRoute',
-      kind: 'function',
-      signature: 'function prefetchRoute(href: string): void',
-      summary:
-        'Imperatively prefetch a route\'s JS chunk by injecting `<link rel="prefetch">` + `<link rel="modulepreload">` into `document.head`. Deduplicates — calling twice with the same `href` is a no-op. Backed by an LRU cache (MAX 200 entries) that evicts oldest entries AND removes their DOM nodes to prevent head-bloat across long SPA sessions.',
-      example: `import { prefetchRoute } from '@pyreon/zero/link'
-
-// On user hovering a card, prefetch the linked route's chunk
-<Card onMouseEnter={() => prefetchRoute('/posts/' + post.id)}>...</Card>`,
-      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',
-      signature:
-        '<Image src={url} alt={alt} width={w} height={h} priority={false} loading="lazy" placeholder={blurUrl} />',
-      summary:
-        "Default optimized image — lazy loading via IntersectionObserver, automatic width/height for CLS prevention, responsive srcset, multi-format via `<picture>`, blur-up placeholder, `fetchPriority=\"high\"` for LCP images. Built on `createImage` so consumers can layer rocketstyle / custom wrappers on top via `createImage(MyStyledImage)` without losing the optimization pipeline. The `raw: true` escape hatch returns a bare `<img>` (no container, no lazy load, no aspect-ratio enforcement).",
-      example: `import { Image } from '@pyreon/zero/image'
-import hero from './hero.jpg?optimize'
-
-// With imagePlugin — spreads optimized srcset + formats + dimensions
-<Image {...hero} alt="Hero" priority />
-
-// Manual
-<Image src="/hero.jpg" alt="Hero" width={1200} height={630} />
-
-// Raw mode — skip all optimization wrappers (custom layout)
-<Image src="/bg.jpg" alt="" width={400} height={300} raw />`,
-      mistakes: [
-        "Forgetting `width` + `height` — both are REQUIRED for CLS prevention. The `aspect-ratio` CSS is computed from these; omitting them produces layout shift when the image loads",
-        "Setting `priority` on below-the-fold images — `priority` disables lazy loading AND adds `fetchPriority=\"high\"`. Reserve it for the LCP image only (typically the hero)",
-        "Setting `loading=\"eager\"` AND `priority` — they're redundant; `priority` already implies eager. Pick one (`priority` is the LCP-marker; `loading=\"eager\"` is the no-priority eager hint)",
-        "Using `placeholder` as a full-resolution image — it should be a tiny base64 data URI or a /placeholder.jpg (~1-2 KB). Large placeholders defeat the purpose by blocking initial paint",
-        "Spreading `imagePlugin` output (`{...hero}`) WITHOUT `alt` — `alt` is required for accessibility AND not auto-derived by the plugin. The TypeScript type enforces this",
-        "Wrapping `<Image>` in a `<picture>` manually for WebP/AVIF — `formats` already does this via `imagePlugin`. Manual `<picture>` defeats the optimization",
-      ],
-      seeAlso: ['useImage', 'createImage', 'ImageProps', 'ImageRenderProps'],
-    },
-    {
-      name: 'useImage',
-      kind: 'hook',
-      signature: 'function useImage(props: ImageProps): UseImageReturn',
-      summary:
-        "Composable that returns resolved image attributes + signals — `{ containerRef, inView, loaded, src, srcSet, sizes, aspectRatio, containerStyle, imageStyle, placeholderStyle, loading, fetchPriority, handleLoad, formats, hasFormats }`. Use for full control when `createImage`'s default `<div><img/></div>` structure is wrong (e.g. `<figure>` + `<figcaption>`, custom container layouts, overlay elements). Reactive accessors (`src`, `srcSet`, `imageStyle`, `placeholderStyle`) re-evaluate on `inView()` flip — wire them as JSX expressions for fine-grained updates.",
-      example: `import { useImage } from '@pyreon/zero/image'
-
-function FigureImage(props: ImageProps) {
-  const img = useImage(props)
-  return (
-    <figure ref={img.containerRef} style={img.containerStyle}>
-      <img
-        src={img.src}
-        srcSet={img.srcSet}
-        sizes={img.sizes}
-        alt={props.alt}
-        width={props.width}
-        height={props.height}
-        loading={img.loading}
-        onLoad={img.handleLoad}
-        style={img.imageStyle}
-      />
-      <figcaption>{props.alt}</figcaption>
-    </figure>
-  )
-}`,
-      mistakes: [
-        "Reading `img.src` as a plain string — it's a `() => string` accessor that returns empty string until `inView()` triggers. Pass it as a JSX attribute (`src={img.src}`) so the renderer wraps it in a reactive binding",
-        "Forgetting to wire `img.containerRef` — without the ref, IntersectionObserver has nothing to observe; lazy images never enter view, never load",
-        "Calling `img.handleLoad()` from your own code — `handleLoad` is the `<img>`'s `onLoad` handler. Wire it as `onLoad={img.handleLoad}`; calling it manually marks the image as loaded prematurely (placeholder fades out before the image arrives)",
-        "Spreading `useImage` return on the `<img>` directly (`<img {...img}/>`) — most fields aren't `<img>` attributes (`containerRef`, `aspectRatio`, `imageStyle`, `placeholderStyle`, `hasFormats`). Pick the fields you need",
-        "Ignoring `img.hasFormats` — if `formats` is set, you should render a `<picture>` with per-format `<source>` elements; `img.srcSet()` returns empty string under formats mode (the format-specific srcsets live on `<source>`)",
-        "Treating `useImage` as setup-only — like all Pyreon hooks, call it at the top of the component body. The container ref + signals are stable across re-renders",
-      ],
-      seeAlso: ['Image', 'createImage', 'UseImageReturn'],
-    },
-    {
-      name: 'createImage',
-      kind: 'function',
-      signature:
-        'function createImage(Component: (p: ImageRenderProps) => any): (props: ImageProps) => any',
-      summary:
-        'HOC that wraps any component with image optimization. The wrapped component receives `ImageRenderProps` with pre-rendered `placeholder` JSX (null when no placeholder set) + pre-rendered `image` JSX (bare `<img>` OR `<picture>` tree depending on formats), the container ref, container styles, and class. Consumer composes those pieces with whatever wrapper element / extra layout (overlay, badge, caption).',
-      example: `import { createImage } from '@pyreon/zero/image'
-
-const FigureImage = createImage((props) => (
-  <figure ref={props.containerRef} class={props.class} style={props.containerStyle}>
-    {props.placeholder}
-    {props.image}
-    <figcaption>Caption</figcaption>
-  </figure>
-))
-
-<FigureImage src="/hero.jpg" alt="Hero" width={1200} height={630} placeholder="/blur.jpg" />`,
-      mistakes: [
-        "Forgetting to render `props.image` — without it, the actual `<img>` never appears in the DOM. The HOC pre-renders the bare `<img>` or `<picture>` tree; the consumer just needs to place it",
-        "Conditionally rendering `props.placeholder` — it's already conditional (null when no `placeholder` prop set). Always render it; React/Pyreon ignore null children",
-        "Forwarding `props.containerStyle` to a child instead of the container — the styles (aspect-ratio, position: relative, overflow: hidden) MUST apply to the element holding `props.containerRef`. Otherwise CLS prevention breaks AND IntersectionObserver observes the wrong element",
-        "Building `placeholder` JSX from scratch — `createImage` already constructs the blur-up `<img>` with the right styles. Just render `{props.placeholder}`; don't reach into `useImage().placeholderStyle()` manually",
-        "Passing `raw: true` to a `createImage`-wrapped component — `raw` short-circuits BEFORE `createImage`'s wrapped component runs (returns bare `<img>`). The wrapped component never receives `ImageRenderProps` in raw mode. Documented as the no-optimization escape hatch",
-        "Re-implementing the `<picture>` switch — `props.image` already handles the formats branch. Wrapping `props.image` in another `<picture>` produces nested `<picture>` which browsers ignore (the outer wins)",
-      ],
-      seeAlso: ['Image', 'useImage', 'ImageRenderProps'],
-    },
-
-    {
-      name: 'Script',
-      kind: 'component',
-      signature:
-        '<Script src={url} strategy="afterHydration" id={uniqueId} async={true} onLoad={cb} onError={cb} />',
-      summary:
-        "Default optimized third-party script loader. Strategies: `beforeHydration` (in HTML already), `afterHydration` (inject on mount — default), `onIdle` (via `requestIdleCallback`), `onInteraction` (on first click/scroll/keydown/touchstart), `onViewport` (when sentinel enters viewport). Built on `createScript` — consumers can render loading indicators, retry buttons, or analytics-readiness gates via `createScript(MyCustom)` without re-implementing the strategy machine. Returns a 0×0 sentinel `<div>` for `onViewport` strategy, `null` otherwise.",
-      example: `import { Script } from '@pyreon/zero/script'
-
-// Load analytics after page is interactive
-<Script src="https://analytics.example.com/script.js" strategy="onIdle" id="analytics" />
-
-// Load chat widget when scrolled into view
-<Script src="/chat-widget.js" strategy="onViewport" />
-
-// Inline script with deferred execution
-<Script strategy="afterHydration">{\`console.log("App hydrated!")\`}</Script>`,
-      mistakes: [
-        "Setting `strategy=\"onInteraction\"` for analytics that needs first-paint metrics — by definition, onInteraction loads AFTER the first user interaction; first-paint metrics from such a script are useless. Use `onIdle` for analytics that needs LCP / FCP capture",
-        "Forgetting `id` for scripts that might mount in multiple places — without `id`, dedup doesn't fire and the script loads twice. Always provide `id` for analytics / tracking / third-party widgets",
-        "Mixing `src` + `children` — `children` is the inline script body; `src` is the URL. If BOTH are set, `src` wins and `children` is ignored (the dom script.src takes precedence). Use one or the other",
-        "`strategy=\"beforeHydration\"` without actually putting the `<script>` in the HTML — beforeHydration is a NO-OP marker; the script must already exist in the SSR-emitted HTML. Use SSR `<script>` tag injection in your entry-server, not `<Script>`",
-        "Setting `async={false}` for non-critical scripts — `async={false}` blocks parser; reserve for scripts that MUST execute in order (rare for third-party). Default is true",
-        "Expecting `onError` to fire for inline scripts — only `src`-based scripts trigger onerror via the browser. Inline scripts (`children`) execute synchronously; runtime exceptions don't propagate to `onError`",
-      ],
-      seeAlso: ['useScript', 'createScript', 'ScriptProps', 'ScriptStrategy'],
-    },
-    {
-      name: 'useScript',
-      kind: 'hook',
-      signature: 'function useScript(props: ScriptProps): UseScriptReturn',
-      summary:
-        "Composable returning script load-state signals + sentinel ref — `{ sentinelRef, loaded, errored, pending, needsSentinel, load }`. Reactive signals (`loaded`, `errored`, `pending`) let consumers render loading indicators, retry buttons, or analytics-readiness gates without re-implementing the strategy machine. `needsSentinel` is true ONLY for `onViewport` strategy. `load()` is the imperative escape hatch (strategy normally triggers it; rarely needed).",
-      example: `import { useScript } from '@pyreon/zero/script'
-
-function TrackedScript(props: ScriptProps) {
-  const s = useScript(props)
-  return (
-    <>
-      {() => s.pending() && <Spinner />}
-      {() => s.errored() && <button onClick={() => location.reload()}>Retry</button>}
-      {s.needsSentinel && <div ref={s.sentinelRef} style="width:0;height:0" />}
-    </>
-  )
-}`,
-      mistakes: [
-        "Reading `s.loaded` / `s.errored` / `s.pending` as booleans — they're `() => boolean` accessors. Call them inside reactive scopes (JSX thunks, `effect()`) so the UI updates when state changes",
-        "Forgetting `s.needsSentinel` and always rendering a sentinel — non-onViewport strategies don't need one; rendering a div anyway is harmless but reads as wrong",
-        "Calling `s.load()` in the component body — the strategy already calls it (afterHydration runs it on mount, onInteraction on first interaction, etc.). Manual `load()` typically duplicates the request (unless `id` is set for dedup)",
-        "Wiring `s.sentinelRef` to a non-DOM element — IntersectionObserver needs a real Element. A `null` or detached ref means viewport-based load never fires",
-        "Expecting `s.pending()` to start true for `afterHydration` — it doesn't. `afterHydration` is the synchronous-load strategy; pending only starts true for `onIdle` / `onInteraction` / `onViewport` (where the load is deferred)",
-        "Using `s.errored()` to suppress retry-on-mount — `errored` is set when the script's onerror fires, NOT when a previous mount errored. Multi-mount apps need their own retry budget tracking",
-      ],
-      seeAlso: ['Script', 'createScript', 'UseScriptReturn'],
-    },
-    {
-      name: 'createScript',
-      kind: 'function',
-      signature:
-        'function createScript(Component: (p: ScriptRenderProps) => any): (props: ScriptProps) => any',
-      summary:
-        "HOC that wraps any component with script load behavior. The wrapped component receives `ScriptRenderProps` with the sentinel ref, load-state signals (`loaded`, `errored`, `pending`), and `needsSentinel` flag. Use this to render loading indicators, retry UI, or analytics-readiness gates around the script load lifecycle.",
-      example: `import { createScript } from '@pyreon/zero/script'
-
-const StatusScript = createScript((props) => (
-  <div>
-    {() => props.pending() && <span>Loading analytics...</span>}
-    {() => props.errored() && <span>Analytics failed to load</span>}
-    {props.needsSentinel && <div ref={props.sentinelRef} style="width:0;height:0" />}
-  </div>
-))
-
-<StatusScript src="/analytics.js" strategy="onIdle" id="analytics" />`,
-      mistakes: [
-        "Always rendering `<div ref={props.sentinelRef} .../>` regardless of `needsSentinel` — for non-onViewport strategies the ref is `undefined`. Gate the sentinel render on `props.needsSentinel`",
-        "Calling `props.loaded()` / `props.errored()` / `props.pending()` outside reactive scopes — they're accessors; outside JSX thunks they capture the value at setup time and never update",
-        "Forgetting that the wrapped component's render output doesn't affect script loading — the script load fires in `useScript`'s `onMount` regardless of what the wrapped component returns (null, div, fragment). The wrapper is purely a UI surface",
-        "Building a custom strategy machine in the wrapped component — the strategy is already resolved by `useScript`. The wrapped component just observes the resulting signals",
-        "Forwarding `props.sentinelRef` to multiple elements — `useIntersectionObserver` observes ONE element. Multi-ref forwarding produces undefined behavior (the last-attached element wins)",
-        "Expecting the wrapped component to fire `onLoad` / `onError` — those callbacks are on the `ScriptProps` (passed to the OUTER component), not on the wrapped component. The wrapped component reads `props.loaded()` / `props.errored()` signals to react to the same events",
-      ],
-      seeAlso: ['Script', 'useScript', 'ScriptRenderProps'],
-    },
-  ],
-  gotchas: [
-    'mode: \'ssg\' returns Plugin[] (the SSG plugin auto-attaches a companion `ssgPlugin()`); Vite\'s plugins array flattens nested arrays so `plugins: [pyreon(), zero()]` works as-is.',
-    {
-      label: 'i18n strategies',
-      note: '`prefix-except-default` (default) keeps the default locale unprefixed (SEO-canonical for primary-locale apps). `prefix` prefixes every locale including default (best when no locale is primary). Switching strategies changes the dist filesystem layout — plan migration paths if you flip mid-product.',
-    },
-    {
-      label: 'getStaticPaths × i18n cardinality',
-      note: '3 IDs × 3 locales × 2 strategies of accidents = bigger SSG output than you expected. Use `ssg.concurrency` to parallelize the render; use `ssg.onProgress` to surface heartbeat lines on long builds (CI silent-stretches look hung otherwise).',
-    },
-    {
-      label: 'Adapter.build invocation',
-      note: 'Auto-invoked in SSG `closeBundle` AFTER path render. SSR-mode auto-invoke is NOT yet wired — SSR consumers handle their own server bundle.',
-    },
-    {
-      label: 'Locale-aware RouterLink — not yet shipped',
-      note: 'RouterLinks under i18n duplication emit LITERAL hrefs from their `to` prop. Cross-locale navigation falls through to the default-locale route. A locale-aware-link feature is a future PR; for now, write per-locale hrefs explicitly or use the router\'s programmatic navigation in handlers.',
-    },
-  ],
-})