@pyreon/mcp 0.15.0 → 0.18.0

package/src/api-reference.ts

@@ -68,6 +68,21 @@ effect(() => {
 - Creating signals inside an effect — they re-create on every run; create once outside`,
   },
 
+  'reactivity/renderEffect': {
+    signature: '(fn: () => void) => () => void',
+    example: `// Inside a custom DOM helper that updates a text node:
+const node = document.createTextNode('')
+const dispose = renderEffect(() => {
+  node.data = String(count())
+})
+// Re-runs only when count() changes; lighter than effect() but no
+// onCleanup support, no scope auto-disposal, no error-handler routing.`,
+    notes: `DOM-specific effect with a lighter dependency tracking path — uses a local array for deps instead of the full \`EffectScope\` integration. Used internally by \`_bind\` / \`_tpl\` for compiled-template DOM updates. **Prefer \`effect()\` for general use**; reach for \`renderEffect()\` only when you're hand-writing DOM update logic and have measured the overhead difference. Returns a dispose function (not an \`Effect\` object — different shape from \`effect()\`). See also: effect, computed.`,
+    mistakes: `- Calling \`onCleanup()\` inside \`renderEffect()\` — not supported; only \`effect()\` collects cleanups. Use \`effect()\` if you need cleanup callbacks
+- Expecting \`renderEffect()\` to auto-dispose with the surrounding scope — it does NOT register with \`EffectScope\`. Component-scoped DOM effects should use \`effect()\` so they tear down on unmount
+- Reaching for \`renderEffect()\` as the default — \`effect()\` is the canonical primitive. The performance delta only matters in extreme hot paths (1000+ DOM nodes), never in component-level code`,
+  },
+
   'reactivity/batch': {
     signature: '(fn: () => void) => void',
     example: `const a = signal(1)
@@ -82,6 +97,18 @@ batch(() => {
 - Forgetting \`batch()\` when updating 3+ related signals — causes N intermediate re-renders`,
   },
 
+  'reactivity/nextTick': {
+    signature: '() => Promise<void>',
+    example: `count.set(5)
+// Effects haven't run yet (sync writes are queued)
+await nextTick()
+// Now everything is flushed — DOM reflects count = 5
+expect(node.textContent).toBe('5')`,
+    notes: `Returns a promise that resolves after the next microtask. Use to await pending reactive updates — every signal write that happens before \`nextTick()\` is fully flushed (effects ran, computeds settled, DOM patched) by the time the promise resolves. Equivalent to Vue's \`nextTick\`. Useful in tests and in code that needs to read the post-update DOM state. See also: batch.`,
+    mistakes: `- Awaiting \`nextTick()\` inside a \`batch()\` callback — pointless; the batch flushes when the callback returns, not when the microtask drains. Move the await outside \`batch()\`
+- Using \`nextTick()\` to defer work — it doesn't schedule anything; it just resolves on the next microtask. Use \`setTimeout\` / \`requestAnimationFrame\` for actual deferral`,
+  },
+
   'reactivity/onCleanup': {
     signature: '(fn: () => void) => void',
     example: `effect(() => {
@@ -101,7 +128,50 @@ batch(() => {
 })`,
     notes: 'Explicit reactive watcher — tracks `source` and fires `callback` when it changes. Unlike `effect()`, the callback receives both `next` and `prev` values and does NOT auto-track signals read inside the callback body. `source` is evaluated at setup time to establish tracking; reading browser globals there still fires SSR lint rules. Returns a dispose function. See also: effect, computed.',
     mistakes: `- Reading browser globals in the \`source\` function — it runs at setup time (not just in mounted context), so \`no-window-in-ssr\` fires on \`window.X\` there
-- Expecting signals read inside the \`callback\` to be tracked — only the \`source\` function establishes tracking; the callback is untracked`,
+- Expecting signals read inside the \`callback\` to be tracked — only the \`source\` function establishes tracking; the callback is untracked
+- Forgetting to return a cleanup function from the callback — \`watch\` honors a returned function as a cleanup that runs before each re-run AND on dispose. Useful for cancelling in-flight requests, clearing timers, or removing listeners attached on the previous run`,
+  },
+
+  'reactivity/createSelector': {
+    signature: '<T>(source: () => T) => (value: T) => boolean',
+    example: `const selectedId = signal<string | null>(null)
+const isSelected = createSelector(() => selectedId())
+
+// In each row's render — O(1) selection updates regardless of N rows:
+<For each={rows} by={r => r.id}>{row => (
+  <li class={() => (isSelected(row.id) ? 'selected' : '')}>
+    {row.label}
+  </li>
+)}</For>`,
+    notes: `Create an O(1) equality selector — returns a reactive predicate that fires only when the previously-selected and newly-selected values' subscribers are affected. Unlike a plain \`() => source() === value\` (which re-evaluates for every row in a list), this only triggers TWO subscribers per source change (deselected + newly selected) regardless of list size. Critical for keyed-list selection patterns. See also: signal, computed.`,
+    mistakes: `- Using a plain \`() => source() === value\` in lists — every row subscribes to source; selecting a row notifies ALL N rows (O(N))
+- Calling \`isSelected\` outside a reactive scope — returns the current value but doesn't subscribe
+- Using \`createSelector\` for non-equality predicates — it's purpose-built for \`===\` matching; for ranges or filters, use \`computed()\``,
+  },
+
+  'reactivity/cell': {
+    signature: '<T>(value: T) => Cell<T>',
+    example: `import { cell } from '@pyreon/reactivity'
+
+// Create a cell:
+const label = cell('Initial')
+
+// Read (no tracking — read inside an effect does NOT subscribe):
+label.peek()             // 'Initial'
+
+// Write:
+label.set('Updated')
+label.update(s => s + '!')
+
+// Subscribe directly (returns disposer):
+const dispose = label.subscribe(() => console.log(label.peek()))
+
+// Fire-and-forget — no disposer (saves 1 closure allocation):
+label.listen(() => console.log('changed'))`,
+    notes: `Lightweight reactive primitive — class-based alternative to \`signal()\`. **1 object allocation vs \`signal()\`'s ~6 closures**, single-listener fast path (no Set allocated when ≤1 subscriber), methods on prototype shared across instances. **NOT callable as a getter** — does not integrate with effect dependency tracking. Use when you need reactive state but plan to subscribe directly via \`.subscribe()\` / \`.listen()\`, NOT via \`effect()\`. Ideal for keyed-list row labels where the subscription lifetime equals the row's lifetime. See also: signal.`,
+    mistakes: `- Using \`label()\` to read — Cells are NOT callable. Use \`label.peek()\` to read
+- Reading \`label.peek()\` inside \`effect()\` and expecting tracked re-runs — Cells don't integrate with effect tracking. Use \`signal()\` if you need automatic dependency tracking
+- Using \`cell()\` for ALL reactive state — only switch from \`signal()\` when you've measured allocation pressure (1000+ instances) AND you don't need effect-based subscriptions`,
   },
 
   'reactivity/createStore': {
@@ -112,10 +182,91 @@ batch(() => {
 })
 store.todos[0].done = true   // fine-grained — only 'done' subscribers fire
 store.todos.push({ text: 'Build app', done: false })  // array methods work`,
-    notes: 'Create a deeply reactive proxy-based object. Mutations at any depth trigger fine-grained updates — `store.todos[0].done = true` only re-runs effects that read `store.todos[0].done`, not effects that read `store.todos.length` or other items. No immer, no spread-copy, no `produce()` — just mutate. Works with nested objects, arrays, Maps, and Sets. See also: signal.',
+    notes: 'Create a deeply reactive proxy-based object. Mutations at any depth trigger fine-grained updates — `store.todos[0].done = true` only re-runs effects that read `store.todos[0].done`, not effects that read `store.todos.length` or other items. No immer, no spread-copy, no `produce()` — just mutate. Works with nested plain objects and arrays. Built-in types with internal slots (`Map`, `Set`, `WeakMap`, `WeakSet`, `Date`, `RegExp`, `Promise`, `Error`) are returned raw and are NOT deeply reactive — they fail the Proxy internal-slot check on every method call. Replace the whole field (`store.users = new Map(store.users)`) to trigger reactivity for these. See also: signal.',
     mistakes: `- Replacing the entire store object — \`store = { ... }\` replaces the variable, not the proxy. Mutate properties instead: \`store.filter = "active"\`
 - Destructuring store properties at setup — \`const { filter } = store\` captures the value once, losing reactivity. Read \`store.filter\` inside reactive scopes
-- Using \`createStore\` for simple scalar state — use \`signal()\` for primitives; \`createStore\` adds proxy overhead that only pays off for nested objects`,
+- Using \`createStore\` for simple scalar state — use \`signal()\` for primitives; \`createStore\` adds proxy overhead that only pays off for nested objects
+- Expecting fine-grained reactivity inside Map/Set/Date/RegExp/Promise — these are returned raw because Proxy can't intercept methods that rely on internal slots. Mutating the raw instance (\`store.users.set(...)\`) does NOT notify subscribers. Replace the whole field (\`store.users = new Map(store.users)\`) to trigger reactivity`,
+  },
+
+  'reactivity/createResource': {
+    signature: '<T, P>(source: () => P, fetcher: (param: P) => Promise<T>) => Resource<T>',
+    example: `const userId = signal(1)
+const user = createResource(
+  () => userId(),
+  (id) => fetch(\`/api/users/\${id}\`).then(r => r.json()),
+)
+effect(() => {
+  if (user.loading()) return
+  if (user.error()) return console.error(user.error())
+  console.log(user.data())
+})
+userId.set(2)            // auto-refetches
+user.refetch()           // explicit refetch with current source
+user.dispose()           // stop tracking, discard in-flight response`,
+    notes: 'Async data primitive. Auto-fetches whenever `source()` changes — `data`, `loading`, `error` are signals readable inside effects. Stale-response guarded via internal `requestId` (typing fast then slow does not flicker old data). `refetch()` re-runs the fetcher with the current source value. **`dispose()` MUST be called for resources created outside an `EffectScope`** — otherwise the source-tracking effect leaks for the lifetime of the program. See also: signal, effect, effectScope.',
+    mistakes: `- Forgetting \`dispose()\` for resources outside an EffectScope — the internal source-tracking effect runs forever, leaking memory and unbounded fetch calls on source changes
+- Calling \`refetch()\` after \`dispose()\` — silently no-ops; check disposed state on your end if needed
+- Reading \`data()\` without checking \`loading()\` / \`error()\` — undefined values flow through; gate the read on those signals
+- Expecting an in-flight response to update the resource AFTER \`dispose()\` — the response is discarded by design (stale-id check), \`loading\` may stay frozen at its dispose-time value
+- Reading signals INSIDE the fetcher and expecting tracked re-runs — only \`source()\` is tracked; signals read inside \`fetcher\` are read once per call without subscription`,
+  },
+
+  'reactivity/reconcile': {
+    signature: '<T extends object>(source: T, target: T) => void',
+    example: `const state = createStore({ user: { name: 'Alice', age: 30 }, items: [] })
+
+// API response arrives — pure replacement payload:
+reconcile(
+  { user: { name: 'Alice', age: 31 }, items: [{ id: 1 }] },
+  state,
+)
+// → only state.user.age signal fires (name unchanged)
+// → state.items[0] is newly created, length signal fires`,
+    notes: 'Surgically diff a new value into an existing `createStore` proxy. Walks both trees in parallel and only calls `.set()` on signals whose value actually changed — unchanged subtrees do NOT re-run their effects. Ideal for applying API responses to a long-lived store: only the truly-changed fields trigger updates, even if you receive a fully-replacement payload from the server. Arrays reconcile by index; excess elements are removed. See also: createStore, signal.',
+    mistakes: `- Passing a non-store as \`target\` — \`reconcile\` requires a \`createStore\` proxy; for plain objects, just assign
+- Expecting reconciliation by key for arrays — arrays are reconciled BY INDEX. For keyed list reconciliation, use a Map keyed by id and reconcile each entry by key, OR replace the array reference (which \`<For>\` reconciles via \`by\`)
+- Using \`reconcile\` inside an effect — it triggers writes; you'd cycle. Call it outside reactive scopes (e.g. in a query callback or event handler)`,
+  },
+
+  'reactivity/isStore': {
+    signature: '(value: unknown) => boolean',
+    example: `const a = createStore({ x: 1 })
+const b = { x: 1 }
+isStore(a)  // true
+isStore(b)  // false
+isStore(null)  // false (null-safe)`,
+    notes: 'Type guard — returns `true` if the value is a `createStore` proxy (recognized via an internal symbol marker). Use to differentiate reactive stores from plain objects in code that handles both shapes (e.g. helpers that conditionally `reconcile()` vs assign). See also: createStore, reconcile.',
+    mistakes: `- Using \`isStore\` to detect ANY proxy — it's specific to Pyreon's store proxies. Other proxies return \`false\`
+- Calling on \`null\` / \`undefined\` and expecting a throw — null-safe; returns \`false\``,
+  },
+
+  'reactivity/shallowReactive': {
+    signature: '<T extends object>(initial: T) => T',
+    example: `const store = shallowReactive({ user: { name: 'Alice' }, count: 0 })
+effect(() => store.count)        // tracks store.count
+effect(() => store.user)         // tracks store.user reference (not its contents)
+store.user.name = 'Bob'          // does NOT trigger any effect (nested mutation)
+store.count = 5                  // triggers count effect
+store.user = { name: 'Bob' }     // triggers user effect (reference replacement)`,
+    notes: 'Create a SHALLOW reactive store — only top-level mutations trigger updates. Nested objects are NOT auto-wrapped; reading a nested object returns the raw reference, and mutating it does NOT trigger any effect. Replacing the top-level reference DOES trigger reactivity. Use when nested data is immutable (frozen API responses), when you want explicit control over which subtrees are reactive, or when you need to store class instances/third-party objects without paying the deep-proxy overhead. Vue 3 parity. See also: createStore, markRaw.',
+    mistakes: `- Expecting nested mutations to trigger effects — they don't. Use \`createStore\` if you need deep reactivity, or replace the top-level reference (\`store.user = { ...store.user, name: 'Bob' }\`)
+- Mixing shallow + deep on the same raw object — \`createStore(raw)\` and \`shallowReactive({ wrapper: raw })\` produce DIFFERENT proxies (separate caches). Pick one shape per data flow`,
+  },
+
+  'reactivity/markRaw': {
+    signature: '<T extends object>(value: T) => T',
+    example: `import { markRaw, createStore } from '@pyreon/reactivity'
+
+class Editor { /* ... */ }
+const ed = markRaw(new Editor())   // skips proxy
+const store = createStore({ editor: ed })
+store.editor === ed                 // true — raw reference preserved
+store.editor.someMethod()           // works — class methods see real receiver`,
+    notes: `Mark an object as RAW — \`createStore\` and \`shallowReactive\` will return it unwrapped. Useful for class instances, third-party objects, DOM nodes, or any shape that shouldn't be deeply proxied (Vue 3 parity). Marking is one-way: there's no \`unmarkRaw\`. Mark BEFORE the object enters a store; marking after wrap doesn't unwrap an existing proxy. See also: createStore, shallowReactive.`,
+    mistakes: `- Marking an object AFTER it's been wrapped — the existing proxy is unaffected. Mark before the object enters any store
+- Expecting \`markRaw(obj)\` to return a different object — it mutates \`obj\` and returns the SAME reference (with the marker symbol attached)
+- Using markRaw on plain data objects to "skip" deep wrap — for that, use \`shallowReactive\`. markRaw is for class instances and externally-managed shapes`,
   },
 
   'reactivity/untrack': {
@@ -127,6 +278,132 @@ store.todos.push({ text: 'Build app', done: false })  // array methods work`,
     notes: `Execute a function reading signals WITHOUT subscribing to them. Alias for \`runUntracked\`. Use inside effects when you need to read a signal's current value as a one-shot snapshot without the effect re-running when that signal changes. See also: signal, effect.`,
     mistakes: '- Using `untrack` as the default — signals should be tracked by default; `untrack` is the escape hatch for specific optimization or loop-prevention cases',
   },
+
+  'reactivity/effectScope': {
+    signature: '() => EffectScope',
+    example: `import { effectScope, signal, effect } from '@pyreon/reactivity'
+
+const scope = effectScope()
+const count = signal(0)
+
+scope.runInScope(() => {
+  effect(() => console.log(count()))    // tracked by scope
+})
+
+count.set(5)   // logs 5
+scope.stop()   // tears down all effects in the scope
+count.set(10)  // no log — effect was disposed`,
+    notes: `Create an \`EffectScope\` — a container that auto-tracks effects/computeds created inside \`scope.runInScope(fn)\` and disposes them all at once via \`scope.stop()\`. \`@pyreon/core\`'s \`mountReactive\` uses this internally for component lifetime management. **Always use a scope for effects created outside a component's setup phase** (e.g. in event handlers, route loaders, or async-await chains) — without one, effects leak for the lifetime of the program. See also: effect, getCurrentScope, onScopeDispose.`,
+    mistakes: `- Forgetting \`scope.stop()\` — effects leak for the lifetime of the program; same shape as forgetting \`dispose()\` on a top-level \`effect()\`
+- Creating effects outside \`runInScope(fn)\` and expecting them to be tracked — effects must run during the synchronous body of \`runInScope\` to register with the scope
+- Stopping a scope that has pending updates — in-flight microtasks may still fire \`onUpdate\` hooks; design for idempotency or check \`isActive\` before writes`,
+  },
+
+  'reactivity/onScopeDispose': {
+    signature: '(fn: () => void) => void',
+    example: `scope.runInScope(() => {
+  const ws = new WebSocket(url)
+  onScopeDispose(() => ws.close())
+  // ws.close() runs when scope.stop() is called
+})`,
+    notes: 'Register a callback to run when the current `EffectScope` stops. Vue 3 parity. Captures the AMBIENT scope at registration time, so it must be called inside `scope.runInScope(fn)`. Calling outside any scope is a no-op (with a dev warning). Use for resource cleanup tied to scope lifetime — timers, listeners, external subscriptions. Equivalent to `getCurrentScope()?.add({ dispose: fn })` but without the boilerplate. See also: effectScope, getCurrentScope, onCleanup.',
+    mistakes: `- Calling outside any scope — silently no-ops in production, dev warns. The callback is dropped on the floor; verify with \`getCurrentScope()\` before calling if scope is uncertain
+- Expecting the callback to run on EFFECT cleanup — \`onScopeDispose\` fires only on \`scope.stop()\`. For per-effect cleanup, use \`onCleanup()\` inside the effect body or return a cleanup function from it
+- Using outside \`runInScope\` and inside an effect callback — the effect captures whatever scope was ambient when the effect SET UP, not when the registration runs. Effects re-run later may see a different ambient scope; register at setup, not in the body`,
+  },
+
+  'reactivity/getCurrentScope': {
+    signature: '() => EffectScope | null',
+    example: `import { getCurrentScope } from '@pyreon/reactivity'
+
+function myReactiveResource() {
+  const scope = getCurrentScope()
+  if (scope) {
+    // Inside a component — register cleanup with the component's scope
+    scope.add({ dispose: cleanup })
+  } else {
+    // Top-level / standalone — caller must call dispose() manually
+    console.warn('myReactiveResource: no active scope; remember to dispose')
+  }
+}`,
+    notes: `Returns the currently active \`EffectScope\` (the one whose \`runInScope(fn)\` is on the stack), or \`null\` if no scope is active. Use to register cleanup with the surrounding scope, or to detect "am I inside a component lifetime?" — useful for library code that wants to register an effect with the consumer's scope rather than the global one. See also: effectScope, setCurrentScope.`,
+    mistakes: `- Calling \`getCurrentScope()\` outside any scope and expecting a default — returns \`null\`. Handle the no-scope case explicitly
+- Using \`getCurrentScope()\` as a substitute for \`effectScope()\` — it returns the AMBIENT scope, not a fresh one`,
+  },
+
+  'reactivity/setCurrentScope': {
+    signature: '(scope: EffectScope | null) => void',
+    example: `// Inside a custom render boundary that needs to swap scopes mid-flow:
+const prev = getCurrentScope()
+setCurrentScope(myScope)
+try {
+  doWork()
+} finally {
+  setCurrentScope(prev)
+}
+// Or — preferred:
+myScope.runInScope(() => doWork())`,
+    notes: '**Low-level escape hatch** — directly set the ambient `EffectScope`. Use only when implementing scope-aware framework primitives (e.g. `mountReactive`, custom render boundaries). Most code should use `scope.runInScope(fn)` which sets and restores via try/finally. Pairing `setCurrentScope(s)` with a manual `setCurrentScope(prev)` is error-prone — `runInScope` is the safe form. See also: effectScope, getCurrentScope.',
+    mistakes: `- Forgetting to restore the previous scope — leaks effects to the wrong owner forever
+- Using \`setCurrentScope\` instead of \`runInScope\` in user code — the safe API is \`runInScope\``,
+  },
+
+  'reactivity/onSignalUpdate': {
+    signature: '(listener: (event: { signal, name, prev, next, stack, timestamp }) => void) => () => void',
+    example: `import { onSignalUpdate, signal } from '@pyreon/reactivity'
+
+const dispose = onSignalUpdate(e => {
+  console.log(\`\${e.name ?? '(anonymous)'}: \${e.prev} → \${e.next}\`)
+})
+const count = signal(0, { name: 'count' })
+count.set(5)   // logs: count: 0 → 5
+dispose()      // remove listener`,
+    notes: 'Register a global trace listener that fires on every signal write. Returns a disposer. **Dev/debug only** — every signal write incurs the listener call. Use for time-travel debugging, recording reactive transcripts in tests, or building devtools panels. Multiple listeners are supported (each gets every event). See also: inspectSignal, why.',
+    mistakes: `- Leaving \`onSignalUpdate\` registered in production — fires on EVERY signal write, even hot-path internal ones. Always dispose when done
+- Throwing inside the listener — corrupts the signal's notification flow (the listener fires after \`_v\` is updated but before subscribers are notified). Wrap your handler in try/catch
+- Expecting the event to capture writes that occur via batch flushes — the event fires per \`set()\` call, regardless of batch state`,
+  },
+
+  'reactivity/inspectSignal': {
+    signature: '<T>(sig: Signal<T>) => SignalDebugInfo<T>',
+    example: `const count = signal(0, { name: 'count' })
+inspectSignal(count)
+// Console group:
+//   🔍 Signal "count"
+//     value: 0
+//     subscribers: 2`,
+    notes: 'Inspect a signal — pretty-prints its current value, name, and subscriber count to the console (in a `console.group`) and returns the debug info object. Useful for one-shot inspection while debugging; for continuous tracing use `onSignalUpdate`. See also: onSignalUpdate, why.',
+    mistakes: '- Calling `inspectSignal` in production — produces console noise. Gate calls behind `if (import.meta.env.DEV)` or `__DEV__`',
+  },
+
+  'reactivity/why': {
+    signature: '() => void',
+    example: `why()         // arm tracer
+clickButton()  // any signal writes here are captured
+why()         // disarm + dump transcript:
+//   [pyreon:why] "filter": "all" → "active" (12 subscribers)
+//   [pyreon:why] "scrollY": 0 → 240 (1 subscriber)`,
+    notes: 'Toggle a global "why-did-it-update?" tracer that logs every signal write between consecutive calls. Calling once arms the tracer; calling again disarms it and dumps the captured transcript. **Dev/debug only.** Useful for hunting "why did this effect just re-run?" — wrap a suspicious operation, call `why()` before and after, see exactly which signals changed. See also: onSignalUpdate, inspectSignal.',
+    mistakes: `- Calling \`why()\` once and forgetting to call it again — keeps tracing forever, leaks the listener, prints nothing until disarmed
+- Using \`why()\` in production — pure dev tool`,
+  },
+
+  'reactivity/setErrorHandler': {
+    signature: '(fn: (err: unknown) => void) => void',
+    example: `setErrorHandler(err => {
+  reportToSentry(err)
+  toast.error('Something went wrong')
+})
+
+effect(() => {
+  if (count() > 100) throw new Error('count too high')
+})
+count.set(101)  // logs/reports via handler instead of crashing`,
+    notes: 'Register a global handler for unhandled errors thrown inside `effect()` / `computed()` / `renderEffect()`. Without a handler, errors are logged to `console.error` and the effect re-throws (potentially crashing the surrounding frame). With one, the framework calls your handler with the thrown value and continues. Use for telemetry / error-boundary integration. **One handler only — calling twice replaces the first.** See also: effect, renderEffect.',
+    mistakes: `- Calling \`setErrorHandler\` multiple times and expecting all to fire — the second call REPLACES the first. Compose multiple handlers manually if you need a chain
+- Throwing inside the handler — the framework will swallow this too, but you lose visibility. Make handlers no-throw (try/catch internally if needed)
+- Expecting the handler to receive errors from \`signal.set()\` writes — only effect-runtime errors are routed. Synchronous errors at write time bubble up normally`,
+  },
   // <gen-docs:api-reference:end @pyreon/reactivity>
 
   // ═══════════════════════════════════════════════════════════════════════════
@@ -475,10 +752,15 @@ return wrapCompatComponent(type)(props)`,
   },
 
   'core/ExtractProps': {
-    signature: 'type ExtractProps<T> = T extends ComponentFn<infer P> ? P : T',
-    example: `const Greet: ComponentFn<{ name: string }> = ({ name }) => <h1>{name}</h1>
-type Props = ExtractProps<typeof Greet>  // { name: string }`,
-    notes: `Extracts the props type from a \`ComponentFn\`. Passes through unchanged if \`T\` is not a \`ComponentFn\`. Useful for HOC patterns and typed wrappers that need to infer the wrapped component's prop interface. See also: HigherOrderComponent.`,
+    signature: 'type ExtractProps<T> = /* matches up to 4 overloads, unions the props */ T extends ComponentFn<infer P> ? P : T',
+    example: `function Iterator<T extends SimpleValue>(p: { data: T[]; valueName?: string }): VNodeChild
+function Iterator<T extends ObjectValue>(p: { data: T[]; component: ComponentFn<T> }): VNodeChild
+type Props = ExtractProps<typeof Iterator>
+// → { data: SimpleValue[]; valueName?: string }
+//  | { data: ObjectValue[]; component: ComponentFn<ObjectValue> }`,
+    notes: 'Extracts the props type from a `ComponentFn`. Passes through unchanged if `T` is not a `ComponentFn`. **Multi-overload aware** — matches up to 4 call signatures and produces the UNION of their first-argument types. Critical for multi-overload primitives (Iterator, List, Element) whose loosest overload is last; without overload-aware extraction, HOC wrapping (`rocketstyle()`, `attrs()`) silently downgraded their public prop surface. Single-overload functions still work — the union of 4 copies of the same props type dedupes back to the single shape. See also: HigherOrderComponent.',
+    mistakes: `- Assuming \`ExtractProps<T>\` returns only the LAST overload — pre-fix it did, post-fix it returns the UNION of up to 4 overloads. Functions with more than 4 overloads still drop the extras.
+- Using \`T extends (props: infer P) => any ? P : never\` directly in user code — that pattern captures only the LAST overload of a multi-overload function. Use \`ExtractProps<T>\` to get the full union.`,
   },
 
   'core/HigherOrderComponent': {
@@ -818,18 +1100,61 @@ export default createHandler({
   },
 
   'server/island': {
-    signature: 'island(loader: () => Promise<ComponentFn>, options: { name: string; hydrate?: HydrationStrategy }): ComponentFn',
-    example: `const SearchBar = island(
-  () => import("./SearchBar"),
-  { name: "SearchBar", hydrate: "visible" }
+    signature: 'island(loader: () => Promise<ComponentFn>, options: { name: string; hydrate?: HydrationStrategy; prefetch?: PrefetchStrategy }): ComponentFn',
+    example: `// Visible-hydration paired with idle-prefetch — chunk arrives during
+// browser idle so by scroll-in, hydration is instant.
+const Comments = island(
+  () => import("./Comments"),
+  { name: "Comments", hydrate: "visible", prefetch: "idle" }
 )
 
-// Hydration strategies: "load" | "idle" | "visible" | "media" | "never"`,
-    notes: 'Wrap a lazily-loaded component in a `<pyreon-island>` boundary with a hydration strategy. The rest of the page stays HTML-only; only the island fetches its JS bundle and hydrates. Strategies: `"load"` (immediate), `"idle"` (`requestIdleCallback`), `"visible"` (IntersectionObserver), `"media(query)"` (matchMedia), `"never"` (HTML-only, no JS). Props passed to islands are JSON-serialized — non-JSON values (functions, symbols, undefined, children) are stripped. See also: createHandler, hydrateIslands.',
+// Interaction-hydration — perfect for modals / dropdowns / command palettes.
+const CommandPalette = island(
+  () => import("./CommandPalette"),
+  { name: "CommandPalette", hydrate: "interaction" }, // first focus/click/pointerenter/touchstart
+)
+
+// Hydration strategies: "load" | "idle" | "visible" | "interaction" | "media" | "never"
+// Prefetch strategies:  "none" (default) | "idle" | "visible"`,
+    notes: 'Wrap a lazily-loaded component in a `<pyreon-island>` boundary with a hydration strategy. The rest of the page stays HTML-only; only the island fetches its JS bundle and hydrates. Strategies: `"load"` (immediate), `"idle"` (`requestIdleCallback`), `"visible"` (IntersectionObserver), `"interaction"` (first focus/click/pointerenter/touchstart — also `"interaction(<events>)"` for custom event lists; clicks are REPLAYED on the equivalent live element after hydration so the first click both wakes the island AND fires the action), `"media(query)"` (matchMedia), `"never"` (HTML-only, no JS). Props passed to islands are JSON-serialized — non-JSON values (functions, symbols, undefined, children) are stripped. Pair with `prefetch: "idle"` or `"visible"` to pre-warm the chunk BEFORE the hydration trigger fires — eliminates the blank-while-fetching flash on deferred-strategy islands. Prefetch is a no-op for `hydrate: "load"` (loader runs synchronously already) and `hydrate: "never"` (defeats the zero-JS strategy). See also: createHandler, hydrateIslands, hydrateIslandsAuto.',
     mistakes: `- Passing function props (event handlers, callbacks) — silently stripped during JSON serialization, the island sees \`undefined\`
 - Passing children to an island — stripped; islands cannot render arbitrary descendant trees from props
-- Forgetting to call \`hydrateIslands({ Name: () => import("./Path") })\` on the client — islands render as HTML and never hydrate
-- Using a duplicate \`name\` across two islands — the client-side registry collapses them, only one loader will fire`,
+- Forgetting to wire client-side hydration — under \`@pyreon/vite-plugin\` use \`hydrateIslandsAuto(registry)\` (the registry is auto-generated from \`island()\` calls); without a plugin use the manual \`hydrateIslands({ Name: () => import("./Path") })\`
+- Using a duplicate \`name\` across two islands — the client-side registry collapses them, only one loader will fire
+- Setting \`prefetch: "idle"\` on a \`hydrate: "load"\` island — load runs the loader synchronously, prefetch is redundant (silently suppressed; no \`data-prefetch\` attribute is emitted)
+- Setting any \`prefetch\` on a \`hydrate: "never"\` island — defeats the whole zero-JS point of \`never\` (silently suppressed)
+- Registering a \`hydrate: "never"\` island in \`hydrateIslands({ ... })\` — defeats the strategy by pulling the component module into the client bundle. The whole point of \`never\` is zero client JS. The runtime short-circuits never-strategy before the registry lookup so missing entries are silent (no \`data-island-error="no-loader"\`); the auto-registry omits never-strategy islands by design.
+- Using \`"interaction"\` for visible-on-load components — defeats the strategy. Use \`"load"\` for above-the-fold interactive content; reserve \`"interaction"\` for modals / dropdowns / command palettes that are interactive but only shown on user demand
+- Relying on focus/pointerenter to trigger the SAME action as click for \`"interaction"\` — only clicks are replayed post-hydration. Non-click events trigger hydration but no replay (focus can\'t be reliably re-dispatched once the user has tabbed past; pointerenter is passive)`,
+  },
+
+  'server/hydrateIslands': {
+    signature: 'hydrateIslands(registry: Record<string, () => Promise<ComponentFn | { default: ComponentFn }>>): () => void',
+    example: `import { hydrateIslands } from "@pyreon/server/client"
+
+hydrateIslands({
+  Counter:  () => import("./Counter"),
+  SearchBar: () => import("./SearchBar"),
+  // hydrate: "never" islands are intentionally omitted —
+  // registering them defeats the zero-JS contract.
+})`,
+    notes: 'Client-side counterpart to `island()`. Walks every `<pyreon-island>` element on the page and schedules hydration per its `data-hydrate` strategy. Manual form: the user maintains the `Name → loader` mapping by hand (must match every `island()` `name` field). Returns a cleanup function that disconnects pending observers / listeners. Use `hydrateIslandsAuto()` under `@pyreon/vite-plugin` to skip the manual sync. Imported from `@pyreon/server/client`, NOT from `@pyreon/server` (server-only entry). See also: island, hydrateIslandsAuto.',
+    mistakes: `- Registry key must match the \`island()\` \`name\` field exactly — typo / drift causes runtime \`data-island-error="no-loader"\`. Use \`hydrateIslandsAuto()\` to eliminate this manual sync.
+- Including a \`hydrate: "never"\` island in the registry — defeats the strategy by pulling its module into the client bundle. Skip never-islands; the runtime short-circuits silently for them.
+- Importing from \`@pyreon/server\` instead of \`@pyreon/server/client\` — the main entry is server-only and stubs/throws on client-side use.`,
+  },
+
+  'server/hydrateIslandsAuto': {
+    signature: 'hydrateIslandsAuto(registry: AutoIslandRegistry): () => void',
+    example: `// src/entry-client.ts
+import { hydrateIslandsAuto } from "@pyreon/server/client"
+import * as registry from "virtual:pyreon/islands-registry"
+
+hydrateIslandsAuto(registry)`,
+    notes: 'Auto-discovered counterpart to `hydrateIslands()`. Under `@pyreon/vite-plugin` (`pyreon({ islands: true })` is the default), the plugin pre-scans your source for `island()` declarations and emits a `virtual:pyreon/islands-registry` virtual module. The user imports it into `entry-client.ts` and passes it here. Eliminates the manual `Name → loader` sync that drives the #1 author foot-gun for islands. Never-strategy islands are omitted from the auto-registry by design — their components stay out of the client bundle. See also: hydrateIslands, island.',
+    mistakes: `- Calling without the registry argument — the function takes the imported virtual module explicitly. The user-side \`import\` is what lets the plugin\'s \`resolveId\` hook run; importing from inside \`@pyreon/server/client\` would fail at build time because Rolldown\'s static-import analysis runs before plugin resolveId hooks for workspace sources.
+- Using under a non-Vite bundler — the virtual module only exists under \`@pyreon/vite-plugin\`. Fall back to manual \`hydrateIslands({ ... })\` for non-Vite consumers.
+- Setting \`pyreon({ islands: false })\` and still calling \`hydrateIslandsAuto()\` — the plugin emits a stub registry that throws at runtime with a clear error message. Either re-enable islands (the default) or use \`hydrateIslands({ ... })\` instead.`,
   },
 
   'server/prerender': {
@@ -2348,6 +2673,18 @@ if (__DEV__) console.warn('hello')`,
 
   // <gen-docs:api-reference:start @pyreon/mcp>
 
+  'mcp/mcp_overview': {
+    signature: 'tool: mcp_overview() → MarkdownTable',
+    example: `mcp_overview()
+// → | Tool | When to use | Example |
+//   |------|-------------|---------|
+//   | mcp_overview | Returns a markdown table of every registered MCP tool... | mcp_overview() |
+//   | get_api | Look up any Pyreon API by package and symbol... | get_api({ package: 'flow', symbol: 'createFlow' }) |
+//   | ...`,
+    notes: 'Returns a markdown table of every registered MCP tool with a one-sentence "when to use" description and a one-line example. Reads from this same manifest at runtime — single source of truth (the same data feeds `api-reference.ts`, `llms-full.txt`, and `docs/docs/mcp.md`). Intended as the first call for any AI agent connecting to the server: enumerates the surface so the agent can navigate by intent (e.g. "I need release notes" → `get_changelog`) rather than guessing tool names from `tools/list`. See also: get_api.',
+    mistakes: '- Skipping this tool and calling `tools/list` instead — that returns names + parameter schemas but no "when to use" guidance, so an agent has to call multiple tools to figure out which one fits the task.',
+  },
+
   'mcp/get_browser_smoke_status': {
     signature: 'tool: get_browser_smoke_status — no args',
     example: `// Ask the MCP server:
@@ -2438,7 +2775,17 @@ get_changelog({ package: '@pyreon/router', since: '0.12.0' })`,
     signature: `tool: audit_test_environment({ minRisk?: 'high' | 'medium' | 'low'; limit?: number }) → AuditReport`,
     example: `audit_test_environment({ minRisk: 'medium', limit: 10 })
 // → grouped report with HIGH / MEDIUM / LOW sections`,
-    notes: `Scan every \`*.test.{ts,tsx}\` under \`packages/\` for the mock-vnode anti-pattern that caused PR #197\'s silent metadata drop. Files are classified HIGH / MEDIUM / LOW based on the balance of mock-vnode literals + helpers + helper-call sites vs real \`h()\` calls + \`@pyreon/core\` import. Three context-aware skips (helper-def vs binding discrimination, type-guard call-arg skip, template-string fixture mask) keep the false-positive rate low. Run before merging a new test file or after a framework change. See also: get_browser_smoke_status.`,
+    notes: `Scan every \`*.test.{ts,tsx}\` under \`packages/\` for the mock-vnode anti-pattern that caused PR #197\'s silent metadata drop. Files are classified HIGH / MEDIUM / LOW based on the balance of mock-vnode literals + helpers + helper-call sites vs real \`h()\` calls + \`@pyreon/core\` import. Three context-aware skips (helper-def vs binding discrimination, type-guard call-arg skip, template-string fixture mask) keep the false-positive rate low. Run before merging a new test file or after a framework change. See also: get_browser_smoke_status, audit_islands.`,
+  },
+
+  'mcp/audit_islands': {
+    signature: 'tool: audit_islands({ json?: boolean }) → IslandAuditReport',
+    example: `audit_islands({})
+// → markdown-grouped report with one section per finding code
+
+audit_islands({ json: true })
+// → machine-readable { root, findings: [...], summary: {...} }`,
+    notes: `Project-wide cross-file islands audit (PR C of the islands DX roadmap). Walks \`packages/\` + \`examples/\` and runs five detectors that auto-registry can\'t reach (manual \`hydrateIslands({...})\` for non-Vite consumers / library authors) AND PR G\'s per-file \`island-never-with-registry-entry\` detector misses (it only catches the same-file shape): \`duplicate-name\`, \`never-with-registry-entry\`, \`registry-mismatch\`, \`nested-island\`, \`dead-island\`. Each finding ships with file path + line/column + actionable fix suggestion. Companion to the \`pyreon doctor --check-islands\` CLI flag (same scanner, same five detectors). Run before merging an island PR; CI gate by piping \`--json\` and grepping \`findings.length > 0\`. See also: audit_test_environment, get_anti_patterns.`,
   },
   // <gen-docs:api-reference:end @pyreon/mcp>
 
@@ -2966,4 +3313,448 @@ const tree = helper.getDocNode()`,
     notes: 'Explicit page boundary inside a `DocPage`. Forces the renderer to start a new page at this point in paginated outputs (PDF, DOCX). In flow outputs (HTML, Markdown), it renders as visible whitespace or is omitted entirely. Use for explicit pagination control beyond what `DocPage` boundaries already provide. See also: DocPage.',
   },
   // <gen-docs:api-reference:end @pyreon/document-primitives>
+
+  // <gen-docs:api-reference:start @pyreon/zero>
+
+  'zero/zero': {
+    signature: 'function zero(config?: ZeroConfig): Plugin[] // default export of @pyreon/zero/server',
+    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' })]`,
+    notes: `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. See also: I18nRoutingConfig, GetStaticPaths, Adapter, createISRHandler.`,
+    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`,
+  },
+
+  'zero/I18nRoutingConfig': {
+    signature: `interface I18nRoutingConfig { locales: string[]; defaultLocale: string; strategy?: 'prefix' | 'prefix-except-default' }`,
+    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`,
+    notes: `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. See also: zero, expandRoutesForLocales, i18nRouting.`,
+    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`,
+  },
+
+  'zero/expandRoutesForLocales': {
+    signature: 'function expandRoutesForLocales(routes: FileRoute[], config: I18nRoutingConfig): FileRoute[] // server-only',
+    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`,
+    notes: '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. See also: I18nRoutingConfig, zero, parseFileRoutes.',
+    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`,
+  },
+
+  'zero/GetStaticPaths': {
+    signature: 'type GetStaticPaths<TParams> = () => Array<{ params: TParams }> | Promise<Array<{ params: TParams }>>',
+    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 } }))
+}`,
+    notes: '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`. See also: zero, I18nRoutingConfig.',
+    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`,
+  },
+
+  'zero/Adapter': {
+    signature: 'interface Adapter { name: string; build?(options: AdapterBuildOptions): Promise<void>; revalidate?(path: string): Promise<AdapterRevalidateResult> }',
+    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`,
+    notes: `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. See also: zero, createISRHandler, vercelAdapter.`,
+    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`,
+  },
+
+  'zero/createISRHandler': {
+    signature: 'function createISRHandler(options: { handler: Handler; cacheTtl?: number; ... }): Handler',
+    example: `import { createISRHandler, createServer } from '@pyreon/zero/server'
+
+// Wrap createServer's handler with ISR cache
+const ssrHandler = createServer({ routes })
+const isrHandler = createISRHandler({
+  handler: ssrHandler,
+  cacheTtl: 60_000,  // serve cached HTML for 60s
+})
+
+export default isrHandler`,
+    notes: `Runtime ISR — on-demand SSR caching with TTL. Wraps an SSR handler so pages are rendered on the FIRST request, cached for \`cacheTtl\` ms (default 60s), and served stale until expiry. 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. See also: zero, Adapter.`,
+    mistakes: `- Setting \`cacheTtl: 0\` and expecting "never cache" — pass-through is the explicit handler call (no \`createISRHandler\` wrapper). \`cacheTtl: 0\` is a degenerate state
+- Sharing the ISR handler across server instances without external cache — each server's in-memory cache diverges. For multi-instance deploys, swap to a shared cache layer (Redis adapter not built in; user-side concern)`,
+  },
+
+  'zero/vercelAdapter': {
+    signature: 'function vercelAdapter(): Adapter',
+    example: `plugins: [pyreon(), zero({ mode: 'ssg', adapter: vercelAdapter() })]`,
+    notes: '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()`. See also: Adapter, zero.',
+  },
+
+  'zero/cloudflareAdapter': {
+    signature: 'function cloudflareAdapter(): Adapter',
+    example: `plugins: [pyreon(), zero({ mode: 'ssg', adapter: cloudflareAdapter() })]`,
+    notes: `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. See also: Adapter, zero.`,
+  },
+
+  'zero/netlifyAdapter': {
+    signature: 'function netlifyAdapter(): Adapter',
+    example: `plugins: [pyreon(), zero({ mode: 'ssg', adapter: netlifyAdapter() })]`,
+    notes: `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). See also: Adapter, zero.`,
+  },
+
+  'zero/seoPlugin': {
+    signature: 'function seoPlugin(config: SeoPluginConfig): Plugin // server-only',
+    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' },
+})`,
+    notes: `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. See also: aiPlugin, zero.`,
+    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`,
+  },
+
+  'zero/aiPlugin': {
+    signature: 'function aiPlugin(config?: AiPluginConfig): Plugin // server-only',
+    example: 'plugins: [pyreon(), zero(), seoPlugin({ ... }), aiPlugin()]',
+    notes: `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. See also: seoPlugin, zero.`,
+  },
+
+  'zero/i18nRouting': {
+    signature: 'function i18nRouting(config: I18nRoutingConfig): Plugin // server-only',
+    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`,
+    notes: '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`. See also: zero, I18nRoutingConfig, createLocaleContext.',
+    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`,
+  },
+
+  'zero/validateEnv': {
+    signature: 'function validateEnv<T>(schema: T, env?: ProcessEnv): ValidatedEnv<T> // server-only',
+    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`,
+    notes: '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. See also: zero.',
+  },
+
+  'zero/cspMiddleware': {
+    signature: 'function cspMiddleware(config: { directives: CspDirectives }): Middleware // server-only',
+    example: `import { cspMiddleware } from '@pyreon/zero/server'
+
+plugins: [pyreon(), zero({
+  middleware: [cspMiddleware({
+    directives: {
+      'default-src': ["'self'"],
+      'script-src': ["'self'", "'nonce-{{nonce}}'"],
+    },
+  })],
+})]`,
+    notes: `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. See also: useRequestLocals.`,
+  },
+
+  'zero/useRequestLocals': {
+    signature: 'function useRequestLocals<T = unknown>(): T',
+    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 }>()`,
+    notes: '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. See also: cspMiddleware.',
+  },
+
+  'zero/Link': {
+    signature: '<Link href={path} prefetch="hover" activeClass={cls}>{children}</Link>',
+    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"`,
+    notes: '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. See also: useLink, createLink, prefetchRoute.',
+    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`,
+  },
+
+  'zero/useLink': {
+    signature: 'function useLink(props: LinkProps): UseLinkReturn',
+    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>
+  )
+}`,
+    notes: '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. See also: Link, createLink, UseLinkReturn.',
+    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`,
+  },
+
+  'zero/createLink': {
+    signature: 'function createLink(Component: (p: LinkRenderProps) => any): (props: LinkProps) => any',
+    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>`,
+    notes: '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. See also: Link, useLink, LinkRenderProps.',
+    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`,
+  },
+
+  'zero/prefetchRoute': {
+    signature: 'function prefetchRoute(href: string): void',
+    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>`,
+    notes: `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. See also: Link, useLink.`,
+  },
+
+  'zero/Image': {
+    signature: '<Image src={url} alt={alt} width={w} height={h} priority={false} loading="lazy" placeholder={blurUrl} />',
+    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 />`,
+    notes: '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). See also: useImage, createImage, ImageProps, ImageRenderProps.',
+    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`,
+  },
+
+  'zero/useImage': {
+    signature: 'function useImage(props: ImageProps): UseImageReturn',
+    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>
+  )
+}`,
+    notes: `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. See also: Image, createImage, UseImageReturn.`,
+    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`,
+  },
+
+  'zero/createImage': {
+    signature: 'function createImage(Component: (p: ImageRenderProps) => any): (props: ImageProps) => any',
+    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" />`,
+    notes: '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). See also: Image, useImage, ImageRenderProps.',
+    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)`,
+  },
+
+  'zero/Script': {
+    signature: '<Script src={url} strategy="afterHydration" id={uniqueId} async={true} onLoad={cb} onError={cb} />',
+    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>`,
+    notes: '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. See also: useScript, createScript, ScriptProps, ScriptStrategy.',
+    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\``,
+  },
+
+  'zero/useScript': {
+    signature: 'function useScript(props: ScriptProps): UseScriptReturn',
+    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" />}
+    </>
+  )
+}`,
+    notes: '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). See also: Script, createScript, UseScriptReturn.',
+    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`,
+  },
+
+  'zero/createScript': {
+    signature: 'function createScript(Component: (p: ScriptRenderProps) => any): (props: ScriptProps) => any',
+    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" />`,
+    notes: '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. See also: Script, useScript, ScriptRenderProps.',
+    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`,
+  },
+  // <gen-docs:api-reference:end @pyreon/zero>
 }