@zakkster/lite-signal 1.1.3 → 1.1.4

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)
@@ -296,6 +298,31 @@ 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`
+```
+
+Four functions (top-level + per-registry), added in 1.1.4, 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 `{ kind, value }` descriptor (`kind` ∈ `"signal" | "computed" | "effect"`). No-op 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
@@ -522,22 +549,23 @@ These are the questions you'd ask in a code review, with the answers:
 
 ## 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 × 10 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.4** 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).
 
-| 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** | 194K       | **+62%**      |
+| **BROADCAST** | 1 signal → 1000 effects (fan-out)    | **26K**     | 22K           | **+22%**      |
+| **KAIROS**    | 1 signal → 1000 computeds → 1 effect | **14K**     | 12K           | **+12%**      |
+| **DEEP CHAIN** | 256-deep computed chain → 1 effect  | 53K         | **60K**       | −11%          |
+| **WIDE DENSE** | 5 layers × ~200 wide, dense fan-in  | **7K**      | 6K            | **+6%** ⬆     |
+| **Δheap MUX**  | transient alloc pressure, 20K iters | **0.3 KB**  | 3,907 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 **+62%**, **BROADCAST** (fan-out) by **+22%**, and **KAIROS** (one source feeding a wide layer of memos) by **+12%** — 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 **−11% 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 **29 MB** in the same loop. 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 stable 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.
 
-> 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:
 
@@ -571,6 +599,10 @@ Three tiers, all reproducible.
 - **`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 (1.1.4 fix). A stopped effect must not re-subscribe to a signal read later in the same run; self-dispose must leave no orphaned link; a throwing effect setup must leave no live subscription; normal and dynamic re-tracking stay unaffected.
 
 ```bash
 npm test
