react-state-basis 0.3.4 → 0.4.1

package/README.md

@@ -5,13 +5,15 @@
 <div align="center">
 
 # 📐 react-state-basis
-### Runtime state profiler for React
+### Runtime Architectural Auditor & State Profiler for React
 
 [![npm version](https://img.shields.io/npm/v/react-state-basis.svg?style=flat-square)](https://www.npmjs.com/package/react-state-basis)
 [![GitHub stars](https://img.shields.io/github/stars/liovic/react-state-basis.svg?style=flat-square)](https://github.com/liovic/react-state-basis/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-**Catches redundant state and update chains while your React app runs.**
+**Basis tracks the rhythm of state updates, not the data. It identifies redundant patterns and sync-leaks that standard tools miss.**
+
+> Stop relying on architectural intuition. Start measuring architectural debt.
 
 </div>
 
@@ -26,7 +28,7 @@
 - **Infinite loops** - Circular dependencies that freeze your browser
 - **Tight coupling** - State variables that should be independent but aren't
 
-It works by tracking *when* state updates happen, not *what* the values are.
+It works by tracking *when* state updates happen (temporal patterns), not *what* the values are.
 
 ---
 
@@ -37,7 +39,7 @@ const [user, setUser] = useState(null);
 const [isLoggedIn, setIsLoggedIn] = useState(false);
 
 useEffect(() => {
-  setIsLoggedIn(!!user);  // Double render - flagged as redundant
+  setIsLoggedIn(!!user);  // Double render - flagged as sync leak
 }, [user]);
 
 // ✅ Better
@@ -49,14 +51,40 @@ const isLoggedIn = !!user;  // Computed, no second render
 
 ## See It Work
 
-The optional HUD shows which states update together in real-time:
+The optional HUD shows your state basis matrix in real-time:
 
 <p align="center">
-  <img src="./assets/react-state-basis.gif" width="800" alt="React State Basis Demo" />
+  <img src="./assets/react-state-basis-demo.gif" width="800" alt="React State Basis Demo" />
 </p>
 
 ---
 
+## Real-World Audits
+
+Basis has been tested on major open-source projects to validate detection accuracy:
+
+### Excalidraw (114k+ ⭐)
+**Detected:** Causal Sync Leak in theme state synchronization  
+**Issue:** A `useEffect` was manually syncing theme state, causing an unnecessary double render on every theme toggle  
+**Fix:** [PR #10637](https://github.com/excalidraw/excalidraw/pull/10637) - Replaced with a computed value
+
+<p align="center"> 
+  <img src="./assets/excalidraw-audit.png" width="800" alt="Excalidraw Audit" /> 
+</p>
+
+### shadcn-admin (10k+ ⭐)
+**Detected:** Redundant state pattern in mobile detection hooks  
+**Issue:** Viewport resize events were being synchronized via effects rather than direct subscriptions  
+**Fix:** [PR #274](https://github.com/satnaing/shadcn-admin/pull/274) - Optimized subscription pattern
+
+<p align="center"> 
+  <img src="./assets/shadcn-admin.png" width="800" alt="shadcn Admin Audit" /> 
+</p>
+
+> **Note:** These are proposed architectural improvements. Basis points out patterns worth investigating - the final decision rests with the maintainer.
+
+---
+
 ## Setup (Vite)
 
 ### 1. Install
@@ -91,7 +119,19 @@ root.render(
 );
 ```
 
-That's it. The tool runs automatically in development.
+### 4. Verify It's Working
+
+Add this test pattern to any component:
+```tsx
+const [a, setA] = useState(0);
+const [b, setB] = useState(0);
+
+useEffect(() => {
+  setB(a); // Basis will flag this
+}, [a]);
+```
+
+Trigger an update (e.g., click a button that calls `setA(1)`). You should see a console alert within ~100ms.
 
 ---
 
@@ -99,213 +139,262 @@ That's it. The tool runs automatically in development.
 
 ### Console Alerts
 
-When Basis detects issues, you'll see styled console logs:
-
-**Redundant State:**
+**Redundant Pattern:**
+Detected when two variables move in perfect unison.
 ```
-📐 BASIS | REDUNDANT STATE DETECTED
+📐 BASIS | REDUNDANT PATTERN
 📍 Location: TodoList.tsx
-Pattern: States "todos" and "count" update together 92% of the time.
-One is likely redundant and can be removed.
-
-Suggested fix: Convert "count" to a computed value
+Observation: "todos" and "count" move together.
+One is likely a direct mirror of the other. Confidence: 94%
+Action: Refactor "count" to useMemo.
 ```
 
-**Update Chains:**
+**Sync Leak (Causal Chain):**
+Detected when one variable consistently triggers another with a temporal lag.
 ```
-💡 BASIS | UPDATE CHAIN DETECTED
-Sequence: user ➔ Effect ➔ isLoggedIn
-Pattern: "isLoggedIn" is synchronized via useEffect, causing a second render.
+💡 BASIS | DETECTED SYNC LEAK
+📍 Location: AuthProvider.tsx
+Flow: user ➔ Effect ➔ isLoggedIn
+Context: The engine detected a consistent 20ms lag between these updates.
+Result: This creates a Double Render Cycle.
 ```
 
-**Infinite Loops:**
+**Infinite Loop:**
+Detected when a variable updates too rapidly (circuit breaker).
 ```
-🛑 BASIS | INFINITE LOOP DETECTED
-State variable "counter" is updating too rapidly (25+ times in 500ms).
-Execution halted to prevent browser freeze.
+🛑 BASIS CRITICAL | CIRCUIT BREAKER
+Infinite oscillation detected on: "counter"
+Execution halted to prevent browser thread lock.
 ```
 
 ### Health Report
 
-Check your entire app's state health:
+Check your entire app's state architecture:
 ```tsx
 window.printBasisReport();
 ```
 
 Shows:
-- Efficiency score (how much redundant state you have)
-- Which states are independent vs synchronized
-- Correlation matrix
+- **Health Score** - Percentage of independent vs. synchronized state
+- **Synchronized Clusters** - Groups of variables that move together
+- **Correlation Matrix** - Full pairwise similarity analysis (for <15 variables)
 
 ---
 
-## Testing on Real Projects
-
-I've tested this on a few open-source projects to validate the detection:
-
-### Excalidraw (114k+ ⭐)
-
-**Found:** Theme state being manually synchronized in `useEffect`  
-**Issue:** Double render on every theme change  
-**Fix:** [PR #10637](https://github.com/excalidraw/excalidraw/pull/10637) - replaced with computed value  
-**Status:** Pending review
-
-<p align="center"> 
-  <img src="./assets/excalidraw-audit.png" width="800" alt="Excalidraw Audit" /> 
-</p>
+## How It Works (v0.4.0)
 
-### shadcn-admin (10k+ ⭐)
+### Temporal Cross-Correlation
 
-**Found:** Mobile detection hook with effect-based synchronization  
-**Issue:** Unnecessary re-renders on viewport resize  
-**Fix:** [PR #274](https://github.com/satnaing/shadcn-admin/pull/274) - cleaner subscription pattern  
-**Status:** Pending review
-
-<p align="center"> 
-  <img src="./assets/shadcn-admin.png" width="800" alt="shadcn Admin Audit" /> 
-</p>
-
-> **Note:** These are proposed improvements based on the tool's detection. The maintainers may choose different solutions or determine the patterns are intentional.
+Basis tracks **when** state updates occur, creating a 50-tick timeline for each variable:
+```
+useState("count"): [0,0,1,0,0,1,1,0,...]  (updates at ticks 2, 5, 6)
+useState("total"): [0,0,1,0,0,1,1,0,...]  (same pattern)
+                    ↑ Redundant: identical temporal signature
+```
 
----
+For every pair of variables, Basis checks three temporal relationships:
 
-## How It Works
+1. **Synchronous (Redundancy):** Do they update in the same tick?
+```
+   A: [0,1,0,1,0,...]
+   B: [0,1,0,1,0,...]  → Flagged as redundant
+```
 
-### The Basic Idea
+2. **Lead-Lag (A → B):** Does B consistently follow A in the next tick?
+```
+   A: [0,1,0,1,0,...]
+   B: [0,0,1,0,1,...]  → B follows A (sync leak detected)
+```
 
-The tool records the last 50 "ticks" (roughly 1 second) for each state variable:
+3. **Lead-Lag (B → A):** Does A consistently follow B?
 ```
-useState("count"): [0,1,0,0,1,1,0,0,0,...]
-useState("total"): [0,1,0,0,1,1,0,0,0,...]
-                    ↑ Both update at same times = probably redundant
+   A: [0,0,1,0,1,...]
+   B: [0,1,0,1,0,...]  → A follows B (reverse causality)
 ```
 
-It uses **cosine similarity** (a standard correlation metric) to detect when states update together.
+The engine uses **offset-based comparison** to check these patterns without allocating temporary arrays, ensuring minimal overhead even at high frame rates.
+
+### Performance Optimizations
 
-If similarity > 0.88, it flags them as potentially redundant.
+- **Idle Filtering:** Only analyzes variables with 2+ updates, reducing pairwise comparisons by ~90% in typical applications (measured on Excalidraw's 47-hook codebase)
+- **Batched Analysis:** Runs every 5 ticks (~100ms) to avoid impacting frame budget
+- **Console Throttling:** Same alert won't repeat within 5 seconds
+- **Zero Production Overhead:** Entire library is replaced with no-op shims in production builds
 
-### Why This Works
+### What Gets Flagged?
 
-Most architectural issues create **temporal patterns**:
-- Redundant state → always updates together
-- Update chains → one state updates, then another follows
-- Infinite loops → same state updates rapidly
+**Redundant Pattern Example:**
+```tsx
+// ❌ Before (Basis flags this)
+const [count, setCount] = useState(0);
+const [doubled, setDoubled] = useState(0);
 
-The tool watches for these patterns and alerts you.
+useEffect(() => {
+  setDoubled(count * 2);
+}, [count]);
 
-### What It Doesn't Do
+// ✅ After (Basis suggestion)
+const [count, setCount] = useState(0);
+const doubled = useMemo(() => count * 2, [count]);
+```
 
-❌ Doesn't analyze your code statically  
-❌ Doesn't read variable values  
-❌ Doesn't prove mathematical correctness  
-❌ Doesn't replace code review
+**Sync Leak Example:**
+```tsx
+// ❌ Before (causes double render)
+const [user, setUser] = useState(null);
+const [isLoggedIn, setIsLoggedIn] = useState(false);
 
-It's a **diagnostic tool** - it points out patterns worth investigating.
+useEffect(() => {
+  setIsLoggedIn(!!user);
+}, [user]);
+
+// ✅ After (single render)
+const [user, setUser] = useState(null);
+const isLoggedIn = !!user; // Derived, no effect needed
+```
 
 ---
 
 ## Production Safety
 
-In production builds, the entire tool is removed:
+In production builds, the entire tool is replaced with zero-op shims. **Zero runtime overhead. Zero bundle size increase.**
 ```json
 // package.json - automatic based on NODE_ENV
 "exports": {
   ".": {
     "development": "./dist/index.mjs",
-    "production": "./dist/production.mjs",  // Zero-op shims
+    "production": "./dist/production.mjs",  // No-op shims
     "default": "./dist/production.mjs"
   }
 }
 ```
 
-**Zero runtime overhead. Zero bundle size increase.**
+---
+
+## When to Skip Files
+
+Add `// @basis-ignore` at the top of a file to disable instrumentation:
+```tsx
+// @basis-ignore
+// This file uses third-party library wrappers or hardware-bound synchronization that Basis shouldn't audit.
+```
+
+**Good candidates for skipping:**
+- **High-frequency animations** (>60fps state updates)
+- **WebSocket message handlers** (rapid, intentional updates)
+- **Canvas/WebGL render loops** (performance-critical paths)
+- **Intentional synchronization** (e.g., React Query → local cache mirrors)
+- **Third-party library wrappers** (where you don't control the architecture)
 
 ---
 
 ## Comparison to Other Tools
 
-| Tool | What It Detects | When |
-|------|----------------|------|
-| **React DevTools** | Component renders, props/state values | After the fact |
-| **Why Did You Render** | Unnecessary re-renders | During render |
-| **ESLint exhaustive-deps** | Missing effect dependencies | Static analysis |
-| **react-state-basis** | Redundant state, update chains, loops | Runtime patterns |
+| Tool | Focus | When to Use |
+|------|-------|-------------|
+| **React DevTools** | Component hierarchy & values | Debugging specific components |
+| **Why Did You Render** | Re-render optimization | Performance tuning renders |
+| **ESLint exhaustive-deps** | Static dependency analysis | Preventing missing deps |
+| **react-state-basis** | **Temporal state relationships** | **Finding redundant state & effect chains** |
 
-They're complementary - use them together.
+These tools are complementary - use them together for best results.
 
 ---
 
-## Skipping Files
+## Performance Impact (Measured)
 
-Add this comment to skip noisy files:
-```tsx
-// @basis-ignore
-```
+**Development Mode**
 
-Good for:
-- Animation loops
-- High-frequency timers  
-- WebSocket handlers
-- Performance-critical code
+These measurements were taken using the built-in **Stress Lab** with 100 active hooks and continuous state updates, observed in Chrome DevTools Performance and Web Vitals panels. 
 
----
+Location: `/example`
 
-## Limitations
+**Observed impact:**
 
-### Current Version (v0.3.x)
+* **Per update overhead:** < 0.05ms (O(1) Map-based tracking)
+* **Analysis pass:** ~1.0ms (Zero-copy pointer math)
+* **Frame budget impact:** ~2% during active 100-hook stress testing
+* **Latency (INP):** 80ms (v0.4.0) vs 464ms (v0.3.x legacy engine)
 
-**What works well:**
-- ✅ Detecting obvious redundant state
-- ✅ Flagging effect-driven update chains
-- ✅ Catching infinite loops
-- ✅ Works in typical React apps
+> Results will vary by hardware, browser, and workload. Use the Stress Lab to reproduce and compare Basis ON vs OFF in your own environment.
+
+<p align="center"> 
+  <img src="./assets/react-state-basis-stress.gif" width="800" alt="shadcn Admin Audit" /> 
+</p>
 
-**Known issues:**
-- ⚠️ May miss delayed chains (>20ms apart)
-- ⚠️ Can flag intentional patterns as issues
-- ⚠️ Complex multi-way dependencies might not be caught
-- ⚠️ Requires judgment to interpret results
 
-**False positives happen.** Always verify before refactoring.
+**Production Mode:**
+- Overhead: ~0.01ms per hook call (negligible wrapper overhead)
+- Bundle size: ~2-3 KB minified (no-op wrappers only, no analysis engine)
+- Monitoring logic: 100% removed
+- HUD component: 100% removed
 
 ---
 
-## Roadmap
+## Limitations (v0.4.x)
 
-### v0.4.0 (Next)
-- [ ] Zustand integration
-- [ ] Redux middleware
-- [ ] Better false positive filtering
-- [ ] Automated fix suggestions
+**What works well:**
+- ✅ Detecting synchronous redundant state
+- ✅ Flagging effect-driven update chains (A → Effect → B)
+- ✅ Catching infinite loops before browser freeze
+- ✅ Distinguishing causality from redundancy
+
+**Known edge cases:**
+- ⚠️ **Async gaps:** Updates delayed by >40ms (e.g., slow API responses) may appear independent
+- ⚠️ **Intentional sync:** Sometimes synchronization is required for library compatibility
+- ⚠️ **Complex multi-way dependencies:** Three or more interconnected states might not show full relationship graph
+- ⚠️ **Requires judgment:** Tool points out patterns worth investigating - you decide if they're issues
 
-### v0.5.0 (Future)
-- [ ] Visual state dependency graph
-- [ ] Domain isolation analysis
-- [ ] Historical trend tracking
+**Heuristic interpretation requires context. Always verify architectural intent before refactoring.**.
 
 ---
 
-## Contributing
+## Roadmap
 
-Found a bug? Have an idea? Open an issue or PR.
+### v0.4.x
+- [x] **v0.4.0**: Temporal Cross-Correlation Engine (Lead-Lag Analysis)
+- [x] **v0.4.1:** Density Filtering (Eliminate false positives from animations/sliders)
+- [ ] v0.4.2: Ring Buffer (Zero-jank memory management for 500+ hooks)
 
-For technical details on how the detection works, see the [Wiki](https://github.com/liovic/react-state-basis/wiki).
+### v0.5.0 (Planned)
+- [ ] Zustand & Redux middleware integration
+- [ ] Visual dependency graph in HUD
+- [ ] Historical trend tracking across sessions
+
+### Future Ideas
+- [ ] Domain isolation analysis (detect feature boundaries)
+- [ ] Export audit reports for team reviews
+- [ ] CI integration for architectural regressions
 
 ---
 
 ## FAQ
 
 **Q: Will this slow down my app?**  
-A: Only in development. Production builds are zero-overhead.
+A: Only in development (~0.3ms per update). Production builds have zero overhead.
 
 **Q: Do I have to change my code?**  
 A: No. The Babel plugin instruments hooks automatically.
 
 **Q: What if it flags something that's not a problem?**  
-A: Use your judgment. It's a diagnostic tool, not gospel.
+A: Use your judgment. Basis is a diagnostic tool that points out patterns worth investigating - not all flagged patterns are bugs.
+
+**Q: How is this different from Redux DevTools?**  
+A: Redux DevTools shows state values and action history. Basis shows temporal relationships between state variables, regardless of what state management library you use.
 
 **Q: Why "basis"?**  
-A: In linear algebra, a "basis" is a minimal set of independent vectors. The name reflects the goal of finding your app's minimal independent state.
+A: In linear algebra, a "basis" is a minimal set of independent vectors. The name reflects the goal of finding your app's minimal independent state - removing redundancy.
+
+**Q: How is this different from Redux DevTools?**  
+A: Redux DevTools is a **Journal** - it logs specific values and actions within a Redux store. Basis is an **Architectural Auditor** - it instruments React's core primitives (useState, useReducer, useEffect) to detect hidden relationships between entirely separate components and hooks, even when they don't share a store. Redux DevTools answers "what changed and why?" while Basis answers "is this state architecture clean?"
+
+---
+
+## Contributing
+
+Found a bug? Have an idea? Open an issue or PR.
+
+For technical details on how the detection works, see the [Wiki](https://github.com/liovic/react-state-basis/wiki).
 
 ---