@zakkster/lite-signal 1.0.3 → 1.0.5

package/README.md

@@ -3,6 +3,7 @@
 > 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)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
 [![bundle size](https://img.shields.io/badge/min%2Bgz-~3.2KB-blue?style=flat-square)](https://bundlephobia.com/package/@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)
@@ -365,7 +366,7 @@ 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 × 12 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 × 50+ outer invocations (median reported). Newer/faster machines shift all libs up proportionally; the relative ordering between libs is what matters.
 
 | Scenario   | What it stresses                | lite-signal | alien-signals | preact     | solid-js  |
 | ---------- | -------------------------------- | ----------- | ------------- | ---------- | --------- |
@@ -382,7 +383,7 @@ On allocation pressure, `lite-signal` is alone in the zero-Δheap band: ~15 KB o
 
 > 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.
 
-The benchmark harness is in [`bench/benchmark.mjs`](./bench/benchmark.mjs). It:
+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:
 
 1. Writes every effect's output to a shared `Float64Array(4096)` exposed on `globalThis` — V8 cannot prove these writes are dead.
 2. Uses the **client** Solid runtime (`solid-js/dist/solid.js`), not the SSR stub Node resolves to by default. The default Node resolution silently no-ops effects, which is how earlier benchmarks across the ecosystem have reported Solid at ~50 GHz throughput.
@@ -447,6 +448,34 @@ npm run verify   # test + test:gc + a sanity bench
 
 ---
 
+## Performance Trade-offs & Topology Scaling
+
+`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. 
+
+**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:
+
+#### 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.
+
+*Andrii's benchmark results for dynamic topologies:*
+| Scenario | alien-signals | reflex | lite-signal |
+| :--- | :--- | :--- | :--- |
+| **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`.
+
+### Roadmap: v1.1
+We are actively working on a v1.1 architectural update to address this topology degradation while maintaining the zero-GC contract. By moving to a version-stamped dependency reconciliation pass (`lastSeenInEval`) with a pre-allocated scratch buffer, we expect to drop dynamic read costs to $O(1)$ unconditionally.
+
+---
+
 ## What this is not
 
 - **A virtual DOM, JSX runtime, or rendering library.** It's the substrate. Plug it under whatever rendering layer you like.
@@ -584,4 +613,4 @@ MIT © Zahary Shinikchiev
 
 ---
 
-> Part of the **@zakkster** zero-GC stack: [`lite-ecs`](https://www.npmjs.com/package/@zakkster/lite-ecs) · [`lite-ease`](https://www.npmjs.com/package/@zakkster/lite-ease) · [`lite-pointer-tracker`](https://www.npmjs.com/package/@zakkster/lite-pointer-tracker) · [`lite-bmfont`](https://www.npmjs.com/package/@zakkster/lite-bmfont) · [`lite-color`](https://www.npmjs.com/package/@zakkster/lite-color)
+> Part of the **@zakkster** zero-GC stack: [`lite-ecs`](https://www.npmjs.com/package/@zakkster/lite-ecs) · [`lite-ease`](https://www.npmjs.com/package/@zakkster/lite-ease) · [`lite-pointer-tracker`](https://www.npmjs.com/package/@zakkster/lite-pointer-tracker) · [`lite-bmfont`](https://www.npmjs.com/package/@zakkster/lite-bmfont) · [`lite-color`](https://www.npmjs.com/package/@zakkster/lite-color)

package/llms.txt

@@ -117,7 +117,7 @@ class CapacityError extends Error {
 }
 ```
 
-## Benchmark snapshot (Node 22, 2016-era Intel MacBook Pro, 20K iter × 5 runs × 12 invocations)
+## Benchmark snapshot (Node 22, 2016-era Intel MacBook Pro, 20K iter × 5 runs × 50+ invocations)
 
 | Scenario                                | lite-signal | alien-signals | preact   | solid    |
 | --------------------------------------- | ----------- | ------------- | -------- | -------- |
@@ -199,4 +199,4 @@ npm install @zakkster/lite-signal
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@zakkster/lite-signal",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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",
   "type": "module",
-  "main": "Signal.js",
-  "module": "Signal.js",
-  "types": "Signal.d.ts",
+  "main": "./Signal.js",
+  "module": "./Signal.js",
+  "types": "./Signal.d.ts",
   "exports": {
     ".": {
-      "types": "Signal.d.ts",
-      "import": "Signal.js",
-      "default": "Signal.js"
+      "types": "./Signal.d.ts",
+      "import": "./Signal.js",
+      "default": "./Signal.js"
     }
   },
   "files": [