@@ -593,7 +625,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
@@ -611,27 +643,38 @@ npm run verify   # test + test:gc + a sanity bench
 
 `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.4 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.4) | result |
+| :--- | :--- | :--- | :--- |
+| **LARGE WEB APP** (≈ 1000x12) | 3026ms | 2736ms | **lite +11%** |
+| **WIDE DENSE** (≈ 1000x5) | 2960ms | 2802ms | **lite +6%** |
+| **SMALL SELECTIVE** (≈ 64x6) | 2985ms | 1868ms | **lite +60%** |
+
+The cross-framework reactivity suite agrees independently: `dyn: large web app` and `dyn: wide dense` are now wins there too, and lite-signal is the fastest of five frameworks on both (see [`resultsReactive.txt`](./resultsReactive.txt)). The new 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.4 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, −11%).
 
-### 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.
+### 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.
 
 ---
 
@@ -639,11 +682,34 @@ 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
 
 Pure ES2020 + `Object.is` + `Int32 | 0`. Runs anywhere that runs modern JavaScript.
@@ -734,7 +800,7 @@ lite-signal is evaluated against the
 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 +829,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
 
@@ -825,8 +895,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,32 @@ 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 {
+    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 +163,17 @@ 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;
     onCleanup(fn: () => void): void;
     stats(): RegistryStats;
     /** Reset everything: nodes, links, queues, global clock. Outstanding dispose
@@ -169,6 +206,14 @@ 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;
 export function onCleanup(fn: () => void): void;
 export function stats(): RegistryStats;
 export declare function destroy(): void;

package/Signal.js

@@ -1,8 +1,33 @@
 /**
- * @zakkster/lite-signal v1.1.2
+ * @zakkster/lite-signal v1.1.4
  * --------------------
  * Zero-GC reactive graph.
  *
+ * CHANGES vs 1.1.2 (both perf-only; public surface and semantics unchanged):
+ *  1. pullComputed clean short-circuit. markDownstream already stamps markEpoch
+ *     on every node in a changed signal's transitive cone; pullComputed now uses
+ *     it to return a cached value in O(1) when no mark landed since the last eval,
+ *     instead of walking (and recursively pulling) the whole dependency subtree.
+ *     Erases the dynamic-graph regression (batched read-after-write workloads):
+ *     "large web app" 4824ms -> 650ms, "wide dense" 4378ms -> 908ms locally.
+ *  2. allocateLink: the O(N) linear headDep scan on a cursor miss is replaced by
+ *     an O(1) source.tailSub dedup. Dependency re-tracking is now O(N) regardless
+ *     of read order, not O(N^2). Wide reordering nodes: ~50x locally (600-dep
+ *     flip: 2810ms -> 46ms). First-track of a wide node: ~4.4x (48ms -> 10ms).
+ *     SEVER-FIRST: on a cursor-miss divergence the unmatched dep tail is freed
+ *     BEFORE any new link is allocated, so peak link usage never exceeds steady
+ *     state (ZERO pool debt). A divergent re-track therefore cannot trigger a
+ *     mid-compute pool growth under tight maxLinks + "throw" — the zero-GC budget
+ *     holds. (The alternative "splice" variant is ~equal speed but transiently
+ *     holds up to one node's fan-in of extra links until end-of-frame severTail.)
+ *
+ * EDGE NOTE (2): a node that reads the SAME source twice within one body, with a
+ * nested computed that also reads that source evaluated in between, retains ONE
+ * redundant dependency link for the node's lifetime. It is value-correct, bounded
+ * (does not grow across re-tracks), and reclaimed on dispose/destroy. The previous
+ * O(N) scan collapsed this to a single link; the O(1) dedup cannot see past a
+ * nested re-link of the same source. This is a deliberate cost/correctness trade.
+ *
  * Architecture: monomorphic object pool + versioned push-pull propagation
  * + SMI modular arithmetic for 32-bit version-wrap safety.
  *
@@ -79,6 +104,8 @@ class ReactiveNode {
 
         // Pool free-list pointer.
         this.nextFree = null;
+
+        this.schedulerThunk = undefined;
     }
 }
 
@@ -151,13 +178,19 @@ export function createRegistry(config = {}) {
 
     // --- ZERO-GC OBJECT POOLS ---
     const nodePool = [];
+
     for (let i = 0; i < currentNodesCapacity; i++) nodePool[i] = new ReactiveNode();
+
     let freeNodeHead = nodePool[0];
+
     for (let i = 0; i < currentNodesCapacity - 1; i++) nodePool[i].nextFree = nodePool[i + 1];
 
     const linkPool = [];
+
     for (let i = 0; i < currentLinkCapacity; i++) linkPool[i] = new ReactiveLink();
+
     let freeLinkHead = linkPool[0];
+
     for (let i = 0; i < currentLinkCapacity - 1; i++) linkPool[i].nextFree = linkPool[i + 1];
 
     let activeNodes = 0 | 0;
@@ -170,6 +203,7 @@ export function createRegistry(config = {}) {
     const effectQueueA = [];
     const effectQueueB = [];
     const markStack = [];
+
     for (let i = 0; i < currentNodesCapacity; i++) {
         effectQueueA[i] = null;
         effectQueueB[i] = null;
@@ -189,6 +223,48 @@ export function createRegistry(config = {}) {
     let isTrackingDeps = false;
     let isFlushing = false;
 
+    // ── Observer-lifecycle introspection (opt-in; zero steady-state cost) ──
+    // lifecycleCount gates the hot-path checks in allocateLink/freeLink: with no node
+    // registered it stays 0 and each check folds to one predicted-false compare.
+    // Callbacks live in a WeakMap, NOT on the node struct, so node creation/footprint
+    // are untouched.
+    let lifecycleCount = 0 | 0;
+    const lifecycleMap = new WeakMap();
+
+    function fireConnect(node) {
+        const e = lifecycleMap.get(node);
+
+        if (e === undefined || e.onConnect === undefined) return;
+
+        const po = currentObserver, pt = isTrackingDeps;
+        currentObserver = null;
+        isTrackingDeps = false;
+
+        try {
+            e.onConnect();
+        } finally {
+            currentObserver = po;
+            isTrackingDeps = pt;
+        }
+    }
+
+    function fireDisconnect(node) {
+        const e = lifecycleMap.get(node);
+
+        if (e === undefined || e.onDisconnect === undefined) return;
+
+        const po = currentObserver, pt = isTrackingDeps;
+        currentObserver = null;
+        isTrackingDeps = false;
+
+        try {
+            e.onDisconnect();
+        } finally {
+            currentObserver = po;
+            isTrackingDeps = pt;
+        }
+    }
+
     // Reused buffer for throw isolation during flush
     const flushErrorBuffer = [];
     let flushErrorCount = 0 | 0;
@@ -205,45 +281,68 @@ export function createRegistry(config = {}) {
      * @private
      */
     function allocateLink(source, target) {
+        // Eligibility gate (lite's analogue of alien-signals' shouldTrack): if the observer was
+        // disposed mid-run — self-dispose, or an outer observer torn down while suspended — its
+        // flags are cleared to 0. Linking would splice a dead, pool-bound node back into `source`'s
+        // subscriber list: a phantom edge that mis-targets the instant the slot is recycled. Skip it.
+        // Cold path only (the inline cursor-hit fast path never reaches here) -> steady-state reads
+        // pay nothing. Legit tracking always passes a live observer (flags != 0).
+        if (target.flags === 0) return null;
         let expected = activeObserverCurrentDep;
+        // Dead on this build: the inline cursor fast-path inside every read
+        // consumes a cursor *hit* before allocateLink runs, so on entry the
+        // cursor never matches `source`. Kept for the direct-call contract.
+        /* c8 ignore start */
         if (expected !== null && expected.source === source) {
             activeObserverCurrentDep = expected.nextDep;
             return expected;
         }
+        /* c8 ignore stop */
+
+        // SEVER-FIRST (zero pool debt): on any divergence, free the entire
+        // unmatched tail BEFORE allocating, so peak link usage never exceeds
+        // steady-state. Trades a little extra free/alloc churn on small reorders
+        // for honoring the zero-GC budget under tight maxLinks + "throw".
+        if (expected !== null) {
+            let stale = expected;
+            let prev = stale.prevDep;
 
-        let existing = target.headDep;
-        let found = null;
-        while (existing !== null) {
-            if (existing.source === source) {
-                found = existing;
-                break;
+            if (prev !== null) prev.nextDep = null; else target.headDep = null;
+
+            target.tailDep = prev;
+
+            while (stale !== null) {
+                let next = stale.nextDep;
+                freeLink(stale, target, stale.source);
+                stale = next;
             }
-            existing = existing.nextDep;
+
+            activeObserverCurrentDep = null;
         }
 
+        // O(1) same-pass dedup (covers double-read of a still-linked source).
+        const lastSub = source.tailSub;
+
+        if (lastSub !== null && lastSub.target === target) return lastSub;
+
         let link;
-        if (found !== null) {
-            link = found;
-            let p = link.prevDep;
-            let n = link.nextDep;
-            if (p !== null) p.nextDep = n; else target.headDep = n;
-            if (n !== null) n.prevDep = p; else target.tailDep = p;
-        } else {
+        {
             if (freeLinkHead === null) {
                 if (policy === "throw") throw new CapacityError("links", currentLinkCapacity);
+
                 const newCap = currentLinkCapacity * 2;
+
                 if (newCap > maxLinkLimit) throw new CapacityError("links", maxLinkLimit);
 
                 const newLinks = new Array(newCap - currentLinkCapacity);
+
                 for (let i = 0; i < newLinks.length; i++) newLinks[i] = new ReactiveLink();
                 for (let i = 0; i < newLinks.length - 1; i++) newLinks[i].nextFree = newLinks[i + 1];
 
                 const startIdx = linkPool.length;
                 linkPool.length = newCap;
 
-                for (let i = 0; i < newLinks.length; i++) {
-                    linkPool[startIdx + i] = newLinks[i];
-                }
+                for (let i = 0; i < newLinks.length; i++) linkPool[startIdx + i] = newLinks[i];
 
                 freeLinkHead = newLinks[0];
                 currentLinkCapacity = newCap;
@@ -259,26 +358,24 @@ export function createRegistry(config = {}) {
 
             link.nextSub = null;
             link.prevSub = source.tailSub;
+            const _was0 = lifecycleCount !== 0 && source.headSub === null;   // 0→1 detect (pre-link)
 
-            if (source.tailSub !== null) source.tailSub.nextSub = link;
-            else source.headSub = link;
+            if (source.tailSub !== null) source.tailSub.nextSub = link; else source.headSub = link;
 
             source.tailSub = link;
-        }
 
-        link.nextDep = expected;
-        if (expected !== null) {
-            let p = expected.prevDep;
-            link.prevDep = p;
-            expected.prevDep = link;
-            if (p !== null) p.nextDep = link; else target.headDep = link;
-        } else {
-            let tail = target.tailDep;
-            link.prevDep = tail;
-            if (tail !== null) tail.nextDep = link; else target.headDep = link;
-            target.tailDep = link;
+            if (_was0) fireConnect(source);
         }
 
+        // Append at the (post-sever) tail.
+        let tail = target.tailDep;
+        link.prevDep = tail;
+        link.nextDep = null;
+
+        if (tail !== null) tail.nextDep = link; else target.headDep = link;
+
+        target.tailDep = link;
+
         return link;
     }
 
@@ -289,6 +386,7 @@ export function createRegistry(config = {}) {
 
         if (pSub !== null) pSub.nextSub = nSub; else source.headSub = nSub;
         if (nSub !== null) nSub.prevSub = pSub; else source.tailSub = pSub;
+        if (lifecycleCount !== 0 && source.headSub === null) fireDisconnect(source);   // 1→0
 
         link.source = null;
         link.target = null;
@@ -305,12 +403,14 @@ export function createRegistry(config = {}) {
     // --- MANUAL MEMORY MANAGEMENT ---
 
     function disposeNode(node) {
+        /* c8 ignore next -- redundant: both callers (effect handle, dispose(api)) pre-check flags!==0; destroy() resets slots inline */
         if (node.flags === 0) return; // Already freed
 
         runCleanup(node);
 
         // 1. Unlink from dependencies
         let dLink = node.headDep;
+
         while (dLink !== null) {
             const next = dLink.nextDep;
             freeLink(dLink, node, dLink.source);
@@ -319,6 +419,7 @@ export function createRegistry(config = {}) {
 
         // 2. Unlink from subscribers
         let sLink = node.headSub;
+
         while (sLink !== null) {
             const target = sLink.target;
             const next = sLink.nextSub;
@@ -345,6 +446,7 @@ export function createRegistry(config = {}) {
         node.computeFn = undefined;
         node.cleanupFn = undefined;
         node.scheduler = undefined;
+        node.schedulerThunk = undefined;
         node.value = undefined;
         node.equals = undefined;
         node.flags = 0;
@@ -417,12 +519,14 @@ export function createRegistry(config = {}) {
     /** Invoke registered cleanup function(s) on `node` and clear. @private */
     function runCleanup(node) {
         const cleanup = node.cleanupFn;
+
         if (cleanup === undefined) return;
 
         const prevObserver = currentObserver;
         const prevTracking = isTrackingDeps;
         currentObserver = null;
         isTrackingDeps = false;
+
         try {
             if (typeof cleanup === "function") cleanup();
             else for (let i = 0; i < cleanup.length; i++) cleanup[i]();
@@ -449,6 +553,7 @@ export function createRegistry(config = {}) {
             let link = n.headSub;
             while (link !== null) {
                 const t = link.target;
+
                 if ((t.markEpoch | 0) !== (globalVersion | 0)) {
                     t.markEpoch = globalVersion | 0;
                     // flags read stays INSIDE the markEpoch guard on purpose: hoisting it
@@ -471,6 +576,7 @@ export function createRegistry(config = {}) {
                         markStack[stackLen++] = t;
                     }
                 }
+
                 link = link.nextSub;
             }
         }
@@ -483,7 +589,9 @@ export function createRegistry(config = {}) {
      */
     function safeExecute(node, gen) {
         if ((node.gen | 0) !== (gen | 0)) return;
+        /* c8 ignore next -- unreachable after the gen guard: every disposal bumps node.gen, so a non-effect slot fails the gen check above first */
         if ((node.flags & FLAG_EFFECT) === 0) return;
+
         executeEffect(node);
     }
 
@@ -515,11 +623,12 @@ export function createRegistry(config = {}) {
 
                 for (let i = 0; i < toRun; i++) {
                     const node = currentQueue[i];
+
                     try {
                         const scheduler = node.scheduler;
+
                         if (scheduler) {
-                            const gen = node.gen | 0;
-                            scheduler(() => safeExecute(node, gen));
+                            scheduler(node.schedulerThunk);
                         } else {
                             executeEffect(node);
                         }
@@ -535,11 +644,13 @@ export function createRegistry(config = {}) {
             normalExit = true;
         } finally {
             isFlushing = false;
+
             if (!normalExit) {
                 // Escaping via CycleError or any non-effect-body throw. Discard
                 // buffered effect errors — the structural failure supersedes them
                 // and prevents leaking stale errors to the next flush call.
                 for (let i = 0; i < flushErrorCount; i++) flushErrorBuffer[i] = null;
+
                 flushErrorCount = 0 | 0;
             }
         }
@@ -553,8 +664,11 @@ export function createRegistry(config = {}) {
             }
             // 2+ errors: snapshot into a fresh array for AggregateError, then clear.
             const errs = flushErrorBuffer.slice(0, flushErrorCount);
+
             for (let i = 0; i < flushErrorCount; i++) flushErrorBuffer[i] = null;
+
             flushErrorCount = 0 | 0;
+
             throw new AggregateError(errs, "Effects threw during flush");
         }
     }
@@ -566,9 +680,12 @@ export function createRegistry(config = {}) {
      */
     function severTail(node) {
         let stale = activeObserverCurrentDep;
+
         if (stale !== null) {
             let prev = stale.prevDep;
+
             if (prev !== null) prev.nextDep = null; else node.headDep = null;
+
             node.tailDep = prev;
 
             while (stale !== null) {
@@ -585,6 +702,7 @@ export function createRegistry(config = {}) {
      * @private
      */
     function executeEffect(node) {
+        /* c8 ignore next -- defense-in-depth: writes during a flush re-queue for the next pass, so an effect cannot synchronously re-enter executeEffect */
         if ((node.flags & FLAG_COMPUTING) !== 0) throw new Error("CycleError: Infinite effect loop detected.");
 
         const isFirst = node.evalVersion === 0;
@@ -593,8 +711,10 @@ export function createRegistry(config = {}) {
             let link = node.headDep;
             const evalVer = node.evalVersion | 0;
             let needsRun = false;
+
             while (link !== null) {
                 const dep = link.source;
+
                 if ((dep.flags & FLAG_COMPUTED) !== 0) pullComputed(dep);
 
                 // Overflow-safe modular arithmetic version check
@@ -659,24 +779,40 @@ export function createRegistry(config = {}) {
             return node.value;
         }
 
+        // CLEAN SHORT-CIRCUIT: markDownstream stamps markEpoch=globalVersion on
+        // every node in a changed signal's transitive cone. If no mark landed
+        // at-or-after our last eval, nothing we depend on changed -> cached value
+        // is still valid; skip the (recursive) dependency walk entirely. O(1).
+        if (node.evalVersion !== 0 && ((node.markEpoch - node.evalVersion) | 0) <= 0) {
+            node.evalVersion = globalVersion | 0;
+
+            if ((node.flags & FLAG_HAS_ERROR) !== 0) throw node.value;
+
+            return node.value;
+        }
+
         let shouldRun = node.evalVersion === 0;
         if (!shouldRun) {
             let link = node.headDep;
             const evalVer = node.evalVersion | 0;
+
             while (link !== null) {
                 const dep = link.source;
+
                 if ((dep.flags & FLAG_COMPUTED) !== 0) pullComputed(dep);
                 // Modular Arithmetic 32-bit Wrap Check
                 if (((dep.version - evalVer) | 0) > 0) {
                     shouldRun = true;
                     break;
                 }
+
                 link = link.nextDep;
             }
         }
 
         if (shouldRun) {
             if ((node.flags & FLAG_COMPUTING) !== 0) throw new Error("CycleError: Circular dependency detected.");
+
             node.flags = node.flags | FLAG_COMPUTING;
 
             // Run cleanups registered during the previous compute pass before re-tracking.
@@ -694,6 +830,7 @@ export function createRegistry(config = {}) {
             try {
                 const newValue = node.computeFn();
                 const eq = node.equals;
+
                 if (node.evalVersion === 0 || !eq || !eq(node.value, newValue)) {
                     node.value = newValue;
                     node.version = globalVersion | 0;
@@ -716,7 +853,9 @@ export function createRegistry(config = {}) {
         }
 
         node.evalVersion = globalVersion | 0;
+
         if ((node.flags & FLAG_HAS_ERROR) !== 0) throw node.value;
+
         return node.value;
     }
 
@@ -748,6 +887,7 @@ export function createRegistry(config = {}) {
                 // frame entirely. Only a cursor miss falls through to the cold path,
                 // where allocateLink re-reads the cursor for its relink logic.
                 const expected = activeObserverCurrentDep;
+
                 if (expected !== null && expected.source === node) {
                     activeObserverCurrentDep = expected.nextDep;
                 } else {
@@ -756,9 +896,11 @@ export function createRegistry(config = {}) {
             }
             return node.value;
         };
+
         read.peek = () => node.value;
         read.set = (value) => {
             const eq = node.equals;
+
             if (eq && eq(node.value, value)) return;
 
             // Revert capture: first .set() of this signal inside the current batch.
@@ -798,6 +940,7 @@ export function createRegistry(config = {}) {
                 const val = read();
                 const prevTracking = isTrackingDeps;
                 isTrackingDeps = false;
+
                 try {
                     fn(val);
                 } finally {
@@ -809,6 +952,7 @@ export function createRegistry(config = {}) {
         // Secret pointer for safe, isolated disposal without allocating closures
         read[NODE_PTR] = node;
         read[NODE_GEN] = node.gen | 0;
+
         return read;
     }
 
@@ -835,6 +979,7 @@ export function createRegistry(config = {}) {
             if (isTrackingDeps && currentObserver !== null) {
                 // Inlined cursor fast-path — see signal() read for rationale.
                 const expected = activeObserverCurrentDep;
+
                 if (expected !== null && expected.source === node) {
                     activeObserverCurrentDep = expected.nextDep;
                 } else {
@@ -843,6 +988,7 @@ export function createRegistry(config = {}) {
             }
             return pullComputed(node);
         };
+
         read.peek = () => pullComputed(node);
 
         read.subscribe = (fn) => {
@@ -852,6 +998,7 @@ export function createRegistry(config = {}) {
                 const val = read();
                 const prevTracking = isTrackingDeps;
                 isTrackingDeps = false;
+
                 try {
                     fn(val);
                 } finally {
@@ -862,6 +1009,7 @@ export function createRegistry(config = {}) {
 
         read[NODE_PTR] = node;
         read[NODE_GEN] = node.gen | 0;
+
         return read;
     }
 
@@ -891,9 +1039,11 @@ export function createRegistry(config = {}) {
         statEffects = (statEffects + 1) | 0;
 
         let firstRunError = null;
+
         if (scheduler) {
             const gen = node.gen | 0;
-            scheduler(() => safeExecute(node, gen));
+            node.schedulerThunk = () => safeExecute(node, gen);
+            scheduler(node.schedulerThunk);
         } else {
             try {
                 executeEffect(node);
@@ -906,6 +1056,7 @@ export function createRegistry(config = {}) {
 
         let disposed = false;
         const birthGen = node.gen | 0;
+
         const disposeFn = function dispose() {
             if (disposed) return;
             disposed = true;
@@ -926,6 +1077,7 @@ export function createRegistry(config = {}) {
             disposeFn();
             throw firstRunError;
         }
+
         return disposeFn;
     }
 
@@ -974,9 +1126,12 @@ export function createRegistry(config = {}) {
     function batch(fn) {
         if (batchDepth === 0) {
             batchEpoch = (batchEpoch + 1) | 0;
+            /* c8 ignore next -- 2^32 wraparound sentinel; unreachable without ~4e9 batches */
             if (batchEpoch === 0) batchEpoch = 1 | 0;   // preserve the 0 sentinel
         }
+
         batchDepth = (batchDepth + 1) | 0;
+
         try {
             return fn();
         } finally {
@@ -994,25 +1149,12 @@ export function createRegistry(config = {}) {
      * @returns {T}
      */
     /**
-     * Returns true iff a read RIGHT NOW would record a dependency in the current
-     * call stack: an observer body is on the stack AND tracking is enabled.
-     *
-     * Mirrors the engine's own read-trap predicate (both flags checked). Returns
-     * false inside `untrack()`, inside `signal.subscribe`'s callback (which
-     * inlines the same untracked-notify pattern), inside `runCleanup` bodies,
-     * and outside any observer.
-     *
-     * Use case: wrapper libraries (lite-store, lite-query, lite-form) that
-     * lazily allocate reactive primitives on property reads — gating on
-     * isTracking() lets them skip allocation when reads happen outside a
-     * reactive context, preserving the zero-GC contract.
-     *
-     * Cost: two closure-variable loads, one AND, one return. ~1–2 ns.
-     *
-     * Note: per-registry. Wrappers operating against a non-default registry
-     * MUST call that registry's `isTracking()`, not the top-level one — each
-     * registry has its own tracking state.
-     *
+     * Returns true iff a read RIGHT NOW would record a dependency on this
+     * registry. Mirrors the engine's own read-trap predicate (both flags).
+     * False inside untrack(), subscribe callbacks, onCleanup bodies,
+     * watch/when callbacks, and outside any observer. For wrapper libraries
+     * (lite-store, lite-query, lite-form) that lazily allocate signals on
+     * property reads. Per-registry. ~1-2 ns.
      * @returns {boolean}
      */
     function isTracking() {
@@ -1022,6 +1164,7 @@ export function createRegistry(config = {}) {
     function untrack(fn) {
         const prev = isTrackingDeps;
         isTrackingDeps = false;
+
         try {
             return fn();
         } finally {
@@ -1039,6 +1182,7 @@ export function createRegistry(config = {}) {
     function onCleanup(fn) {
         if (currentObserver !== null) {
             const existing = currentObserver.cleanupFn;
+
             if (existing === undefined) currentObserver.cleanupFn = fn;
             else if (typeof existing === "function") currentObserver.cleanupFn = [existing, fn];
             else existing.push(fn);
@@ -1075,6 +1219,7 @@ export function createRegistry(config = {}) {
             n.cleanupFn = undefined;
             n.equals = undefined;
             n.scheduler = undefined;
+            n.schedulerThunk = undefined;
             n.flags = 0;
             n.headDep = null;
             n.tailDep = null;
@@ -1089,11 +1234,15 @@ export function createRegistry(config = {}) {
             n.preBatchVersion = 0;
             // Bump gen so any scheduler trampolines holding a stale node ref bail.
             n.gen = (n.gen + 1) | 0;
+
             if (i < currentNodesCapacity - 1) n.nextFree = nodePool[i + 1];
         }
+
         nodePool[currentNodesCapacity - 1].nextFree = null;
         freeNodeHead = nodePool[0];
 
+        // ... remainder of destroy() stays exactly the same
+
         for (let i = 0; i < currentLinkCapacity; i++) {
             const l = linkPool[i];
             l.source = null;
@@ -1104,6 +1253,7 @@ export function createRegistry(config = {}) {
             l.nextSub = null;
             if (i < currentLinkCapacity - 1) l.nextFree = linkPool[i + 1];
         }
+
         linkPool[currentLinkCapacity - 1].nextFree = null;
         freeLinkHead = linkPool[0];
 
@@ -1127,7 +1277,76 @@ export function createRegistry(config = {}) {
         flushErrorBuffer.length = 0; // release the backing array
     }
 
-    return {signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy, isTracking};
+    function hasObservers(handle) {
+        const node = handle != null ? handle[NODE_PTR] : undefined;
+        return node !== undefined && node.headSub !== null;
+    }
+
+    function observeObservers(handle, opts) {
+        const node = handle != null ? handle[NODE_PTR] : undefined;
+        if (node === undefined) throw new TypeError("observeObservers: argument is not a reactive handle");
+        let e = lifecycleMap.get(node);
+        if (e === undefined) {
+            e = {onConnect: undefined, onDisconnect: undefined};
+            lifecycleMap.set(node, e);
+            lifecycleCount = (lifecycleCount + 1) | 0;
+        }
+        if (opts !== undefined) {
+            if (opts.onConnect !== undefined) e.onConnect = opts.onConnect;
+            if (opts.onDisconnect !== undefined) e.onDisconnect = opts.onDisconnect;
+        }
+        let live = true;
+        return () => {
+            if (!live) return;
+            live = false;
+            if (lifecycleMap.delete(node)) lifecycleCount = (lifecycleCount - 1) | 0;
+        };
+    }
+
+    function describeNode(node) {
+        const fl = node.flags;
+        const kind = (fl & FLAG_EFFECT) !== 0 ? "effect" : (fl & FLAG_COMPUTED) !== 0 ? "computed" : "signal";
+        return {kind, value: node.value};
+    }
+
+    function forEachObserver(handle, fn) {
+        const node = handle != null ? handle[NODE_PTR] : undefined;
+        if (node === undefined) return;
+        let l = node.headSub;
+        while (l !== null) {
+            const nx = l.nextSub;
+            fn(describeNode(l.target));
+            l = nx;
+        }
+    }
+
+    function forEachSource(handle, fn) {
+        const node = handle != null ? handle[NODE_PTR] : undefined;
+        if (node === undefined) return;
+        let l = node.headDep;
+        while (l !== null) {
+            const nx = l.nextDep;
+            fn(describeNode(l.source));
+            l = nx;
+        }
+    }
+
+    return {
+        signal,
+        computed,
+        effect,
+        dispose,
+        batch,
+        untrack,
+        onCleanup,
+        stats,
+        destroy,
+        isTracking,
+        hasObservers,
+        observeObservers,
+        forEachObserver,
+        forEachSource
+    };
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -1178,13 +1397,28 @@ export function untrack(fn) {
 
 /**
  * True iff a read RIGHT NOW would record a dependency on the default registry.
- * See {@link createRegistry} for the per-registry version. Wrappers operating
- * against a non-default registry MUST call THAT registry's `isTracking()`.
+ * See {@link createRegistry} for the per-registry version.
  */
 export function isTracking() {
     return defaultRegistry.isTracking();
 }
 
+export function hasObservers(handle) {
+    return defaultRegistry.hasObservers(handle);
+}
+
+export function observeObservers(handle, opts) {
+    return defaultRegistry.observeObservers(handle, opts);
+}
+
+export function forEachObserver(handle, fn) {
+    return defaultRegistry.forEachObserver(handle, fn);
+}
+
+export function forEachSource(handle, fn) {
+    return defaultRegistry.forEachSource(handle, fn);
+}
+
 /** @type {Registry["onCleanup"]} */
 export function onCleanup(fn) {
     return defaultRegistry.onCleanup(fn);

package/Watch.js

@@ -121,7 +121,10 @@ export function when(predicate, callback) {
 
     stopFn = effect(() => {
         // Defense-in-depth: even if dispose timing lets one more evaluation
-        // through (e.g., during sync propagation), don't fire twice.
+        // through (e.g., during sync propagation), don't fire twice. In practice
+        // stop() disposes this effect before any re-entry, so the early return is
+        // unreachable under the engine's self-cycle no-re-run guard — hence ignored.
+        /* c8 ignore next -- unreachable defensive guard; see comment above */
         if (fired) return;
         if (predicate()) {
             fired = true;

package/llms.txt

@@ -21,6 +21,7 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 - **Untrack**: `untrack(fn)` reads without subscribing.
 - **isTracking**: `isTracking()` returns true iff a read right now would record a dependency on this registry (for wrappers that lazily allocate signals).
 - **onCleanup**: registers teardown for the current computation; fires before each re-run and once on dispose. Works in effects and computeds.
+- **Observer-lifecycle introspection** (1.1.4; top-level + per-registry): `hasObservers(handle)` returns true iff a signal/computed has ≥1 live observer right now (O(1); a `peek` does not count). `observeObservers(handle, { onConnect?, onDisconnect? })` fires on the 0→1 and 1→0 observer transitions (after registration; transition-only) and returns an idempotent unobserve — the auto-pause hook for tickers (lite-time/lite-raf start a source only while it's watched). `forEachObserver(handle, fn)` / `forEachSource(handle, fn)` walk the live graph in either direction, passing a `{ kind, value }` descriptor (`kind` is `"signal" | "computed" | "effect"`) — for inspection (lite-devtools). The surface is gated by an internal counter: zero steady-state cost when nothing is observed. `hasObservers`/`forEach*` no-op on a non-handle; `observeObservers` throws `TypeError`.
 - **Registry**: `createRegistry({ maxNodes, maxLinks, onCapacityExceeded, maxFlushPasses })` creates an isolated reactive world with its own pools. Useful for tests, plugins, multi-tenant sandboxes. Top-level helpers use a default registry created at module load.
 - **CapacityError**: thrown when a fixed-size pool is exhausted under the `"throw"` policy, or when a `"grow"` policy hits the 16× starting-capacity ceiling on links.
 
@@ -45,10 +46,22 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 - `computed()` cache miss — O(deps + body), zero alloc if dep structure is stable.
 - Effect re-run with stable dep order — zero alloc.
 - Stable read order: O(1) per dep via cursor reuse.
-- Chaotic/randomized read order: degrades to O(N) per dep due to list re-insertion.
+- Chaotic/randomized read order: 1.1.4 added version-stamped per-source reconciliation plus a `markEpoch` clean-read short-circuit on the pull, so the prior O(N)-per-dep degradation no longer dominates high-fan-in batched read-after-write — the `dyn: large web app` and `dyn: wide dense` shapes that were the v1.1.x weakness are now the fastest of the five benchmarked frameworks (see resultsReactive.txt). Correctness verified by `retracking.difftest.mjs` (20,000 direct + 10,000 batched writes, 0 disagreements).
 
 ## Version notes
 
+- **1.1.4** (current): combined release — a retracking rewrite plus an observer-lifecycle
+  introspection surface. Drop-in over 1.1.3. **Retracking:** version-stamped O(1)
+  reconciliation + a `markEpoch` clean-read short-circuit replace the cursor strategy's
+  O(N)-per-dep degradation under chaotic high-fan-in batched read-after-write; stable read
+  order is unchanged (still O(1), still zero-alloc). The two documented v1.1.x losses flipped
+  to wins and are now fastest of five frameworks — `dyn: large web app` 6194ms→571ms, `dyn:
+  wide dense` 5115ms→912ms (verified by `retracking.difftest.mjs`: 20k direct + 10k batched, 0
+  disagreements; no regressions elsewhere). **Introspection:** `hasObservers`,
+  `observeObservers`, `forEachObserver`, `forEachSource` (top-level + per-registry), gated by
+  an internal counter so zero steady-state cost when unused. New `test/13-introspection_test.mjs`
+  (10 tests). Internally staged as 1.1.4 + 1.1.5; ships as a single 1.1.4.
+
 - **1.1.3**: adds `isTracking()` (top-level + per-registry). Returns true iff a
   read right now would record a dependency (`isTrackingDeps && currentObserver !== null`).
   False inside `untrack`, `subscribe` callbacks, `onCleanup` bodies, `watch` /
@@ -59,7 +72,7 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
   No behavior or engine changes.
 
 
-- **1.1.2** (current): hot-path micro-optimizations, no behavior/API change.
+- **1.1.2**: hot-path micro-optimizations, no behavior/API change.
   Inlined cursor fast-path in `signal`/`computed` reads (stable-order reads skip
   the `allocateLink` call); zero-allocation creation path (`opts` read defensively
   instead of defaulting to `{}`); single-closure `subscribe`. Owner-tree
@@ -77,8 +90,8 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 ## When NOT to use
 
 - Server-side rendering — no SSR story.
-- Workloads with mostly chaotic read order — `alien-signals` performs better here.
-- If you want time-travel, devtools, or serialization — build those on top.
+- Graph *construction* is allocation-heavy (per-node closures): on create-many micro-benchmarks `alien-signals` builds faster. Real apps build once and update forever — lite-signal leads the update + dynamic-topology rows. (The former "chaotic read order" caveat was closed in 1.1.4.)
+- If you want time-travel or serialization — build those on top. (Graph-inspection devtools are now buildable on the 1.1.4 introspection surface; see lite-devtools.)
 
 ## API summary
 
@@ -91,6 +104,13 @@ function dispose(api: Signal<any> | Computed<any> | Dispose): void;
 function batch<T>(fn: () => T): T;
 function untrack<T>(fn: () => T): T;
 function isTracking(): boolean;
+function hasObservers(handle: Signal<any> | Computed<any>): boolean;
+function observeObservers(
+  handle: Signal<any> | Computed<any>,
+  hooks?: { onConnect?: () => void; onDisconnect?: () => void }
+): () => void;                          // returns idempotent unobserve
+function forEachObserver(handle: Signal<any> | Computed<any>, fn: (d: NodeDescriptor) => void): void;
+function forEachSource(handle: Signal<any> | Computed<any>, fn: (d: NodeDescriptor) => void): void;
 function onCleanup(fn: () => void): void;
 function stats(): RegistryStats;
 
@@ -114,6 +134,11 @@ interface Computed<T> {
 
 type Dispose = () => void;
 
+interface NodeDescriptor {           // yielded by forEachObserver / forEachSource
+  kind: "signal" | "computed" | "effect";
+  value: unknown;                    // node's current value
+}
+
 interface RegistryConfig {
   maxNodes?: number;                 // default 1024
   maxLinks?: number;                 // default maxNodes * 4
@@ -207,6 +232,13 @@ that dominate UI workloads. alien-signals retains a 15% lead on 256-deep compute
 pipelines, where its flatter internal representation pays off when the propagation
 path is long rather than wide.
 
+These four are the *stable* topologies (unchanged through 1.1.4). The chaotic,
+high-fan-in shapes that were lite-signal's documented weakness — `dyn: large web app`
+and `dyn: wide dense` in the cross-framework reactivity suite — were closed by the
+1.1.4 retracking rewrite and are now the fastest of five frameworks: 571ms / 912ms
+vs alien-signals' 623ms / 1001ms, with preact and vue 10–18× slower. See
+resultsReactive.txt for the full 34-test, 5-framework table.
+
 On allocation pressure, lite-signal is alone in the zero-Δheap band: ~15 KB of
 transient garbage per 20,000-iteration loop, regardless of scenario. preact runs
 ~230 KB per loop; solid runs into single-digit megabytes; alien-signals — which
@@ -264,7 +296,13 @@ sandbox.destroy();   // entire reactive world reset
 - `test/07-dispose.test.mjs` — universal disposal: registry.dispose(api).
 - `test/08-watch.test.mjs` — new watch reactivity tests.
 - `test/09-conformance.test.mjs` — johnsoncodehk/reactive-framework-test-suite conformance fixes tests.
-- `bench/benchmark.mjs`       — comparative benchmark vs alien-signals, preact, solid.
+- `test/10-is-tracking_test.mjs` — `isTracking()` across observer bodies, untracked windows, and outside any observer.
+- `test/11-adopted-reactive_test.mjs` — engine-agnostic edge cases adopted from the wider ecosystem (alien-signals link-integrity #226–228, equality-predicate corners, `update()`/`peek()`/`subscribe` contracts).
+- `test/12-coverage_test.mjs` — targeted public-surface + hot-path branch coverage (top-level routing, clean-read short-circuit, tail severance, scheduler ABA); owner-tree block capability-gated.
+- `test/13-introspection_test.mjs` — observer-lifecycle surface: `hasObservers`, `observeObservers` auto-pause, `forEach*` enumeration (10 tests).
+- `test/14-lifecycle-teardown_test.mjs` — effect-teardown guards: stopped effect doesn't re-subscribe to a signal read later in the same run, self-dispose leaves no orphan link, throwing setup leaves no live subscription (4 tests).
+- `bench/benchmark.mjs`       — anti-DCE throughput harness (ops/s; results.txt).
+- `bench/benchmarkReactive.mjs` — cross-framework reactivity suite vs alien-signals, preact, vue-reactivity, solid (resultsReactive.txt).
 - `demo/index.html`           — interactive visualization of the reactive graph.
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Zero-GC reactive graph. Monomorphic object pool, versioned push-pull propagation, 32-bit modular versioning. Built for hot paths and long-running processes.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
@@ -27,6 +27,7 @@
   "scripts": {
     "test": "node --test --test-reporter=spec",
     "test:gc": "node --expose-gc --test --test-reporter=spec",
+    "test:coverage": "c8 node --test --test-reporter=spec",
     "bench": "node --expose-gc bench/benchmark.mjs",
     "bench-reactive": "node --expose-gc bench/benchmarkReactive.mjs",
     "verify": "npm test && npm run bench"
@@ -57,5 +58,12 @@
   "engines": {
     "node": ">=18"
   },
-  "sideEffects": false
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "c8": "^11.0.0"
+  }
 }