react-state-basis 0.4.0 → 0.4.2

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 using temporal cross-correlation.**
+**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>
 
@@ -52,7 +54,7 @@ const isLoggedIn = !!user;  // Computed, no second render
 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>
 
 ---
@@ -177,9 +179,19 @@ Shows:
 - **Synchronized Clusters** - Groups of variables that move together
 - **Correlation Matrix** - Full pairwise similarity analysis (for <15 variables)
 
+### Hardware Telemetry
+
+Verify engine efficiency and heap stability in real-time:
+
+```tsx
+window.getBasisMetrics();
+```
+
+Returns: Engine execution time, active hook count, and current memory allocation strategy.
+
 ---
 
-## How It Works (v0.4.0)
+## How It Works (v0.4.x)
 
 ### Temporal Cross-Correlation
 
@@ -253,25 +265,6 @@ const isLoggedIn = !!user; // Derived, no effect needed
 
 ---
 
-## 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
-```
-
----
-
 ## Production Safety
 
 In production builds, the entire tool is replaced with zero-op shims. **Zero runtime overhead. Zero bundle size increase.**
@@ -293,7 +286,7 @@ In production builds, the entire tool is replaced with zero-op shims. **Zero run
 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
+// This file contains external protocols or hardware-bound synchronization outside the scope of architectural auditing.
 ```
 
 **Good candidates for skipping:**
@@ -322,24 +315,27 @@ These tools are complementary - use them together for best results.
 
 **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. 
+**Basis is designed to be statistically invisible to the main thread.** 
+
+The v0.4.2 **Flat Memory Architecture** utilizes `Uint8Array` Ring Buffers to eliminate Garbage Collection (GC) churn and provide constant-time $O(1)$ telemetry recording.
 
-Location: `/example`
+### Audited Benchmarks
 
-**Observed impact:**
+These metrics were recorded during a **20-minute high-frequency endurance audit** (1.2M state pulses) using the built-in **Stress Lab**.
 
-* **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
+*   **Logic Execution Overhead:** < 1.0ms per 100-hook update cycle.
+*   **Memory Profile:** **0 Delta heap growth.** (Static allocation via Ring Buffers).
+*   **Interaction Latency (INP):** ~56ms during continuous 50-hook concurrency tests (Green Zone).
+*   **Drawing Efficiency:** ~15ms drawing cost via Path2D GPU-batching.
 
-> Results will vary by hardware, browser, and workload. Use the Stress Lab to reproduce and compare Basis ON vs OFF in your own environment.
+> 🔍 **Forensic Proof:** Detailed heap snapshots, modulo-tax analysis, and linearized math benchmarks are documented in the [**v0.4.2 Performance RFC (#33)**](https://github.com/liovic/react-state-basis/issues/33).
 
 <p align="center"> 
-  <img src="./assets/performance-test.png" width="800" alt="shadcn Admin Audit" /> 
+  <img src="./assets/perf.gif" width="800" alt="Basis Stress Lab" /> 
 </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)
@@ -348,7 +344,7 @@ Location: `/example`
 
 ---
 
-## Limitations (v0.4.0)
+## Limitations (v0.4.x)
 
 **What works well:**
 - ✅ Detecting synchronous redundant state
@@ -362,16 +358,21 @@ Location: `/example`
 - ⚠️ **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
 
-**False positives can happen.** Always verify before refactoring.
+**Heuristic interpretation requires context. Always verify architectural intent before refactoring.**.
 
 ---
 
 ## Roadmap
 
+### 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)
+- [x] v0.4.2: Ring Buffer (Zero-jank memory management for 500+ hooks) [**v0.4.2 Performance RFC (#33)**](https://github.com/liovic/react-state-basis/issues/33)
+
+
 ### 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
@@ -381,26 +382,6 @@ Location: `/example`
 
 ---
 
-## 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`
-
-**"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
-
-**"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?**  

package/dist/index.d.mts

@@ -3,6 +3,18 @@ import React__default, { ReactNode } from 'react';
 export { basis } from './vite-plugin.mjs';
 import 'vite';
 
+declare const configureBasis: (c: any) => void;
+/**
+ * DISPLAY: window.printBasisReport()
+ */
+declare const printBasisHealthReport: (threshold?: number) => void;
+declare const getBasisMetrics: () => {
+    engine: string;
+    hooks: number;
+    load: number;
+    analysis_ms: string;
+};
+
 type GetReducerState<R extends React.Reducer<any, any>> = R extends React.Reducer<infer S, any> ? S : never;
 type GetReducerAction<R extends React.Reducer<any, any>> = R extends React.Reducer<any, infer A> ? A : never;
 declare function useState<S>(initialState: S | (() => S), label?: string): [S, React.Dispatch<React.SetStateAction<S>>];
@@ -34,9 +46,4 @@ declare const useBasisConfig: () => {
     debug: boolean;
 };
 
-declare const configureBasis: (newConfig: Partial<{
-    debug: boolean;
-}>) => void;
-declare const printBasisHealthReport: (threshold?: number) => void;
-
-export { BasisProvider, configureBasis, printBasisHealthReport, use, useActionState, useBasisConfig, useCallback, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition };
+export { BasisProvider, configureBasis, getBasisMetrics, printBasisHealthReport, use, useActionState, useBasisConfig, useCallback, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition };

package/dist/index.d.ts

@@ -3,6 +3,18 @@ import React__default, { ReactNode } from 'react';
 export { basis } from './vite-plugin.js';
 import 'vite';
 
+declare const configureBasis: (c: any) => void;
+/**
+ * DISPLAY: window.printBasisReport()
+ */
+declare const printBasisHealthReport: (threshold?: number) => void;
+declare const getBasisMetrics: () => {
+    engine: string;
+    hooks: number;
+    load: number;
+    analysis_ms: string;
+};
+
 type GetReducerState<R extends React.Reducer<any, any>> = R extends React.Reducer<infer S, any> ? S : never;
 type GetReducerAction<R extends React.Reducer<any, any>> = R extends React.Reducer<any, infer A> ? A : never;
 declare function useState<S>(initialState: S | (() => S), label?: string): [S, React.Dispatch<React.SetStateAction<S>>];
@@ -34,9 +46,4 @@ declare const useBasisConfig: () => {
     debug: boolean;
 };
 
-declare const configureBasis: (newConfig: Partial<{
-    debug: boolean;
-}>) => void;
-declare const printBasisHealthReport: (threshold?: number) => void;
-
-export { BasisProvider, configureBasis, printBasisHealthReport, use, useActionState, useBasisConfig, useCallback, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition };
+export { BasisProvider, configureBasis, getBasisMetrics, printBasisHealthReport, use, useActionState, useBasisConfig, useCallback, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition };