react-state-basis 0.3.3 → 0.4.0

package/README.md

@@ -5,212 +5,434 @@
 <div align="center">
 
 # 📐 react-state-basis
-### Real-time architectural auditor for React
+### Runtime 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)
 
-**Audit your React architecture in development — without changing a single line of component code.**
+**Catches redundant state and update chains using temporal cross-correlation.**
 
 </div>
 
 ---
 
-## What is react-state-basis?
+## What Does It Do?
 
-**react-state-basis** is a development-time React utility that analyzes how state behaves *over time* and surfaces architectural issues that are difficult to detect with snapshot-based tools.
+**react-state-basis** watches your React app in development and flags common architectural issues:
 
-It focuses on **runtime behavior**, not values — helping you identify redundant state, hidden coupling, unstable update patterns, and effect-driven render loops while your app is running.
+- **Redundant state** - Two states that always update together
+- **Update chains** - Effects that trigger more state updates (double renders)
+- **Infinite loops** - Circular dependencies that freeze your browser
+- **Tight coupling** - State variables that should be independent but aren't
 
-> This is an architectural diagnostic tool.  
-> It is not a state manager and not a replacement for React DevTools.
+It works by tracking *when* state updates happen (temporal patterns), not *what* the values are.
 
 ---
 
-## What problems does it catch?
+## Quick Example
+```tsx
+// ❌ Basis will flag this
+const [user, setUser] = useState(null);
+const [isLoggedIn, setIsLoggedIn] = useState(false);
 
-In real React applications, many architectural issues don’t show up as errors:
+useEffect(() => {
+  setIsLoggedIn(!!user);  // Double render - flagged as sync leak
+}, [user]);
 
-- Multiple state variables encode the same information
-- Effects create subtle feedback loops
-- Components re-render twice even though nothing “looks wrong”
-- State updates oscillate under load or user interaction
+// ✅ Better
+const [user, setUser] = useState(null);
+const isLoggedIn = !!user;  // Computed, no second render
+```
 
-These issues emerge **over time**, across renders.
+---
 
-react-state-basis observes state updates as a timeline and flags structural patterns that indicate architectural debt.
+## See It Work
+
+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" />
+</p>
 
 ---
 
-## Key capabilities
+## Real-World Audits
 
-- **Temporal State Matrix (HUD)**  
-  A real-time visualization of state activity. If rows pulse together, the architecture is coupled or redundant.
+Basis has been tested on major open-source projects to validate detection accuracy:
 
-- **Redundant state detection**  
-  Identifies state variables that move together and suggests derived alternatives (e.g. `useMemo`).
+### 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
 
-- **Causality tracing**  
-  Tracks `useEffect → setState` chains to expose hidden double-render cycles.
+<p align="center"> 
+  <img src="./assets/excalidraw-audit.png" width="800" alt="Excalidraw Audit" /> 
+</p>
 
-- **Stability circuit breaker**  
-  Detects recursive update patterns and halts them before the browser tab locks up.
+### 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
 
-- **Universal support**  
-  Works with **React Web**, **React Native**, and **Expo**.
+<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.
 
 ---
 
-## High-Level Insights
+## Setup (Vite)
 
-### System Health Report
-For a bird's-eye view of your entire application's state-space, call the global reporter in your browser console or in code :
+### 1. Install
+```bash
+npm i react-state-basis
+```
 
+### 2. Add to `vite.config.ts`
 ```tsx
-window.printBasisReport();
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { basis } from 'react-state-basis/vite';
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: { plugins: [['react-state-basis/plugin']] }
+    }),
+    basis()
+  ]
+});
 ```
 
-This generates a correlation matrix and calculates your Basis Efficiency Score in real-time.
+### 3. Wrap your app
+```tsx
+import { BasisProvider } from 'react-state-basis';
 
----
+root.render(
+  <BasisProvider debug={true}>
+    <App />
+  </BasisProvider>
+);
+```
 
-## How it works (high level)
+### 4. Verify It's Working
 
-During development, react-state-basis observes state updates and compares how they evolve over short time windows.
+Add this test pattern to any component:
+```tsx
+const [a, setA] = useState(0);
+const [b, setB] = useState(0);
 
-Instead of asking:
-> “What is the state right now?”
+useEffect(() => {
+  setB(a); // Basis will flag this
+}, [a]);
+```
 
-It asks:
-> “How does this state behave relative to other states over time?”
+Trigger an update (e.g., click a button that calls `setA(1)`). You should see a console alert within ~100ms.
 
-This allows the engine to detect redundancy, coupling, and instability that static analysis and snapshot tools can’t see.
+---
 
-Implementation details are intentionally hidden from the public API.  
-The tool is designed to be **used**, not configured.
+## What You'll See
 
