@blu3ph4ntom/inval 0.1.0 → 0.1.1

package/README.md

@@ -11,7 +11,7 @@ inval:  50 widgets, change 1 width   4,230K ops/s  (10x faster)
 
 ---
 
-## Why Enterprise Teams Choose Inval
+## Why Enterprise Teams Should Choose Inval
 
 ### The Problem Nobody Talks About
 
@@ -49,6 +49,32 @@ bun add @blu3ph4ntom/inval
 pnpm add @blu3ph4ntom/inval
 ```
 
+### Why More Code?
+
+Yes, `const area = node({ dependsOn: { w, h }, compute: ({ w, h }) => w * h })` is more verbose than `const area = width * height`.
+
+**But consider what's missing from the simple version:**
+
+```typescript
+// This is what your simple version is actually doing:
+function getArea() {
+  // Did width or height change since last call?
+  // Do I need to recompute or can I return cached?
+  // What if I forgot a dependency and it's stale?
+  // What if height depends on width indirectly?
+  // How do I debug why it recomputed?
+  return width * height
+}
+```
+
+Inval gives you:
+- **Explicit dependencies** — No more guessing what's cached
+- **Debug tools** — `why(node)` tells you exactly what invalidated
+- **Incremental updates** — Only recompute what changed
+- **Production confidence** — 71 tests, deterministic behavior
+
+**For simple cases** — use plain variables. **When layout gets complex** — Inval scales.
+
 ---
 
 ## The Inval Difference
@@ -56,24 +82,26 @@ pnpm add @blu3ph4ntom/inval
 ### Before (Naive Approach)
 
 ```typescript
-// Every width change recomputes EVERYTHING
-const width = 800
-const contentWidth = width - sidebar
-const cardHeight = textHeight(contentWidth, cardText)
-const rowOffset = index * cardHeight
-const visibleRange = computeVisible(scroll, rowOffset)
-// 50 widgets × 6 computations each = 300 recomputes
+// Without a dependency graph, you must recompute everything
+// or manually track what depends on what
+function updateLayout(newWidth) {
+  const contentWidth = newWidth - sidebarWidth
+  const cardHeight = textHeight(contentWidth, cardText)
+  const rowOffset = index * cardHeight
+  const visibleRange = computeVisible(scrollTop, rowOffset)
+  // Either recompute all of these, or try to memoize each one
+}
 ```
 
 ### After (With Inval)
 
 ```typescript
-import { input, node, batch, why } from '@blu3ph4ntom/inval'
+import { input, node } from '@blu3ph4ntom/inval'
 
 const width = input(800)
 const contentWidth = node({
   dependsOn: { w: width },
-  compute: ({ w }) => w - sidebar
+  compute: ({ w }) => w - sidebarWidth
 })
 const cardHeight = node({
   dependsOn: { cw: contentWidth },
@@ -82,14 +110,14 @@ const cardHeight = node({
 
 width.set(600)
 // Only contentWidth and cardHeight recompute
-// visibleRange? NOT dirty — it doesn't depend on width
-// 5 widgets × 2 computations = 10 recomputes (30x less)
+// visibleRange stays clean if it doesn't depend on width
+// The library handles incremental updates automatically
 ```
 
 **You get:**
-- 10x faster performance on layout changes
+- 10x faster performance on layout changes (benchmarked)
 - Exact knowledge of what recomputed (via `why()`)
-- Confidence your reflows are minimal and correct
+- No more manual memoization guessing
 
 ---
 
@@ -122,12 +150,14 @@ why(area)         // ['area', 'width'] — trace exact invalidation path
 ### Dashboard: 50 Widgets, One Width Change
 
 ```
-naive:  417,000 ops/s  (recomputes all 50 × 6 = 300 computations)
-inval:  4,230,000 ops/s  (recomputes only 10 computations)
+naive:  417,000 ops/s  (recomputes all computed nodes)
+inval:  4,230,000 ops/s  (recomputes only affected nodes)
 ─────────────────────────────────────────────────────────────
 10.1x faster in production-like scenario
 ```
 
+Note: The naive comparison uses direct function calls without any optimization (no memoization, no dependency tracking). Your actual results will vary based on implementation.
+
 ### Virtualized List: 1000 Items, Width Change
 
 ```
@@ -424,8 +454,19 @@ open demo/pure/index.html           # With inval
 open demo/without-inval/index.html  # Without inval (naive)
 ```
 
+### Live Demo
+
+A side-by-side dashboard demo showing the difference between using Inval vs naive approach:
+
+- **demo/pure/index.html** — Uses Inval for incremental updates
+- **demo/without-inval/index.html** — Recomputes everything on each change
+
+![Dashboard Demo](docs/dashboard-final.png)
+
+The left panel uses Inval: notice the cached count stays high after initial computation. The right panel recomputes everything on each change.
+
 ---
 
 ## License
 
-MIT — free for commercial use.
+MIT — free for commercial use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blu3ph4ntom/inval",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Deterministic, incremental layout invalidation engine",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -47,14 +47,13 @@
   "license": "MIT",
   "devDependencies": {
     "esbuild": "^0.25.11",
-    "playwright": "^1.59.1",
     "typescript": "^5.7.0"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/blu3ph4ntom/inval.git"
+    "url": "https://github.com/Blu3ph4ntom/inval.git"
   },
-  "homepage": "https://github.com/blu3ph4ntom/inval#readme",
+  "homepage": "https://github.com/Blu3ph4ntom/inval#readme",
   "bugs": {
     "url": "https://github.com/blu3ph4ntom/inval/issues"
   },