@pyreon/reactivity 0.24.4 → 0.24.6

package/src/manifest.ts

@@ -1,660 +0,0 @@
-import { defineManifest } from '@pyreon/manifest'
-
-export default defineManifest({
-  name: '@pyreon/reactivity',
-  title: 'Complete API',
-  tagline:
-    'Fine-grained reactivity: signal, computed, effect, batch, onCleanup, createStore, watch, createResource, untrack',
-  description:
-    'Standalone reactive primitives — no DOM, no JSX, no framework dependency. Signals are callable functions (`count()` to read, `count.set(5)` to write, `count.update(n => n + 1)` to derive). Subscribers tracked via `Set<() => void>`; batch uses pointer swap for zero-allocation grouping. Every other Pyreon package builds on this foundation but `@pyreon/reactivity` can be used independently in Node, Bun, or browser scripts without any framework overhead.',
-  category: 'universal',
-  longExample: `import { signal, computed, effect, batch, onCleanup, createStore, watch, untrack } from "@pyreon/reactivity"
-
-// signal<T>() — callable function, NOT .value getter/setter
-const count = signal(0)
-count()              // read (subscribes)
-count.set(5)         // write
-count.update(n => n + 1)  // derive
-count.peek()         // read WITHOUT subscribing
-
-// computed<T>() — auto-tracked, memoized
-const doubled = computed(() => count() * 2)
-
-// effect() — re-runs when dependencies change
-const dispose = effect(() => {
-  console.log("Count:", count())
-  onCleanup(() => console.log("cleaning up"))
-})
-
-// batch() — group 3+ writes into a single notification pass
-batch(() => {
-  count.set(10)
-  count.set(20)  // subscribers fire once, with 20
-})
-
-// watch(source, callback) — explicit dependency tracking
-watch(() => count(), (next, prev) => {
-  console.log(\`changed from \${prev} to \${next}\`)
-})
-
-// createStore() — deeply reactive object (proxy-based)
-const store = createStore({ todos: [{ text: 'Learn Pyreon', done: false }] })
-store.todos[0].done = true  // fine-grained update, no immer needed
-
-// untrack() — read signals without subscribing
-effect(() => {
-  const current = count()
-  const other = untrack(() => otherSignal())  // won't re-run when otherSignal changes
-})`,
-  features: [
-    'signal<T>() — callable function with .set() and .update()',
-    'computed<T>() — auto-tracked memoized derivation',
-    'effect() / renderEffect() — side-effects with auto-tracking',
-    'batch() / nextTick() — write-grouping + flush awaiter',
-    'onCleanup() — register cleanup inside effects',
-    'watch(source, callback) — explicit reactive watcher',
-    'createSelector() — O(1) equality selector for keyed lists',
-    'cell<T>() — lighter alternative to signal() for direct subscribe()',
-    'createStore() / reconcile() / isStore() — deeply reactive proxy stores + structural diff',
-    'effectScope() / getCurrentScope() — scope-based lifecycle management',
-    'untrack() — read without subscribing',
-    'onSignalUpdate() / inspectSignal() / why() / getReactiveTrace() — debug instrumentation',
-    'setErrorHandler() — global hook for unhandled effect errors',
-    'Standalone — zero DOM, zero JSX, zero framework dependency',
-  ],
-  api: [
-    {
-      name: 'signal',
-      kind: 'function',
-      signature: '<T>(initialValue: T, options?: { name?: string }) => Signal<T>',
-      summary:
-        'Create a reactive signal. The returned value is a CALLABLE FUNCTION — `count()` reads (and subscribes), `count.set(v)` writes, `count.update(fn)` derives, `count.peek()` reads without subscribing. This is NOT a `.value` getter/setter pattern (React/Vue) — Pyreon signals are functions. Optional `{ name }` for debugging; auto-injected by `@pyreon/vite-plugin` in dev mode.',
-      example: `const count = signal(0)
-count()              // 0 (subscribes to updates)
-count.set(5)         // sets to 5
-count.update(n => n + 1)  // 6
-count.peek()         // 6 (does NOT subscribe)`,
-      mistakes: [
-        '`count.value` — does not exist. Use `count()` to read',
-        '`count = 5` — reassigning the variable replaces the signal, does not write to it. Use `count.set(5)`',
-        '`signal(5)` called with an argument after creation — reads and ignores the argument (dev mode warns). Use `.set(5)` to write',
-        '`const [val, setVal] = signal(0)` — signals are not destructurable tuples. The whole return value IS the signal',
-        '`{count}` in JSX — renders the signal function itself, not its value. Use `{count()}` or `{() => count()}`',
-        '`.peek()` inside `effect()` / `computed()` — bypasses tracking, creates stale reads. Only use `.peek()` for loop-prevention guards',
-      ],
-      seeAlso: ['computed', 'effect', 'batch'],
-    },
-    {
-      name: 'computed',
-      kind: 'function',
-      signature: '<T>(fn: () => T, options?: { equals?: (a: T, b: T) => boolean }) => Computed<T>',
-      summary:
-        'Create a memoized derived value. Dependencies auto-tracked on each evaluation — no dependency array needed (unlike React `useMemo`). Only recomputes when a tracked signal actually changes. Custom `equals` function prevents downstream effects from firing on structurally-equal updates (default: `Object.is`).',
-      example: `const count = signal(0)
-const doubled = computed(() => count() * 2)
-doubled()  // 0
-count.set(5)
-doubled()  // 10`,
-      mistakes: [
-        '`computed(() => count)` — must CALL the signal: `computed(() => count())`',
-        'Using `computed()` for side effects — use `effect()` instead; computed is for pure derivation',
-        'Expecting `computed()` to re-run when a `.peek()`-read signal changes — `.peek()` bypasses tracking',
-      ],
-      seeAlso: ['signal', 'effect'],
-    },
-    {
-      name: 'effect',
-      kind: 'function',
-      signature: '(fn: () => (() => void) | void) => () => void',
-      summary:
-        'Run a side effect that auto-tracks signal dependencies and re-runs when they change. Returns a dispose function that unsubscribes. The effect function can return a cleanup callback (equivalent to calling `onCleanup()` inside the body) — the cleanup runs before each re-execution and on final dispose. For DOM-specific effects with lighter overhead, use `renderEffect()` instead.',
-      example: `const count = signal(0)
-const dispose = effect(() => {
-  console.log("Count:", count())
-  onCleanup(() => console.log("cleaning up"))
-})
-// Or return cleanup directly:
-effect(() => {
-  const handler = () => console.log(count())
-  window.addEventListener("resize", handler)
-  return () => window.removeEventListener("resize", handler)
-})`,
-      mistakes: [
-        'Passing a dependency array — Pyreon auto-tracks; no array needed',
-        '`effect(() => { count })` — must call the signal: `effect(() => { count() })`',
-        'Nesting `effect()` inside `effect()` — use `computed()` for derived values instead',
-        'Creating signals inside an effect — they re-create on every run; create once outside',
-      ],
-      seeAlso: ['onCleanup', 'computed', 'renderEffect'],
-    },
-    {
-      name: 'renderEffect',
-      kind: 'function',
-      signature: '(fn: () => void) => () => void',
-      summary:
-        '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()`).',
-      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.`,
-      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',
-      ],
-      seeAlso: ['effect', 'computed'],
-    },
-    {
-      name: 'batch',
-      kind: 'function',
-      signature: '(fn: () => void) => void',
-      summary:
-        'Group multiple signal writes so subscribers fire only once — after the batch completes. Uses pointer swap (zero allocation). Essential when updating 3+ signals that downstream effects read together; without batch, each `.set()` triggers an independent notification pass.',
-      example: `const a = signal(1)
-const b = signal(2)
-batch(() => {
-  a.set(10)
-  b.set(20)
-})
-// Effects that read both a() and b() fire once, not twice`,
-      mistakes: [
-        'Reading a signal inside `batch()` and expecting the NEW value before the batch completes — reads inside the batch see the new value (writes are synchronous), but effects fire only after the batch callback returns',
-        'Forgetting `batch()` when updating 3+ related signals — causes N intermediate re-renders',
-      ],
-      seeAlso: ['signal', 'effect'],
-    },
-    {
-      name: 'nextTick',
-      kind: 'function',
-      signature: '() => Promise<void>',
-      summary:
-        '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.',
-      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')`,
-      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',
-      ],
-      seeAlso: ['batch'],
-    },
-    {
-      name: 'onCleanup',
-      kind: 'function',
-      signature: '(fn: () => void) => void',
-      summary:
-        'Register a cleanup function inside an `effect()` or `renderEffect()`. Runs before each re-execution of the effect (when dependencies change) and once on final dispose. Equivalent to returning a cleanup function from the effect body — both forms work, `onCleanup` is useful when you need to register cleanup at a different point than the end of the body.',
-      example: `effect(() => {
-  const handler = () => console.log(count())
-  window.addEventListener("resize", handler)
-  onCleanup(() => window.removeEventListener("resize", handler))
-})`,
-      mistakes: [
-        'Using `onCleanup` outside an effect — it only works inside `effect()` or `renderEffect()` body',
-        'Confusing with `onUnmount` — `onCleanup` is for effects, `onUnmount` is for component lifecycle',
-      ],
-      seeAlso: ['effect'],
-    },
-    {
-      name: 'watch',
-      kind: 'function',
-      signature: '<T>(source: () => T, callback: (next: T, prev: T) => void, options?: WatchOptions) => () => void',
-      summary:
-        '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.',
-      example: `watch(() => count(), (next, prev) => {
-  console.log(\`changed from \${prev} to \${next}\`)
-})`,
-      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',
-        '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',
-      ],
-      seeAlso: ['effect', 'computed'],
-    },
-    {
-      name: 'createSelector',
-      kind: 'function',
-      signature: '<T>(source: () => T) => (value: T) => boolean',
-      summary:
-        '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.',
-      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>`,
-      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()`',
-      ],
-      seeAlso: ['signal', 'computed'],
-    },
-    {
-      name: 'cell',
-      kind: 'function',
-      signature: '<T>(value: T) => Cell<T>',
-      summary:
-        '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.',
-      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'))`,
-      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',
-      ],
-      seeAlso: ['signal'],
-    },
-    {
-      name: 'createStore',
-      kind: 'function',
-      signature: '<T extends object>(initial: T) => T',
-      summary:
-        '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.',
-      example: `const store = createStore({
-  todos: [{ text: 'Learn Pyreon', done: false }],
-  filter: 'all',
-})
-store.todos[0].done = true   // fine-grained — only 'done' subscribers fire
-store.todos.push({ text: 'Build app', done: false })  // array methods work`,
-      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',
-        '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',
-      ],
-      seeAlso: ['signal'],
-    },
-    {
-      name: 'createResource',
-      kind: 'function',
-      signature:
-        '<T, P>(source: () => P, fetcher: (param: P) => Promise<T>) => Resource<T>',
-      summary:
-        '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.',
-      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`,
-      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',
-      ],
-      seeAlso: ['signal', 'effect', 'effectScope'],
-    },
-    {
-      name: 'reconcile',
-      kind: 'function',
-      signature: '<T extends object>(source: T, target: T) => void',
-      summary:
-        '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.',
-      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`,
-      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)',
-      ],
-      seeAlso: ['createStore', 'signal'],
-    },
-    {
-      name: 'isStore',
-      kind: 'function',
-      signature: '(value: unknown) => boolean',
-      summary:
-        '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).',
-      example: `const a = createStore({ x: 1 })
-const b = { x: 1 }
-isStore(a)  // true
-isStore(b)  // false
-isStore(null)  // false (null-safe)`,
-      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`',
-      ],
-      seeAlso: ['createStore', 'reconcile'],
-    },
-    {
-      name: 'shallowReactive',
-      kind: 'function',
-      signature: '<T extends object>(initial: T) => T',
-      summary:
-        '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.',
-      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)`,
-      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',
-      ],
-      seeAlso: ['createStore', 'markRaw'],
-    },
-    {
-      name: 'markRaw',
-      kind: 'function',
-      signature: '<T extends object>(value: T) => T',
-      summary:
-        '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.',
-      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`,
-      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',
-      ],
-      seeAlso: ['createStore', 'shallowReactive'],
-    },
-    {
-      name: 'untrack',
-      kind: 'function',
-      signature: '(fn: () => T) => T',
-      summary:
-        '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.',
-      example: `effect(() => {
-  const current = count()        // tracked — effect re-runs on count change
-  const other = untrack(() => otherSignal())  // NOT tracked — just reads the current value
-})`,
-      mistakes: [
-        'Using `untrack` as the default — signals should be tracked by default; `untrack` is the escape hatch for specific optimization or loop-prevention cases',
-      ],
-      seeAlso: ['signal', 'effect'],
-    },
-    {
-      name: 'effectScope',
-      kind: 'function',
-      signature: '() => EffectScope',
-      summary:
-        '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.',
-      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`,
-      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',
-      ],
-      seeAlso: ['effect', 'getCurrentScope', 'onScopeDispose'],
-    },
-    {
-      name: 'onScopeDispose',
-      kind: 'function',
-      signature: '(fn: () => void) => void',
-      summary:
-        '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.',
-      example: `scope.runInScope(() => {
-  const ws = new WebSocket(url)
-  onScopeDispose(() => ws.close())
-  // ws.close() runs when scope.stop() is called
-})`,
-      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',
-      ],
-      seeAlso: ['effectScope', 'getCurrentScope', 'onCleanup'],
-    },
-    {
-      name: 'getCurrentScope',
-      kind: 'function',
-      signature: '() => EffectScope | null',
-      summary:
-        '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.',
-      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')
-  }
-}`,
-      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',
-      ],
-      seeAlso: ['effectScope', 'setCurrentScope'],
-    },
-    {
-      name: 'setCurrentScope',
-      kind: 'function',
-      signature: '(scope: EffectScope | null) => void',
-      summary:
-        '**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.',
-      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())`,
-      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`',
-      ],
-      seeAlso: ['effectScope', 'getCurrentScope'],
-    },
-    {
-      name: 'onSignalUpdate',
-      kind: 'function',
-      signature: '(listener: (event: { signal, name, prev, next, stack, timestamp }) => void) => () => void',
-      summary:
-        '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).',
-      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`,
-      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',
-      ],
-      seeAlso: ['inspectSignal', 'why'],
-    },
-    {
-      name: 'inspectSignal',
-      kind: 'function',
-      signature: '<T>(sig: Signal<T>) => SignalDebugInfo<T>',
-      summary:
-        '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`.',
-      example: `const count = signal(0, { name: 'count' })
-inspectSignal(count)
-// Console group:
-//   🔍 Signal "count"
-//     value: 0
-//     subscribers: 2`,
-      mistakes: [
-        'Calling `inspectSignal` in production — produces console noise. Gate calls behind `if (import.meta.env.DEV)` or `__DEV__`',
-      ],
-      seeAlso: ['onSignalUpdate', 'why'],
-    },
-    {
-      name: 'why',
-      kind: 'function',
-      signature: '() => void',
-      summary:
-        '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.',
-      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)`,
-      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',
-      ],
-      seeAlso: ['onSignalUpdate', 'inspectSignal'],
-    },
-    {
-      name: 'getReactiveTrace',
-      kind: 'function',
-      signature:
-        '() => Array<{ name: string | undefined; prev: string; next: string; timestamp: number }>',
-      summary:
-        'Returns the last ~50 signal writes (chronological, oldest → newest) from a bounded dev-only ring buffer — the causal SEQUENCE of reactive state changes, not a point-in-time snapshot. `@pyreon/core` attaches this to `ErrorContext.reactiveTrace` automatically so error reports carry "what changed in the run-up to the crash". Entries hold bounded string previews of values (never raw refs — no memory pinning, always serializable). **Dev-only**: the recorder feeding the buffer is behind the production dead-code gate and tree-shakes out, so this returns `[]` in prod builds. Distinct from `onSignalUpdate` — that is opt-in and captures stacks; this is always-on, deliberately cheap, and exists to enrich error reports. `clearReactiveTrace()` resets it (test isolation).',
-      example: `import { getReactiveTrace, clearReactiveTrace, signal } from '@pyreon/reactivity'
-
-const status = signal('idle', { name: 'status' })
-status.set('submitting')
-getReactiveTrace()
-// [{ name: 'status', prev: '"idle"', next: '"submitting"', timestamp: 1234.5 }]
-clearReactiveTrace()  // → []`,
-      mistakes: [
-        'Expecting it to return signal VALUES — it returns string PREVIEWS (truncated, safely stringified). For live values inspect the signal directly',
-        'Relying on it in production — returns `[]` (the recorder is dev-gated and tree-shaken). Use it for dev tooling / error-report enrichment, not runtime logic',
-        'Treating it as a snapshot of all signals — it is a bounded ring of recent WRITES; signals never written (or written before the ~50-entry window) are absent',
-      ],
-      seeAlso: ['onSignalUpdate', 'inspectSignal'],
-    },
-    {
-      name: 'setErrorHandler',
-      kind: 'function',
-      signature: '(fn: (err: unknown) => void) => void',
-      summary:
-        '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.**',
-      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`,
-      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',
-      ],
-      seeAlso: ['effect', 'renderEffect'],
-    },
-    {
-      name: 'activateReactiveDevtools',
-      kind: 'function',
-      signature:
-        'activateReactiveDevtools(): void  ·  deactivateReactiveDevtools(): void  ·  isReactiveDevtoolsActive(): boolean',
-      summary:
-        'Opt-in lifecycle for the reactive-devtools bridge — the live signal/computed/effect graph the `@pyreon/devtools` Signals/Graph/Effects/Profiler tabs consume (surfaced on the browser hook as `window.__PYREON_DEVTOOLS__.reactive`). **Zero cost until activated**: every per-primitive instrumentation point early-returns on the inactive flag and sits inside the production dead-code gate, so it tree-shakes out of prod builds entirely (locked by a minified-bundle test) and, in dev, costs one predicted-false branch until a devtools client calls `activate()` — the same risk profile as the adjacent reactive-trace / perf-harness calls. `deactivate()` drops all retained registry + fire-buffer state (a closed panel leaves zero residue). Leak-free by construction: nodes are held via `WeakRef` + `FinalizationRegistry`, never pinned.',
-      example: `import { activateReactiveDevtools, getReactiveGraph } from '@pyreon/reactivity'
-
-// Only AFTER activation are subsequently-created signals tracked.
-activateReactiveDevtools()
-const price = signal(10, { name: '$price' })
-const total = computed(() => price() * 2)
-effect(() => total())
-getReactiveGraph().nodes // → [$price (signal), derived, effect]
-deactivateReactiveDevtools() // → registry cleared`,
-      mistakes: [
-        'Expecting nodes created BEFORE `activate()` to appear — registration is gated on the active flag (mirrors a devtools panel attaching). Activate first, then build/observe the graph',
-        'Calling it in production for app logic — the whole bridge is dev-gated and tree-shaken; `getReactiveGraph()` returns an empty graph in prod builds',
-        'Assuming it tracks compiler-emitted DOM bindings — only user `signal()` / `computed()` / `effect()` are registered; `renderEffect` / `_bind` plumbing is intentionally excluded (it would flood the graph and tax the hottest path)',
-      ],
-      seeAlso: ['getReactiveGraph', 'onSignalUpdate', 'getReactiveTrace'],
-    },
-    {
-      name: 'getReactiveGraph',
-      kind: 'function',
-      signature:
-        'getReactiveGraph(): { nodes: ReactiveNode[]; edges: { from: number; to: number }[] }  ·  getReactiveFires(): { id: number; ts: number }[]',
-      summary:
-        'Fresh snapshot of the live reactive graph + a bounded recent-fire timeline, for the reactive-devtools tabs. `getReactiveGraph()` returns every tracked node (`{ id, kind: "signal"|"derived"|"effect", name, value, subscribers, fires, lastFire }`) plus dependency edges recomputed on demand from the real subscriber `_s` Sets (source → subscriber: signal→derived, derived→effect) — always consistent with the framework’s actual subscription state, no incremental drift. `getReactiveFires()` returns a fixed-size ring buffer of recent fires (`{ id, ts }`, oldest → newest) powering the Effects/Profiler tabs. Both require `activateReactiveDevtools()` first and return empty otherwise. Names come from `signal(v, { name })` / the vite-plugin dev auto-naming; anonymous computeds/effects get a synthetic `derived#id` / `effect#id`.',
-      example: `activateReactiveDevtools()
-const a = signal(1, { name: '$a' })
-const b = computed(() => a() + 1)
-effect(() => b())
-a.set(2)
-getReactiveGraph()
-// nodes: [{ name:'$a', kind:'signal', value:'2', … }, { kind:'derived', … }, { kind:'effect', … }]
-// edges: [{ from:$a, to:derived }, { from:derived, to:effect }]
-getReactiveFires() // → [{ id, ts }, …]  (bounded, chronological)`,
-      mistakes: [
-        'Holding the returned arrays expecting them to update — they are point-in-time snapshots; call again (the devtools panel polls)',
-        'Reading `node.value` for non-string state as the real value — it is a bounded, safely-stringified PREVIEW (never a raw ref — no pinning). Inspect the signal directly for the live value',
-        'Expecting fires for every write in a long-running app — `getReactiveFires()` is a fixed-size ring; older entries roll off',
-      ],
-      seeAlso: ['activateReactiveDevtools', 'getReactiveTrace', 'onSignalUpdate'],
-    },
-  ],
-  gotchas: [
-    {
-      label: 'Signals are callable functions',
-      note: 'Pyreon signals are NOT `.value` getters (Vue ref) or `[state, setState]` tuples (React useState). The signal IS the function: `count()` reads, `count.set(v)` writes, `count.update(fn)` derives. This is the #1 confusion for developers coming from other frameworks.',
-    },
-    {
-      label: 'No dependency arrays',
-      note: '`effect()` and `computed()` auto-track dependencies on each execution — no `[dep1, dep2]` array needed. Every signal read inside the body is a tracked dependency. This means conditional reads (`if (cond()) { return x() }`) only track `x` when `cond()` is true.',
-    },
-    {
-      label: 'Standalone',
-      note: '`@pyreon/reactivity` has zero dependencies. Use it in Node/Bun scripts, edge workers, or any JavaScript environment without pulling in the rest of the framework. `@pyreon/core` and `@pyreon/runtime-dom` build on it but are not required.',
-    },
-  ],
-})