-👉 For a deeper dive into the internal model and formal specification, see the [project Wiki](https://github.com/liovic/react-state-basis/wiki).
+### Console Alerts
 
----
+**Redundant Pattern:**
+Detected when two variables move in perfect unison.
+```
+📐 BASIS | REDUNDANT PATTERN
+📍 Location: TodoList.tsx
+Observation: "todos" and "count" move together.
+One is likely a direct mirror of the other. Confidence: 94%
+Action: Refactor "count" to useMemo.
+```
 
-## See it in action
+**Sync Leak (Causal Chain):**
+Detected when one variable consistently triggers another with a temporal lag.
+```
+💡 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.
+```
 
-The optional HUD visualizes your application’s state “heartbeat” using the Canvas API.
+**Infinite Loop:**
+Detected when a variable updates too rapidly (circuit breaker).
+```
+🛑 BASIS CRITICAL | CIRCUIT BREAKER
+Infinite oscillation detected on: "counter"
+Execution halted to prevent browser thread lock.
+```
 
-Below, Basis detects redundant state, flags effect-driven render loops, and activates the stability circuit breaker in real time.
+### Health Report
 
-<p align="center">
-  <img src="./assets/react-state-basis.gif" width="800" alt="React State Basis Demo" />
-</p>
+Check your entire app's state architecture:
+```tsx
+window.printBasisReport();
+```
+
+Shows:
+- **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)
 
 ---
 
-## Zero-friction setup (Vite)
+## How It Works (v0.4.0)
 
-As of **v0.3.0**, react-state-basis runs transparently in development.
+### Temporal Cross-Correlation
+
+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
+```
 
-You do **not** need to modify component imports or wrap individual hooks.
+For every pair of variables, Basis checks three temporal relationships:
 
-### 1. Install
-```bash
-npm i react-state-basis
+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
+```
+
+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)
+```
+
+3. **Lead-Lag (B → A):** Does A consistently follow B?
+```
+   A: [0,0,1,0,1,...]
+   B: [0,1,0,1,0,...]  → A follows B (reverse causality)
+```
+
+The engine uses **offset-based comparison** to check these patterns without allocating temporary arrays, ensuring minimal overhead even at high frame rates.
 
-### 2. Configure Vite
+### Performance Optimizations
 
-Add the `basis` plugin to your `vite.config.ts`.
-It instruments React automatically during development.
+- **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
 
+### What Gets Flagged?
+
+**Redundant Pattern Example:**
 ```tsx
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import { basis } from 'react-state-basis/vite';
+// ❌ Before (Basis flags this)
+const [count, setCount] = useState(0);
+const [doubled, setDoubled] = useState(0);
 
-export default defineConfig({
-  plugins: [
-    react({
-      babel: { plugins: [['react-state-basis/plugin']] }
-    }),
-    basis() // No import changes required
-  ]
-});
+useEffect(() => {
+  setDoubled(count * 2);
+}, [count]);
+
+// ✅ After (Basis suggestion)
+const [count, setCount] = useState(0);
+const doubled = useMemo(() => count * 2, [count]);
 ```
 
-### 3. Initialize the provider
+**Sync Leak Example:**
+```tsx
+// ❌ Before (causes double render)
+const [user, setUser] = useState(null);
+const [isLoggedIn, setIsLoggedIn] = useState(false);
 
-Wrap your root component with `BasisProvider` to enable the engine and HUD.
+useEffect(() => {
+  setIsLoggedIn(!!user);
+}, [user]);
 
-```tsx
-import { BasisProvider } from 'react-state-basis';
+// ✅ After (single render)
+const [user, setUser] = useState(null);
+const isLoggedIn = !!user; // Derived, no effect needed
+```
 
-root.render(
-  <BasisProvider debug={true}>
-    <App />
-  </BasisProvider>
-);
+---
+
+## Upgrading from v0.3.x
+
+### Breaking Changes
+None! v0.4.0 is a drop-in replacement.
+
+### What's Different
+- **Better Detection:** Temporal analysis reduces false positives by distinguishing redundancy from causality
+- **New Alert Type:** "DETECTED SYNC LEAK" identifies effect-driven update chains with directional insight
+- **Console Throttling:** Same pair won't spam console (5-second cooldown between identical alerts)
+- **Idle Filtering:** Variables that haven't updated are excluded from analysis
+
+### Action Required
+None. Just update the package and restart your dev server.
+```bash
+npm update react-state-basis
 ```
 
-### Ignoring files
+---
+
+## Production Safety
+
+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",  // No-op shims
+    "default": "./dist/production.mjs"
+  }
+}
+```
 
-If certain files are intentionally noisy (e.g. animation loops or low-level adapters), you can exclude them from auditing.
+---
 
-Add this comment at the top of the file:
+## When to Skip Files
 
+Add `// @basis-ignore` at the top of a file to disable instrumentation:
 ```tsx
 // @basis-ignore
+// This file uses high-frequency animations and intentional state synchronization
 ```
 
