@zakkster/lite-signal 1.1.3 → 1.1.5

package/README.md

@@ -3,8 +3,9 @@
 > Zero-GC reactive graph for hot paths. Object-pooled nodes, versioned push-pull propagation, 32-bit modular epochs. Built for 16ms render budgets and 1MB extension bundles.
 
 [![npm version](https://img.shields.io/npm/v/@zakkster/lite-signal.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-signal)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
 ![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
-[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-signa?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-signal)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-signal?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-signal)
 [![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-signal?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-signal)
 [![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-signal?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-signal)
 ![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
@@ -46,6 +47,7 @@ Synchronous, glitch-free, push-pull. No microtask queue, no allocations after wa
 - [Benchmarks](#benchmarks)
 - [Testing strategy](#testing-strategy)
 - [What this is not](#what-this-is-not)
+- [Ecosystem](#ecosystem)
 - [Browser and runtime support](#browser-and-runtime-support)
 - [Integration recipes](#integration-recipes)
 - [Conformance](#conformance)
@@ -102,6 +104,9 @@ Full type definitions ship in [`Signal.d.ts`](./Signal.d.ts) and are referenced
 
 ## The case for object pooling
 
+<details>
+<summary>Why pre-allocate: the GC math, and the per-op zero-allocation table.</summary>
+
 A naive reactive library allocates one object per dependency edge, one per subscription, one per queued effect. With 1000 computeds × 1 update / frame × 60 fps, that's 60,000 short-lived objects per second. The major GC will catch up with you.
 
 `lite-signal` solves this by pre-allocating two pools at startup — **nodes** (one per signal/computed/effect) and **links** (one per dependency edge) — and reusing them indefinitely. After the warm-up frames, the hot path performs zero allocations:
@@ -116,10 +121,15 @@ A naive reactive library allocates one object per dependency edge, one per subsc
 
 The free lists are singly-linked through a `nextFree` field on each pool object — `O(1)` pop, `O(1)` push, no fragmentation.
 
+</details>
+
 ---
 
 ## Architecture in one diagram
 
+<details>
+<summary>Pools, the reactive graph, hot-path state, and the doubly-linked edge model.</summary>
+
 ```mermaid
 flowchart TB
   subgraph Pools[Pre-allocated object pools]
@@ -161,10 +171,15 @@ Every reactive entity is a `ReactiveNode` with bit flags (`COMPUTED`, `EFFECT`,
 
 Doubly-linked on both axes means `O(1)` unlink during the cursor-based reconciliation that happens at the end of every computed/effect re-run.
 
+</details>
+
 ---
 
 ## How a write propagates
 
+<details>
+<summary>The set → mark → flush sequence, and why computeds stay pull-based.</summary>
+
 ```mermaid
 sequenceDiagram
   participant U as User code
@@ -195,6 +210,8 @@ The flush phase uses **two queue buffers** (`effectQueueA` / `effectQueueB`) alt
 
 Computeds are **pull-based** — they're not in the effect queue. Reading a computed walks its dep list, recursively pulls upstream computeds, and only re-runs if any dep's version is greater than its own `evalVersion`. The version comparison uses 32-bit modular arithmetic: `((dep.version - evalVer) | 0) > 0`. This is the trick that makes the engine immune to integer overflow during long-running sessions.
 
+</details>
+
 ---
 
 ## API reference
@@ -296,6 +313,33 @@ Returns `true` iff a read right now would record a dependency on the current reg
 
 For wrapper libraries (lite-store, lite-query, lite-form) gating lazy allocation on the read path. Per-registry — call `registry.isTracking()` if your signals live in a non-default registry.
 
+### Observer-lifecycle introspection
+
+```ts
+// Start a ticker only while something is actually watching a derived value.
+const now = signal(performance.now());
+const unobserve = observeObservers(now, {
+  onConnect:    () => startRAF(),   // 0 → 1 observers
+  onDisconnect: () => stopRAF(),    // 1 → 0 observers
+});
+
+hasObservers(now);                  // O(1): is anyone subscribed right now? (a peek doesn't count)
+
+// Walk the live graph in either direction (lite-devtools):
+forEachObserver(sum, d => console.log(d.kind, d.value));  // subscribers of `sum`
+forEachSource(sum,   d => console.log(d.kind, d.value));  // dependencies of `sum`
+```
+
+Six functions (top-level + per-registry) — four in 1.1.4, two more in 1.1.5 — for auto-pausing wrappers and graph inspection:
+
+- **`hasObservers(handle)` → `boolean`** — O(1) (`node.headSub !== null`). The auto-pause predicate.
+- **`observeObservers(handle, { onConnect?, onDisconnect? })` → `unobserve`** — fires on the 0→1 and 1→0 observer transitions *after* registration (transition-only — no immediate fire if already observed). Re-tracking a persistently-read source does **not** churn. This is the hook `lite-time` / `lite-raf` use to run a clock only while a derived value is watched. Throws `TypeError` on a non-handle.
+- **`forEachObserver(handle, fn)` / `forEachSource(handle, fn)`** — walk subscribers / dependencies; `fn` gets a `{ id, kind, value }` descriptor (`kind` ∈ `"signal" | "computed" | "effect"`; `id` added in 1.1.5). No-op on a non-handle.
+- **`nodeId(handle)` → `number | undefined`** *(1.1.5)* — the node's stable per-allocation id; the dedupe key for graph traversal. `undefined` on a non-handle.
+- **`describe(handle)` → `{ id, kind, value } | undefined`** *(1.1.5)* — the handle's own descriptor. **Re-walkable**: pass it back into `forEachObserver`/`forEachSource` to recurse the graph. `undefined` on a non-handle.
+
+The surface is gated by an internal lifecycle counter: when nothing is being observed, the hot path adds a single branch-predicted `count !== 0` check in link alloc/free and nothing else — **zero steady-state cost when unused**.
+
 ### onCleanup
 
 ```ts
@@ -346,6 +390,9 @@ r.destroy();                     // reset all pools, invalidate generations
 
 ## Capacity, growth, and the link ceiling
 
+<details>
+<summary>Pool sizing, the grow policy, and why there is a 16× link ceiling.</summary>
+
 The engine has two pool sizes: **nodes** and **links**. Both are fixed at registry creation but can be configured to grow.
 
 ```mermaid
@@ -370,6 +417,8 @@ Default sizing for a Twitch-extension-style budget:
 
 `stats()` reports `signals`, `computeds`, `effects`, `activeLinks`, `pooledLinks`, `linkPoolCapacity`. Drop it on screen for live observability.
 
+</details>
+
 ---
 
 ## Watchers
@@ -505,6 +554,9 @@ All three primitives live in a separate module (`Watch.js`) and are re-exported
 
 ## Edge cases pinned down
 
+<details>
+<summary>Diamonds, self-feedback, NaN/±0, throwing bodies, 32-bit version wrap, deep-chain limits.</summary>
+
 These are the questions you'd ask in a code review, with the answers:
 
 - **Diamond dependency.** Glitch-free. The mark phase walks the graph once; computeds are pulled lazily on read, so each one re-runs at most once per propagation regardless of how many paths reach it.
@@ -518,26 +570,29 @@ These are the questions you'd ask in a code review, with the answers:
 - **Deep chain depth.** Computed resolution is recursive in the JS call stack. Chains beyond ~10,000 deep risk `RangeError: Maximum call stack size exceeded`. Effects use an iterative mark phase, so signal → effect fan-out has no depth limit other than memory.
 - **`destroy()` after dispose.** `destroy()` bumps every node's generation, so any in-flight scheduled trampolines from before destruction are silently dropped. Closures returned to user code from disposed effects guard with `if (node.flags === 0) return;` — calling `dispose()` again is a no-op.
 
+</details>
+
 ---
 
 ## Benchmarks
 
-Honest numbers, against the same workload, with anti-DCE sinks and verified effect execution. All measurements: Node 22, **2016-era Intel MacBook Pro (4 cores, ~10 yr old hardware)**, 20K iterations × 5 inner runs × 50+ outer invocations (median reported). Newer/faster machines shift all libs up proportionally; the relative ordering between libs is what matters.
+Honest numbers, against the same workload, with anti-DCE sinks and verified effect execution. All measurements: Node 22, **2016-era Intel MacBook Pro (4 cores, ~10 yr old hardware)**, 20K iterations × 5 inner runs × 11 outer invocations (median reported). Newer/faster machines shift all libs up proportionally; the relative ordering between libs is what matters. Numbers below are lite-signal **@1.1.5** vs alien-signals on the same loop; the full five-framework comparison (incl. preact, vue-reactivity, solid across 34 reactive-suite tests) is in [`resultsReactive.txt`](./resultsReactive.txt). *(Both halves are now @1.1.5 — this throughput table median-of-11, the cross-framework reactivity suite median-of-12 in [`resultsReactive.txt`](./resultsReactive.txt). 1.1.5 is additive over 1.1.4 (node-identity only), so the engine numbers are perf-neutral vs 1.1.4.)*
 
-| Scenario   | What it stresses                | lite-signal | alien-signals | preact     | solid-js  |
-| ---------- | -------------------------------- | ----------- | ------------- | ---------- | --------- |
-| **MUX**    | 256 signals → 1 sum → 1 effect (fan-in) | **249K ops/s** | 207K       | 153K       | 77K       |
-| **BROADCAST** | 1 signal → 1000 effects (fan-out) | **24K**     | 22K           | 17K        | 8K        |
-| **KAIROS**    | 1 signal → 1000 computeds → 1 effect | **14K**  | 13K           | 12K        | 4K        |
-| **DEEP CHAIN** | 256-deep computed chain → 1 effect | 51K     | **60K**       | 50K        | 15K       |
-| **Δheap MUX**  | transient alloc pressure       | **15 KB**   | 3,920 KB      | 4,325 KB   | 2,816 KB  |
-| **Retained MUX** | state surviving forced GC    | **−20 KB** (none) | −2 KB    | −6 KB      | −3 KB     |
+| Scenario   | What it stresses                | lite-signal | alien-signals | lite vs alien |
+| ---------- | -------------------------------- | ----------- | ------------- | ------------- |
+| **MUX**    | 256 signals → 1 sum → 1 effect (fan-in) | **314K ops/s** | 198K       | **+59%**      |
+| **BROADCAST** | 1 signal → 1000 effects (fan-out)    | **27K**     | 22K           | **+20%**      |
+| **KAIROS**    | 1 signal → 1000 computeds → 1 effect | **15K**     | 13K           | **+19%**      |
+| **DEEP CHAIN** | 256-deep computed chain → 1 effect  | 53K         | **60K**       | −12%          |
+| **WIDE DENSE** | 5 layers × ~200 wide, dense fan-in  | **7K**      | 7K            | **+6%** ⬆     |
+| **Δheap MUX**  | transient alloc pressure, 20K iters | **0.3 KB**  | 6,120 KB      | —             |
+| **Retained MUX** | state surviving forced GC         | **−7 KB** (none) | −1 KB    | —             |
 
-**Reading the table:** `lite-signal` wins **MUX** (fan-in aggregation) by **+20%**, **BROADCAST** (fan-out) by **+9%**, and **KAIROS** (one source feeding a wide layer of memos) by **+8%** — three of the four scenarios. These are the patterns that dominate real UI workloads: dashboards, scoreboards, HUDs, leaderboards, and any view that aggregates many inputs into a single computed slice. `alien-signals` retains a **−15% lead on DEEP CHAIN** (256-deep computed pipelines), where a flatter internal representation pays off when the propagation path is long rather than wide.
+**Reading the table:** `lite-signal` wins **MUX** (fan-in aggregation) by **+59%**, **BROADCAST** (fan-out) by **+20%**, and **KAIROS** (one source feeding a wide layer of memos) by **+19%** — the patterns that dominate real UI workloads: dashboards, scoreboards, HUDs, leaderboards, and any view that aggregates many inputs into a single computed slice. The **WIDE DENSE** row (⬆) is the headline of 1.1.4: at 1.1.2 lite-signal *lost* this dense, high-fan-in shape by −16%; the 1.1.4 retracking rewrite flips it to **+6%**. `alien-signals` now retains only a **−12% lead on DEEP CHAIN** (256-deep computed pipelines), where a flatter internal representation pays off when the propagation path is long rather than wide.
 
-On allocation pressure, `lite-signal` is alone in the zero-Δheap band: ~15 KB of transient garbage across 20,000 iterations regardless of scenario. preact runs ~230 KB per loop, solid runs into single-digit megabytes, and alien-signals — which earlier shared the zero-GC band with lite-signal — now allocates 0.9-3.9 MB per scenario in current published versions. Negative "retained" numbers mean V8 reclaimed memory below the pre-bench baseline during the post-run forced GC — no leaks anywhere.
+On allocation pressure, `lite-signal` is alone in the zero-Δheap band: ~0.3 KB of transient garbage on stable shapes across 20,000 iterations. The contrast is starkest on SMALL SELECTIVE — lite-signal 0.3 KB vs alien-signals **~15 MB** in the same loop. preact ranges from ~220 KB to low-single-digit MB per loop, solid runs into single-digit megabytes, and alien-signals — which earlier shared the zero-GC band with lite-signal — allocates from near-zero (BROADCAST) up to ~6 MB (MUX) per stable scenario in this run. Negative "retained" numbers mean V8 reclaimed memory below the pre-bench baseline during the post-run forced GC — no leaks anywhere.
 
-> Note on the +71 KB retained that lite-signal shows on KAIROS specifically: that's the pre-allocated pool sitting in memory holding the live graph (1002 nodes + ~2000 links). The pool *is* the working memory — see the [Case for object pooling](#case-for-object-pooling) section. On the other benches the graph is small enough that the same pool floats below baseline after GC.
+> Note on the +70.8 KB retained that lite-signal shows on KAIROS specifically: that's the pre-allocated pool sitting in memory holding the live graph (1002 nodes + ~2000 links). The pool *is* the working memory — see the [Case for object pooling](#case-for-object-pooling) section. On the other benches the graph is small enough that the same pool floats below baseline after GC.
 
 The benchmark harness is in [`bench/benchmark.mjs`](./bench/benchmark.mjs); a full methodology write-up — including the anti-DCE design, workload diagrams, variance discipline, reproducibility recipe, and a self-validation procedure for the harness itself — lives in [`bench/README.md`](./bench/README.md). It:
 
@@ -562,15 +617,23 @@ Three tiers, all reproducible.
 
 `npm test` runs the suite in `test/`, covering:
 
-- **`01-core.test.mjs`** — signal/computed/effect basics, equality semantics, NaN/±0, subscribe/peek/update, untrack, batch, cleanup ordering, first-run error recovery, nested object reference-identity gotchas.
-- **`02-topology.test.mjs`** — diamond glitch-freedom, 256-deep and 1024-deep computed chains, wide fan-out (1000 effects from one signal), dynamic dependency switching, conditional fan-out, nested effects, cycle detection (`CycleError`).
-- **`03-pool.test.mjs`** — `CapacityError` under both `"throw"` and `"grow"` policies, the 16× link ceiling, stable pool reuse across thousands of create/dispose cycles, registry isolation.
-- **`05-scheduler.test.mjs`** — scheduler-deferred effects, dispose-during-schedule races, microtask integration, 32-bit version wrap (simulated), `setDefaultRegistry`, `onCleanup` inside computeds.
-- **`06-nested-objects.test.mjs`** — array mutation patterns (push/splice/spread), deep nested paths, Map/Set/Date inside signals, custom structural equality, computed memoisation cutoffs over object slices, signal-of-signals composition, high-frequency object updates, batched immutable updates.
-- **`07-dispose.test.mjs`** — unified `dispose(api)` across signals, computeds and effect handles, idempotency, cross-registry isolation (per-registry Symbol prevents pool corruption), foreign-value safety, top-level helper routing, 500-cycle balanced churn leaving pool and stats stable.
-- **`08-watch.test.mjs`** — Validates the user-land observer utilities (watch, when, whenAsync). Covers lifecycle teardown, old/new value tracking, and Promise-based asynchronous state resolution.
-- **`09-conformance.test.mjs`** — Industry-standard conformance tests. Validates the engine against extreme edge cases from the johnsoncodehk reactive test suite, ensuring strict zero-GC invariants, correct cleanup isolation, and re-entrant stability.
-- **`10-is-tracking.test.mjs`** — The `isTracking()` observer-context predicate. 11 tests across 5 describe blocks: true inside effect/computed bodies; false inside `untrack`, `subscribe` callbacks, `onCleanup` bodies, and `watch` callbacks (the untracked-window cases that catch an observer-only misimplementation); false outside any observer including at the call site of an unobserved computed read; state-restoration after a thrown body; per-registry isolation; top-level binding.
+- **`01-core_test.mjs`** — signal/computed/effect basics, equality semantics, NaN/±0, subscribe/peek/update, untrack, batch, cleanup ordering, first-run error recovery, nested object reference-identity gotchas.
+- **`02-topology_test.mjs`** — diamond glitch-freedom, 256-deep and 1024-deep computed chains, wide fan-out (1000 effects from one signal), dynamic dependency switching, conditional fan-out, nested effects, cycle detection (`CycleError`).
+- **`03-pool_test.mjs`** — `CapacityError` under both `"throw"` and `"grow"` policies, the 16× link ceiling, stable pool reuse across thousands of create/dispose cycles, registry isolation.
+- **`05-scheduler_test.mjs`** — scheduler-deferred effects, dispose-during-schedule races, microtask integration, 32-bit version wrap (simulated), `setDefaultRegistry`, `onCleanup` inside computeds.
+- **`06-nested-objects_test.mjs`** — array mutation patterns (push/splice/spread), deep nested paths, Map/Set/Date inside signals, custom structural equality, computed memoisation cutoffs over object slices, signal-of-signals composition, high-frequency object updates, batched immutable updates.
+- **`07-dispose_test.mjs`** — unified `dispose(api)` across signals, computeds and effect handles, idempotency, cross-registry isolation (per-registry Symbol prevents pool corruption), foreign-value safety, top-level helper routing, 500-cycle balanced churn leaving pool and stats stable.
+- **`08-watch_test.mjs`** — Validates the user-land observer utilities (watch, when, whenAsync). Covers lifecycle teardown, old/new value tracking, and Promise-based asynchronous state resolution.
+- **`09-conformance_test.mjs`** — Industry-standard conformance tests. Validates the engine against extreme edge cases from the johnsoncodehk reactive test suite, ensuring strict zero-GC invariants, correct cleanup isolation, and re-entrant stability.
+- **`10-is-tracking_test.mjs`** — The `isTracking()` observer-context predicate. 11 tests across 5 describe blocks: true inside effect/computed bodies; false inside `untrack`, `subscribe` callbacks, `onCleanup` bodies, and `watch` callbacks (the untracked-window cases that catch an observer-only misimplementation); false outside any observer including at the call site of an unobserved computed read; state-restoration after a thrown body; per-registry isolation; top-level binding.
+- **`11-adopted-reactive_test.mjs`** — 24 engine-agnostic edge cases adopted from across the ecosystem: alien-signals' parent-child link-integrity regression (#226–228), equality-predicate corners (preact/solid/vue), `signal.update(fn)` functional setter (vue/solid), `peek()` non-subscription depth (preact/vue), and the `subscribe` behavioral contract (preact/mobx).
+- **`12-coverage_test.mjs`** — 18 targeted exercises for public surface and hot-path branches the behavioral suites don't incidentally hit: top-level routing to the default registry, the computed clean-read short-circuit (`markEpoch` O(1) skip), dependency-set shrink severing the stale tail, error/structural edge paths, and scheduler ABA across a recycled pool slot. The owner-tree block is capability-gated (runs on 1.2.0+, skipped on 1.1.x).
+- **`13-introspection_test.mjs`** — The observer-lifecycle surface (1.1.4). 10 tests across 3 describe blocks: `hasObservers` (live observation reflects; a peek doesn't count), `observeObservers` auto-pause lifecycle (start-on-first / stop-on-last, no extra connect for a 2nd observer, re-observe fires again, no churn on re-track, conditional reads toggle honestly, transition-only registration, works for computeds), and `forEachObserver`/`forEachSource` enumeration (both directions; descriptor carries kind + value).
+- **`14-lifecycle-teardown_test.mjs`** — Effect-teardown guards against the alien-signals@3.2.1 regressions (4 tests). A stopped effect must not re-subscribe to a signal read later in the same run; self-dispose must leave no orphaned link (clean `activeLinks`); a throwing setup must leave no live subscription; normal and dynamic re-tracking stay unaffected by the `allocateLink` eligibility gate.
+- **`15-owner-lazy-alloc_test.mjs`** — Owner-adoption contract for the 1.2.0 owner tree (4 tests, capability-gated — skipped on 1.1.x). A signal allocated lazily *inside* a computed/effect must **not** be owner-adopted (it survives the owner's re-run — the lite-store/lite-form lazy-field shape) and sibling lazy signals must not cross-wire, while observers *are* still auto-disposed. Runs on 1.2.0+.
+- **`16-alien-parity_test.mjs`** — Differential regression guards (3 tests) reproducing the *properties* behind alien-signals@3.2.0 fixed bugs: reads inside a cleanup create no spurious dependencies (the dispose-cleanup fix); an inner-effect write does not block later propagation through a computed chain (#112); a dynamic dependency-set change stays correct under dirty-check (#109/#110).
+- **`17-reactivity_test.mjs`** — Behavioral suite (≈30 tests across 11 groups) mirroring universal signal-system bug classes: subscription lifecycle, cleanup ordering, stale-dependency tracking, batching/timing (incl. set-then-revert), equality cutoff (NaN/±0/custom), nested invalidation + glitch-free diamond, memory/retained nodes, the synchronous async-boundary, scheduler & loops (self-write termination, self-reading computed), and differential-review additions (cached computed errors, mid-batch pull, self-disposing getter, pooled-slot return). SSR hydration is a documented N/A — lite has no DOM layer.
+- **`18-identity_test.mjs`** — Node identity (1.1.5; 5 tests). Unique/stable ids; `nodeId`/`describe` return `undefined` for a non-handle; the descriptor's visible shape is `{ id, kind, value }`; `forEach*` descriptors carry `id` and are **re-walkable** (`nodeId`/`forEachSource` accept a descriptor); identity walks are non-perturbing (add no observers).
 
 ```bash
 npm test
@@ -578,7 +641,7 @@ npm test
 
 ### Tier 2 — Memory (allocation-free verification)
 
-`npm run test:gc` runs `test/04-zero-gc.test.mjs` with `--expose-gc`:
+`npm run test:gc` runs `test/04-zero-gc_test.mjs` with `--expose-gc`:
 
 - 100,000 `set()` calls on a graph with effects retain **< 200 KB** of heap.
 - 1,000 create/dispose cycles retain **< 50 KB**.
@@ -593,7 +656,7 @@ npm run test:gc
 
 ### Tier 3 — Performance (comparative benchmark)
 
-`npm run bench` runs the four-scenario comparative benchmark from the previous section. Output is plain text — easy to copy into PRs and changelogs.
+`npm run bench` runs the comparative benchmark (9 scenarios — stable fan-in/out + dynamic/layered DAGs) against alien-signals (results.txt). `npm run bench-reactive` runs the cross-framework reactivity suite vs alien-signals, preact, vue-reactivity, and solid (resultsReactive.txt). Output is plain text — easy to copy into PRs and changelogs.
 
 ```bash
 npm run bench
@@ -609,29 +672,47 @@ npm run verify   # test + test:gc + a sanity bench
 
 ## Performance Trade-offs & Topology Scaling
 
+<details>
+<summary>Stable vs dynamic topologies; Andrii Volynets' matrix, the 1.1.4 result, and the roadmap.</summary>
+
 `lite-signal` was built with a strict mandate: **absolute zero garbage collection**. By packing the dependency graph into a flat, pre-allocated memory arena, we eliminate the Scavenger GC pauses that plague 120fps Canvas/WebGL loops.
 
-However, flat arrays come with a mathematical trade-off. While memory allocation is $O(1)$, modifying a flat array during dynamic dependency churn requires $O(N)$ linear scans. 
+Through **v1.1.2**, that came with a mathematical trade-off: while memory allocation is $O(1)$, the cursor-based retracking degraded to $O(N)$ linear scans under chaotic, high-fan-in, batched read-after-write — the shape of large DOM-style apps with heavy branch switching. **v1.1.4 closed that gap.** A version-stamped $O(1)$ reconciliation plus a `markEpoch` clean-read short-circuit on the pull replaced the cursor degradation; stable read order is unchanged (still $O(1)$, still zero-alloc).
 
-**Andrii Volynets** (author of the phenomenal [Alien Signals](https://github.com/stackblitz/alien-signals)) generously ran `lite-signal` through his advanced topology matrix. The results clearly highlight where the zero-GC flat-array architecture excels, and where pointer-based graphs (like Alien/Reflex) take the lead:
+**Andrii Volynets** (author of the phenomenal [Alien Signals](https://github.com/stackblitz/alien-signals)) generously ran `lite-signal` through his advanced topology matrix on the **v1.1.2** engine. Those numbers — the *pre-rewrite baseline* — are below, followed by the 1.1.4 result.
 
 #### 1. Stable Topologies (Fan-in / Fan-out / Broadcast)
-In stable environments (typical of game engines, particle systems, and visualizers), `lite-signal` is blisteringly fast and maintains a near-zero allocation profile, keeping frame times perfectly flat.
-
-#### 2. Dynamic Topologies (Web Apps / Layered DAGs)
-In highly chaotic graphs with branch switching, selective reads, and wide dense churn (typical of large DOM-based web frameworks like Vue or React), the $O(N)$ edge traversal cost of flat arrays becomes the dominant bottleneck.
+In stable environments (game engines, particle systems, visualizers), `lite-signal` is blisteringly fast and maintains a near-zero allocation profile, keeping frame times perfectly flat — unchanged through 1.1.4.
 
-*Andrii's benchmark results for dynamic topologies:*
-| Scenario | alien-signals | reflex | lite-signal |
+#### 2. Dynamic Topologies (Web Apps / Layered DAGs) — closed in 1.1.4
+*Andrii's v1.1.2 baseline (his host) — where the cursor retracking lost:*
+| Scenario | alien-signals | reflex | lite-signal (1.1.2) |
 | :--- | :--- | :--- | :--- |
 | **1000x12 (4 sources, dynamic)** | 184ms | 194ms | 2031ms |
 | **1000x5 (25 sources, wide/dense)** | 304ms | 303ms | 1746ms |
 | **64x6 (selective dynamic DAG)** | 181ms | 196ms | 559ms |
 
-**The Takeaway:** "Zero-GC" and "topology scalability" are orthogonal dimensions. If you are building a DOM framework with massive dynamic `v-if` churn, use Alien Signals. If you are building a 120fps Canvas game with a stable scene graph where any GC pause is a dropped frame, use `lite-signal`.
+*1.1.5 on the local harness (slow 2016 MacBook — compare within-column, lite vs alien; the approximating scenarios from `bench/benchmark.mjs`):*
+| Scenario | alien-signals | lite-signal (1.1.5) | result |
+| :--- | :--- | :--- | :--- |
+| **LARGE WEB APP** (≈ 1000x12) | 2846ms | 2686ms | **lite +6%** |
+| **WIDE DENSE** (≈ 1000x5) | 2826ms | 2671ms | **lite +6%** |
+| **SMALL SELECTIVE** (≈ 64x6) | 2000ms | 1857ms | **lite +8%** |
+
+> **Honest note (1.1.5 run):** alien-signals is much faster on these three shapes than in the 1.1.4 run above (SMALL SELECTIVE 2985ms → 2000ms, LARGE WEB APP 3026ms → 2846ms) — a newer alien build and/or host conditions — so lite-signal's margins narrowed from +60%/+11%/+6% to **+8%/+6%/+6%**. Within this run lite still leads all three and remains the only zero-Δheap library (see [`results.txt`](./results.txt)).
+
+The cross-framework reactivity suite agrees independently and was re-run on **1.1.5** (median-of-12): `dyn: large web app` **555ms** (+6% vs alien-signals' 590ms) and `dyn: wide dense` **870ms** (+7% vs 933ms) are wins there too — lite-signal is the fastest of five frameworks on both, with preact and vue ~7–30× slower (see [`resultsReactive.txt`](./resultsReactive.txt)). The retracking is verified correct by `retracking.difftest.mjs` — 20,000 direct + 10,000 batched writes, 0 disagreements. *(A fresh run of Andrii's exact matrix on 1.1.5 is the definitive external confirmation and is pending; the two local suites above are the current evidence.)*
+
+**The Takeaway:** as of 1.1.4 you no longer have to choose. `lite-signal` keeps the zero-GC, flat-arena profile for 120fps Canvas/WebGL **and** holds parity-or-ahead of alien-signals on dynamic, high-fan-in web-app topologies. The one shape where alien's flatter representation still leads is the 256-deep computed pipeline (DEEP CHAIN, −12%).
+
+### Roadmap
+- **1.1.5** — additions in service of `lite-devtools` (node identity/traversability on the introspection walkers, for full auto-discovered graph rendering).
+- **1.2.0** — the **ownership hybrid**: an owner tree so nested effects/computeds auto-dispose with their parent (closes conformance #209 / #210, matching Solid's `createRoot` ergonomics).
+- **1.3** — next engine work after the owner-tree validation.
+
+> Note: the retracking rewrite that closes the dynamic-topology gap shipped in **1.1.4**, not a future release. The earlier roadmap that listed it under "v1.2" is superseded.
 
-### Roadmap: v1.2
-v1.2 (in benchmark validation) — Andrii Volynets (alien-signals#117) extended the benchmark matrix to dynamic-topology workloads and identified retracking-cost asymptotics, not allocation pressure, as the dominant cost in those scenarios. v1.2 replaces the cursor-based retracking with per-source version-stamped reconciliation: O(1) per read regardless of read order or dep-set churn. v1.2 will be validated against the alien-signals topology matrix and the before/after numbers published on release.
+</details>
 
 ---
 
@@ -639,13 +720,39 @@ v1.2 (in benchmark validation) — Andrii Volynets (alien-signals#117) extended
 
 - **A virtual DOM, JSX runtime, or rendering library.** It's the substrate. Plug it under whatever rendering layer you like.
 - **A general-purpose state container.** No time-travel, no devtools integration, no serialization. (Build those on top if you need them.)
-- **A perfect fit for every workload.** If your reactive graph is mostly long chains of memos with chaotic read order, `alien-signals` is genuinely faster on those shapes. `lite-signal` optimizes for *stable* read order — the same observer reading the same deps in the same order, frame after frame, which is the dominant pattern in animation loops and HUD overlays.
+- **A perfect fit for every workload.** On *256-deep computed pipelines* (DEEP CHAIN) `alien-signals` is still a bit faster — its flatter representation pays off when the propagation path is long rather than wide. (Through 1.1.2 this caveat also covered chaotic, high-fan-in read order; 1.1.4's retracking rewrite closed that — those shapes are now parity-or-ahead.) `lite-signal` is at its best on the fan-in / fan-out / wide-memo and dynamic-churn patterns that dominate animation loops, HUDs, and dashboards.
 - **A library for the server.** It works in Node, but there's no SSR story. Use it on the client.
 
 ---
 
+## Ecosystem
+
+A growing family of zero-GC, ESM-only, sub-2KB packages built on `lite-signal`. All MIT, all by [@zakkster](https://www.npmjs.com/~zakkster).
+
+**State & data**
+- [`@zakkster/lite-store`](https://www.npmjs.com/package/@zakkster/lite-store) — Fine-grained reactivity for objects & arrays via Proxy. Direct mutation; lazy per-key signals (allocated only on first tracked read); proxy identity preserved across reads; cycle-safe disposal walk.
+- [`@zakkster/lite-resource`](https://www.npmjs.com/package/@zakkster/lite-resource) — Async state as a signal. `resource(source, fetcher)` exposes data/error/loading/state with race-safe commits (generation guard), AbortSignal, stale-while-revalidate, and optimistic mutate.
+- [`@zakkster/lite-form`](https://www.npmjs.com/package/@zakkster/lite-form) — Headless reactive forms. One validator per keystroke, hoisted Zod/Yup schema, ~1.5M keystrokes/sec on a 100-field form (8× the hand-written pattern). No DOM, no VDOM, no compiler.
+- [`@zakkster/lite-router`](https://www.npmjs.com/package/@zakkster/lite-router) — Zero-GC sub-2KB SPA router. URL pathname, query params, and route matches as fine-grained signals — components re-render only when their slice of the URL changes.
+- [`@zakkster/lite-persist`](https://www.npmjs.com/package/@zakkster/lite-persist) — Zero-GC reactive persistence. Debounced, coalesced localStorage/sessionStorage sync with cross-tab mirroring — a burst of writes becomes one storage write.
+- [`@zakkster/lite-channel`](https://www.npmjs.com/package/@zakkster/lite-channel) — Cross-tab synchronization over BroadcastChannel. Multiplexed per-key sync, last-writer-wins (Lamport clock + tab-id tiebreak), reactive presence (peers, status, leader election as signals).
+
+**Rendering (DOM / Canvas)**
+- [`@zakkster/lite-element`](https://www.npmjs.com/package/@zakkster/lite-element) — Zero-GC reactive Custom Elements, no virtual DOM or templating. Component state survives synchronous reparents (sort, drag-and-drop, `insertBefore`) — the moves that destroy React, Vue, and Lit components.
+- [`@zakkster/lite-virtual`](https://www.npmjs.com/package/@zakkster/lite-virtual) — Thrash-free list/grid windowing. Integer-gated reactive indices + `Object.is` cutoff means scrolling within a row writes zero bytes to the DOM. ~3.6M sub-row scrolls/sec, bounded pool regardless of count, fixed and variable heights, 2-D grid.
+- [`@zakkster/lite-scene`](https://www.npmjs.com/package/@zakkster/lite-scene) — Reactive retained-mode Canvas2D scene graph. Nodes (group/rect/circle/line/text/image/path) take signals as props; the renderer redraws only what changed. Hit testing, clip groups, pointerEvents, nested transforms.
+
+**Time & scheduling**
+- [`@zakkster/lite-raf`](https://www.npmjs.com/package/@zakkster/lite-raf) — Zero-GC frame-rate scheduling. One `requestAnimationFrame` loop; frameTime/frameDelta/frameCount as signals; `rafEffect()` — reactive effects that run at most once per frame. Built for canvas/WebGL render loops and games.
+- [`@zakkster/lite-time`](https://www.npmjs.com/package/@zakkster/lite-time) — Reactive, drift-corrected wall-clock cadence. One 1s heartbeat; zero-GC relativeTime/countdown/every; deterministic for tests and SSR. Not a date library — `Intl` does formatting, you bring the dates.
+
+---
+
 ## Browser and runtime support
 
+<details>
+<summary>Support matrix (Chrome / Firefox / Safari / Node / Bun / Deno / Workers).</summary>
+
 Pure ES2020 + `Object.is` + `Int32 | 0`. Runs anywhere that runs modern JavaScript.
 
 | Target                            | Supported |
@@ -661,10 +768,15 @@ Pure ES2020 + `Object.is` + `Int32 | 0`. Runs anywhere that runs modern JavaScri
 
 ESM-only. No CommonJS build — modern bundlers handle this; legacy consumers can use a wrapper.
 
+</details>
+
 ---
 
 ## Integration recipes
 
+<details>
+<summary>Game HUD (rAF), Twitch config sync, per-tenant sandboxing.</summary>
+
 ### Reactive game HUD with requestAnimationFrame
 
 ```js
@@ -725,16 +837,21 @@ function spawnPlugin(pluginCode) {
 }
 ```
 
+</details>
+
 ---
 
 ## Conformance
 
+<details>
+<summary>174/177 on the reactive-framework-test-suite; what lite-signal does and doesn't, by intent.</summary>
+
 lite-signal is evaluated against the
 [reactive-framework-test-suite](https://github.com/johnsoncodehk/reactive-framework-test-suite),
 the most comprehensive behavioral test battery for JavaScript reactive
 libraries.
 
-As of **v1.1.2**, the conformance items that were open at v1.1.0 — batch revert
+As of **v1.1.2** — and unchanged through **1.1.4** (the 1.1.4 retracking rewrite is verified behavior-preserving by `retracking.difftest.mjs`: 20,000 direct + 10,000 batched writes, 0 disagreements) — the conformance items that were open at v1.1.0 — batch revert
 detection (#123 / #132 / #147), throw isolation in flush (#121), and
 inner-write propagation through computed chains (#180 / #213) — are **closed**
 (landed in v1.1.1). The remaining gaps are one deliberate design choice (#179,
@@ -763,6 +880,10 @@ more useful to library users than a green checkmark.
   and most others by one re-evaluation per write.
 - **Auto-unsubscribe** on first-run effect throws — matches preact, reatom,
   solid. Half the field leaks the subscription.
+- **Observer-lifecycle introspection** (`hasObservers` / `observeObservers`,
+  1.1.4): the 0→1 and 1→0 observer transitions are first-class, zero-cost-when-
+  unused hooks — the basis for auto-pausing a clock or RAF loop only while a
+  derived value is watched. Few signal libraries expose this.
 
 ### What lite-signal does NOT do yet
 
@@ -790,10 +911,15 @@ The remaining open items, by intent.
 Per-test results, the runner adapter, and reproductions live in
 `/conformance/`.
 
+</details>
+
 ---
 
 ## FAQ
 
+<details>
+<summary>Microtasks, dual capacities, Object.is, destroy(), framework integration, dep-order stability.</summary>
+
 **Why no microtask scheduler?**
 Microtask schedulers solve a real problem (deduplicating multiple `set()`s into one effect run) but introduce a worse one: causal opacity. When `signal.set(x)` returns, you don't know whether your effect has run yet. `lite-signal` chooses synchronous flush + explicit `batch()` for the same deduplication outcome with predictable timing.
 
@@ -818,6 +944,8 @@ The cleanup runs *before* the next computeFn body, so the set's notification arr
 **Is the dep order stable across re-runs?**
 Yes, if your computeFn reads its deps in the same order each invocation. The `currentDep` cursor walks the existing dep list and tries to match; matches reuse the existing link (zero alloc), mismatches insert/remove. Stable order = stable performance.
 
+</details>
+
 ---
 
 ## npm scripts
@@ -825,8 +953,9 @@ Yes, if your computeFn reads its deps in the same order each invocation. The `cu
 ```bash
 npm test          # behavior suite, ~1.3s
 npm run test:gc   # zero-gc suite, requires --expose-gc, ~3s
-npm run bench     # comparative benchmark, ~5min wall clock
-npm run verify    # all of the above; gate for publish
+npm run bench     # comparative benchmark vs alien-signals (results.txt), ~5min
+npm run bench-reactive  # 5-framework reactivity suite (resultsReactive.txt)
+npm run verify    # test + test:gc + sanity bench; gate for publish
 ```
 
 ---

package/Signal.d.ts

@@ -92,6 +92,35 @@ export interface RegistryStats {
     activeNodes: number;
 }
 
+// ─── Observer-lifecycle introspection (1.1.4) ─────────────────────────────────
+
+/** Whether a described node is a signal, a computed, or an effect. */
+export type NodeKind = "signal" | "computed" | "effect";
+
+/** Non-perturbing snapshot of a graph neighbour yielded by the `forEach*` walkers. */
+export interface NodeDescriptor {
+    /** Stable per-allocation node id (1.1.5+). Dedupe key for graph traversal, and the
+     *  re-walk handle: a descriptor may be passed back into forEachObserver/forEachSource. */
+    id: number;
+    kind: NodeKind;
+    /** The node's current value (last stored/computed value; an effect's is its body return). */
+    value: unknown;
+}
+
+/** Transition callbacks for {@link Registry.observeObservers}. */
+export interface ObserveObserversHooks {
+    /** Fired on the 0→1 observer transition (after registration). */
+    onConnect?: () => void;
+    /** Fired on the 1→0 observer transition. */
+    onDisconnect?: () => void;
+}
+
+/** Stops an {@link Registry.observeObservers} subscription. Idempotent. */
+export type Unobserve = () => void;
+
+/** Anything carrying a node identity that the introspection surface can read. */
+export type ReactiveHandle = Signal<any> | Computed<any>;
+
 // ─── Errors ───────────────────────────────────────────────────────────────────
 
 /** Thrown when a pool ceiling is hit. */
@@ -137,6 +166,22 @@ export interface Registry {
      *  False inside `untrack`, `subscribe` callbacks, `onCleanup` bodies, and
      *  outside any observer. Use for lazy-allocation wrappers like lite-store. */
     isTracking(): boolean;
+    /** O(1): does this source have at least one live observer right now? A `peek` does not count. */
+    hasObservers(handle: ReactiveHandle): boolean;
+    /** Auto-pause hook: fires `onConnect` on the 0→1 observer transition and `onDisconnect`
+     *  on 1→0, after registration (transition-only — no immediate fire if already observed).
+     *  Re-tracking a persistently-read source does not churn. Returns an idempotent unobserve.
+     *  @throws TypeError if `handle` is not a reactive handle. */
+    observeObservers(handle: ReactiveHandle, hooks?: ObserveObserversHooks): Unobserve;
+    /** Walk the observers (subscribers) of `handle`, newest-first. No-op on a non-handle. */
+    forEachObserver(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+    /** Walk the sources (dependencies) of `handle`. No-op on a non-handle. */
+    forEachSource(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+    /** Stable node id of `handle` (1.1.5+), or undefined for a non-handle. */
+    nodeId(handle: ReactiveHandle): number | undefined;
+    /** The own descriptor of `handle` (1.1.5+), or undefined for a non-handle. Re-walkable:
+     *  the returned descriptor may be passed back into forEachObserver/forEachSource. */
+    describe(handle: ReactiveHandle): NodeDescriptor | undefined;
     onCleanup(fn: () => void): void;
     stats(): RegistryStats;
     /** Reset everything: nodes, links, queues, global clock. Outstanding dispose
@@ -169,6 +214,18 @@ export function batch<T>(fn: () => T): T;
 export function untrack<T>(fn: () => T): T;
 /** Top-level binding of {@link Registry.isTracking} against the default registry. */
 export function isTracking(): boolean;
+/** Top-level binding of {@link Registry.hasObservers}. */
+export function hasObservers(handle: ReactiveHandle): boolean;
+/** Top-level binding of {@link Registry.observeObservers}. */
+export function observeObservers(handle: ReactiveHandle, hooks?: ObserveObserversHooks): Unobserve;
+/** Top-level binding of {@link Registry.forEachObserver}. */
+export function forEachObserver(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+/** Top-level binding of {@link Registry.forEachSource}. */
+export function forEachSource(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+/** Top-level binding of {@link Registry.nodeId}. */
+export function nodeId(handle: ReactiveHandle): number | undefined;
+/** Top-level binding of {@link Registry.describe}. */
+export function describe(handle: ReactiveHandle): NodeDescriptor | undefined;
 export function onCleanup(fn: () => void): void;
 export function stats(): RegistryStats;
 export declare function destroy(): void;