-That file will be skipped by both the Babel plugin and the engine.
+**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 | 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** |
+
+These tools are complementary - use them together for best results.
 
 ---
 
-## Basis vs existing tools
+## Performance Impact (Measured)
+
+**Development Mode**
+
+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. 
 
-| Feature | React DevTools | Why Did You Render | Basis 📐 |
-| :--- | :---: | :---: | :---: |
-| **Analyzes Values** | ✅ | ✅ | ❌ (Value-agnostic) |
-| **Tracks Timing/Ticks** | ❌ | ❌ | ✅ |
-| **Detects Redundancy** | ❌ | ❌ | ✅ (Linear Dependence) |
-| **Circuit Breaker** | ❌ | ❌ | ✅ (Halts Loops) |
-| **Prod. Overhead** | Low | Medium | **Zero** (Ghost Mode) |
+Location: `/example`
+
+**Observed impact:**
+
+* **Per state update overhead:** ~0.3ms (lightweight hook instrumentation)
+* **Analysis pass (every ~100ms / 5 ticks):** ~2–4ms in typical applications
+* **Frame budget impact:** <1% when idle, ~5–10% during active stress testing
+* **Render path safety:** Analysis runs asynchronously, outside of React’s render cycle
+
+> 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/performance-test.png" width="800" alt="shadcn Admin Audit" /> 
+</p>
+
+
+**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
 
 ---
 
-## Case study: shadcn-admin audit
+## Limitations (v0.4.0)
 
-We ran react-state-basis on a production-ready dashboard to validate its detection engine.
-- Result: 12 / 12 independent state dimensions
-- Insight: Identified a subtle double-render bottleneck in useIsMobile that static tooling missed
+**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
 
-<p align="center"> <img src="./assets/shadcn-admin.png" width="800" alt="Real World Audit" /> </p>
+**False positives can happen.** Always verify before refactoring.
 
 ---
 
 ## Roadmap
 
-#### **v0.2.x - Signal Intelligence & Visual Foundation (Current)** ✅
-- [x] **Full React Hook Parity:** Support for all standard hooks and React Native/Expo.
-- [x] **React 19 Ready:** Full support for `use()`, `useOptimistic()`, and `useActionState()`.
-- [x] **Temporal Matrix HUD:** Real-time Canvas-based visualization of state signals.
-- [x] **Causality Engine:** Detection of sequential sync-leaks and double-render cycles.
-- [x] **Ghost Mode:** Zero-op production exports with no bundle overhead.
-- [x] **95% Test Coverage:** Verified mathematical engine.
+### v0.5.0 (Planned)
+- [ ] Zustand & Redux middleware integration
+- [ ] Visual dependency graph in HUD
+- [ ] Automated fix suggestions with one-click apply
+- [ ] Historical trend tracking across sessions
+
+### Future Ideas
+- [ ] Domain isolation analysis (detect feature boundaries)
+- [ ] Export audit reports for team reviews
+- [ ] CI integration for architectural regressions
+
+---
+
+## Troubleshooting
+
+**"I'm not seeing any alerts"**
+1. Verify `debug={true}` is set in `<BasisProvider>`
+2. Check that the Babel plugin is loaded (restart dev server after config changes)
+3. Create a test pattern (see "Verify It's Working" section)
+4. Open browser console and look for `Basis Auditor | Structural Relationship Check`
 
-#### **v0.3.0 - Global State & Ecosystem**
-- [x] **Zero-Config Vite Plugin:** Automatic aliasing for `react` and `react-dom`.
-- [x] **Babel Auto-Instrumentation:** Automatic hook labeling without code changes.
-- [ ] **Zustand Middleware:** Auditing global-to-local state redundancy.
-- [ ] **Redux Integration:** Connecting the causal engine to Redux dispatch cycles.
-- [ ] **CLI Initializer:** `rsb-init` to automatically configure Babel/Vite plugins.
-- [ ] **Context Auditor:** Tracking signal collisions across multiple React Context providers.
+**"Too many alerts"**
+- Use `// @basis-ignore` for animation-heavy files
+- Check if your app has intentional state synchronization patterns
+- Consider if alerts are revealing actual architectural issues
 
-#### **v0.4.0 - Topology & Automation**
-- [ ] **State-Space Topology Map:** 2D force-directed graph showing coupling clusters.
-- [ ] **Automated Fix Hints:** Advanced console codemods for converting redundant state to `useMemo`.
+**"Alert says 'sync leak' but I need that effect"**
+- Some effects are necessary (e.g., syncing to localStorage)
+- Basis flags patterns, not bugs - use your judgment
+- If it's intentional, add a comment explaining why
 
 ---
 
+## FAQ
+
+**Q: Will this slow down my app?**  
+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. 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 - 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).
+
+---
+
+<div align="center">
+
+Built by [LP](https://github.com/liovic) • MIT License
 
-<div align="center"> Developed by LP • A React utility for engineers who care about architectural correctness </div>
+</div>