react-state-basis 0.2.2 → 0.2.4

package/README.md

@@ -181,44 +181,84 @@ Basis automatically detects the environment. In mobile environments, it switches
 
 ## Key Capabilities
 
-### Redundant State Detection
-Basis monitors transition vectors to identify "Dimension Collapses." When multiple states (like `isLoading`, `isSuccess`) update in lockstep, it suggests consolidating them.
-<br/>
-<img src="./example/screenshots/booleanEntanglement.gif" width="700" alt="Boolean Entanglement Demo" />
-
-### Causal Detective
-Identifies "Double Render Cycles" by tracking the causality chain from `useEffect` or `useLayoutEffect` to state setters. Basis provides a direct refactor snippet to move from manual sync to a pure mathematical projection (`useMemo`).
-<br/>
-<img src="./example/screenshots/causal.gif" width="700" alt="Causal Link Demo" />
-
-### Circuit Breaker
-A real-time stability monitor. If high-frequency state oscillation is detected (e.g., a recursive effect), Basis forcefully halts the update chain to prevent the browser thread from locking up.
-<br/>
-<img src="./example/screenshots/infiniteLoopTrap.gif" width="700" alt="Circuit Breaker Demo" />
-
-### Cross-Context Audit
-Performs a global state space audit to expose hidden coupling between disparate parts of your architecture (e.g., syncing states across different Providers).
-<br/>
-<img src="./example/screenshots/initiateGlobalSync.gif" width="700" alt="Cross-Context Sync Demo" />
-
-### System Health & Efficiency Audit
-Basis performs a global audit of your state space to calculate its **Mathematical Rank**-the actual number of independent information dimensions. Use the **Efficiency Score** as a real-time KPI for your architecture.
-<br/>
-<img src="./example/screenshots/systemHealthReport.gif" width="700" alt="System Health Report Demo" />
+### 1. Temporal State Matrix (Real-time HUD)
+The "Heartbeat" of your application. Basis injects a high-performance, Zero-Overhead HUD that visualizes your state transitions as a temporal heatmap.
+*   **Signal Visualization:** Watch every `useState`, `useReducer`, and `useEffect` update pulse in real-time.
+*   **Visual Pattern Recognition:** Identify architectural flaws simply by looking at the rhythm of the matrix. If multiple rows pulse together, they likely belong together.
+*   **Zero-Overhead:** Powered by Canvas API and `requestAnimationFrame` polling to ensure your application's performance remains untouched during development.
+
+### 2. Redundant State Detection (Dimension Collapse)
+Basis monitors transition vectors to identify "Dimension Collapses" in your state space.
+*   **Collinearity Alerts:** When multiple states (like `isLoading`, `isSuccess`, `hasData`) update in lockstep, Basis flags them as mathematically redundant.
+*   **Visual Debugging:** Redundant states are automatically highlighted in **Red** within the HUD, providing immediate visual proof that you are storing the same information in multiple places.
+
+### 3. Causal Detective (Double Render Tracker)
+Identify "Double Render Cycles" by tracking the causality chain from effects to state setters.
+*   **Sequence Tracking:** Detects when a state update is a lagging echo of a `useEffect` or `useLayoutEffect`.
+*   **Refactor Insights:** Provides direct console hints to move from manual synchronization to pure, deterministic mathematical projections using `useMemo`.
+
+### 4. Stability Circuit Breaker
+A real-time safety monitor for your execution thread.
+*   **Oscillation Detection:** If high-frequency state oscillation is detected (e.g., a recursive effect loop), Basis forcefully halts the update chain.
+*   **Tab Protection:** Stops the browser thread from locking up, allowing you to catch and fix infinite loops without having to force-quit your browser tab.
+
+### 5. System Health & Efficiency Rank
+Basis performs a global audit of your state space to calculate its **Mathematical Rank**—the actual number of independent information dimensions.
+*   **Efficiency Score:** A real-time KPI for your architecture. A 100% score means every state variable is a unique, non-redundant source of truth.
+*   **Architecture Audit:** Use the global Health Report (`window.printBasisReport()`) to generate a correlation matrix of your entire application state.
 
 ---
 
-## Roadmap
+### See it in Action
+<p align="center">
+  <img src="./assets/react-state-basis.gif" width="800" alt="React State Basis Demo" />
+</p>
+
+---
+
+## 🔍 Case Study: Auditing High-Integrity React Architecture
+
+To test the engine against professional standards, Basis was used to audit the [shadcn-admin](https://github.com/satnaing/shadcn-admin) template-a high-quality, production-ready dashboard implementation.
+
+<p align="center">
+  <img src="./assets/shadcn-admin.png" width="800" alt="Basis Real World Audit" />
+</p>
+
+### Audit Results: 100% Basis Efficiency
+The project demonstrated exceptional architectural integrity. The engine verified a **100% Efficiency**, confirming that all state variables are linearly independent. This proves that the codebase follows a "Single Source of Truth" philosophy with zero redundant state.
+
+### Subtle Optimization Caught
+Despite the perfect efficiency score, the **Causality Engine** identified a hidden performance bottleneck:
+*   **Double Render Detection:** Basis flagged a "Double Render Cycle" in the `use-mobile.tsx` hook. It detected that the `isMobile` state was being manually synchronized within a `useEffect`, triggering a secondary render pass. 
+*   **Refactor Insight:** While the logic was correct, Basis revealed the cost of the implementation - a redundant render cycle that occurs before every layout shift.
 
-#### **v0.2.x - Stability & Universal Support (Current)** ✅
-- [x] Full React Hook API parity & React Native support.
-- [x] Memory-optimized "Ghost Registration" logic.
-- [x] 95% Test Coverage verified engine.
+### Stability Confirmation
+The auditor provided formal verification for the rest of the suite:
+*   **Stable Callbacks:** Verified that `Sidebar` methods were correctly memoized, ensuring child components are protected from unnecessary updates.
+*   **Valid Projections:** Confirmed that complex table logic (pagination and filtering) was implemented as pure mathematical projections, rather than state-syncing.
+
+Math reveals exactly what standard code reviews often miss: the **temporal topology** of your application.
+---
+
+## Roadmap
 
-#### **v0.3.0 - Visuals & React 19** 📈
-- [ ] **State-Space Visualizer:** 2D topology map showing redundancy clusters.
-- [ ] **CLI Utilities:** `rsb-init` and `rsb-clean` for automated codemods.
-- [ ] **React 19 Native Support:** `use()`, `useOptimistic()`, `useActionState()`.
+#### **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.3.0 - Global State & Ecosystem**
+- [ ] **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.
+
+#### **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`.
 
 ---
 

package/dist/index.d.mts

@@ -1,6 +1,8 @@
-import * as React$1 from 'react';
-import React__default, { Dispatch, SetStateAction, Reducer, DependencyList, EffectCallback, Context, ReactNode } from 'react';
-export { CSSProperties, Context, DependencyList, Dispatch, EffectCallback, FC, PropsWithChildren, ReactElement, ReactNode, Reducer, SetStateAction } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+export { React };
+export { React as default };
+export { AnchorHTMLAttributes, Attributes, ButtonHTMLAttributes, CSSProperties, ChangeEvent, ComponentProps, ComponentPropsWithRef, ComponentPropsWithoutRef, ComponentType, DependencyList, DetailedHTMLProps, Dispatch, DragEvent, EffectCallback, ElementType, FC, FocusEvent, FormEvent, HTMLAttributes, HTMLProps, InputHTMLAttributes, JSX, Key, KeyboardEvent, MouseEvent, MutableRefObject, PointerEvent, PropsWithChildren, ReactElement, ReactNode, ReactPortal, Reducer, Ref, RefObject, SVGProps, SetStateAction, TouchEvent } from 'react';
 
 interface BasisConfig {
     debug: boolean;
@@ -27,22 +29,38 @@ declare const __testEngine__: {
     endEffectTracking: () => void;
 };
 
-declare function useState<T>(initialValue: T, label?: string): [T, Dispatch<SetStateAction<T>>];
-declare function useReducer<S, A, I>(reducer: Reducer<S, A>, initialArg: I & S, init?: any, label?: string): [S, Dispatch<A>];
-declare function useMemo<T>(factory: () => T, depsOrLabel?: DependencyList | string, label?: string): T;
-declare function useCallback<T extends (...args: any[]) => any>(callback: T, depsOrLabel?: DependencyList | string, label?: string): T;
-declare function useEffect(effect: EffectCallback, depsOrLabel?: DependencyList | string, label?: string): void;
-declare function useLayoutEffect(effect: EffectCallback, depsOrLabel?: DependencyList | string, label?: string): void;
-declare function useInsertionEffect(effect: EffectCallback, deps?: DependencyList, _label?: string): void;
+interface BasisProviderProps {
+    children: ReactNode;
+    debug?: boolean;
+}
+declare const BasisProvider: React__default.FC<BasisProviderProps>;
+declare const useBasisConfig: () => {
+    debug: boolean;
+};
+
+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>>];
+declare function useRef<T>(initialValue: T): React.RefObject<T>;
+declare function useRef<T>(initialValue: T | null): React.RefObject<T>;
+declare function useRef<T = undefined>(): React.MutableRefObject<T | undefined>;
+declare function useReducer<R extends React.Reducer<any, any>, I>(reducer: R, initialArg: I, init?: any, label?: string): [GetReducerState<R>, React.Dispatch<GetReducerAction<R>>];
+declare function useMemo<T>(factory: () => T, deps: React.DependencyList | undefined, label?: string): T;
+declare function useCallback<T extends (...args: any[]) => any>(callback: T, deps: React.DependencyList, label?: string): T;
+declare function useEffect(effect: React.EffectCallback, deps?: React.DependencyList, label?: string): void;
+declare function useLayoutEffect(effect: React.EffectCallback, deps?: React.DependencyList, label?: string): void;
 declare function useTransition(_label?: string): [boolean, (callback: () => void) => void];
 declare function useDeferredValue<T>(value: T, initialValueOrLabel?: T | string, label?: string): T;
-declare function useRef<T>(initialValue: T, _label?: string): React$1.RefObject<T>;
-declare function createContext<T>(defaultValue: T, label?: string): Context<T>;
-declare function useContext<T>(context: Context<T>): T;
-declare function useId(_label?: string): string;
-declare function useDebugValue<T>(value: T, formatter?: (value: T) => any, _label?: string): void;
-declare function useImperativeHandle<T, R extends T>(ref: React.Ref<T> | undefined, init: () => R, deps?: DependencyList, _label?: string): void;
-declare function useSyncExternalStore<Snapshot>(subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => Snapshot, getServerSnapshot?: () => Snapshot, _label?: string): Snapshot;
+declare function createContext<T>(defaultValue: T, label?: string): React.Context<T>;
+declare const useContext: typeof React.useContext;
+declare const useId: (label?: string) => string;
+declare const useDebugValue: typeof React.useDebugValue;
+declare const useImperativeHandle: typeof React.useImperativeHandle;
+declare const useInsertionEffect: typeof React.useInsertionEffect;
+declare const useSyncExternalStore: any;
+declare function use<T>(usable: React.Usable<T>): T;
+declare function useOptimistic<S, P>(passthrough: S, reducer?: (state: S, payload: P) => S, label?: string): [S, (payload: P) => void];
+declare function useActionState<State, Payload>(action: (state: State, payload: Payload) => Promise<State> | State, initialState: State, permalink?: string, label?: string): [state: State, dispatch: (payload: Payload) => void, isPending: boolean];
 declare const __test__: {
     registerVariable: (label: string) => void;
     unregisterVariable: (label: string) => void;
@@ -53,13 +71,30 @@ declare const __test__: {
     currentTickBatch: any;
 };
 
-interface BasisProviderProps {
-    children: ReactNode;
-    debug?: boolean;
-}
-declare const BasisProvider: React__default.FC<BasisProviderProps>;
-declare const useBasisConfig: () => {
-    debug: boolean;
+declare const Children: {
+    map<T, C>(children: C | readonly C[], fn: (child: C, index: number) => T): C extends null | undefined ? C : Array<Exclude<T, boolean | null | undefined>>;
+    forEach<C>(children: C | readonly C[], fn: (child: C, index: number) => void): void;
+    count(children: any): number;
+    only<C>(children: C): C extends any[] ? never : C;
+    toArray(children: React.ReactNode | React.ReactNode[]): Array<Exclude<React.ReactNode, boolean | null | undefined>>;
 };
+declare const Component: typeof React.Component;
+declare const Fragment: React.ExoticComponent<React.FragmentProps>;
+declare const Profiler: React.ExoticComponent<React.ProfilerProps>;
+declare const PureComponent: typeof React.PureComponent;
+declare const StrictMode: React.ExoticComponent<{
+    children?: React.ReactNode | undefined;
+}>;
+declare const Suspense: React.ExoticComponent<React.SuspenseProps>;
+declare const cloneElement: typeof React.cloneElement;
+declare const createRef: typeof React.createRef;
+declare const forwardRef: typeof React.forwardRef;
+declare const isValidElement: typeof React.isValidElement;
+declare const lazy: typeof React.lazy;
+declare const memo: typeof React.memo;
+declare const startTransition: typeof React.startTransition;
+declare const version: string;
+declare const createPortal: any;
+declare const flushSync: any;
 
-export { type BasisConfig, BasisProvider, __testEngine__, __test__, beginEffectTracking, config, configureBasis, createContext, currentTickBatch, endEffectTracking, history, printBasisHealthReport, recordUpdate, registerVariable, unregisterVariable, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, useTransition };
+export { BasisProvider, Children, Component, Fragment, Profiler, PureComponent, StrictMode, Suspense, __testEngine__, __test__, beginEffectTracking, cloneElement, config, configureBasis, createContext, createPortal, createRef, currentTickBatch, endEffectTracking, flushSync, forwardRef, history, isValidElement, lazy, memo, printBasisHealthReport, recordUpdate, registerVariable, startTransition, unregisterVariable, use, useActionState, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition, version };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import * as React$1 from 'react';
-import React__default, { Dispatch, SetStateAction, Reducer, DependencyList, EffectCallback, Context, ReactNode } from 'react';
-export { CSSProperties, Context, DependencyList, Dispatch, EffectCallback, FC, PropsWithChildren, ReactElement, ReactNode, Reducer, SetStateAction } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+export { React };
+export { React as default };
+export { AnchorHTMLAttributes, Attributes, ButtonHTMLAttributes, CSSProperties, ChangeEvent, ComponentProps, ComponentPropsWithRef, ComponentPropsWithoutRef, ComponentType, DependencyList, DetailedHTMLProps, Dispatch, DragEvent, EffectCallback, ElementType, FC, FocusEvent, FormEvent, HTMLAttributes, HTMLProps, InputHTMLAttributes, JSX, Key, KeyboardEvent, MouseEvent, MutableRefObject, PointerEvent, PropsWithChildren, ReactElement, ReactNode, ReactPortal, Reducer, Ref, RefObject, SVGProps, SetStateAction, TouchEvent } from 'react';
 
 interface BasisConfig {
     debug: boolean;
@@ -27,22 +29,38 @@ declare const __testEngine__: {
     endEffectTracking: () => void;
 };
 
-declare function useState<T>(initialValue: T, label?: string): [T, Dispatch<SetStateAction<T>>];
-declare function useReducer<S, A, I>(reducer: Reducer<S, A>, initialArg: I & S, init?: any, label?: string): [S, Dispatch<A>];
-declare function useMemo<T>(factory: () => T, depsOrLabel?: DependencyList | string, label?: string): T;
-declare function useCallback<T extends (...args: any[]) => any>(callback: T, depsOrLabel?: DependencyList | string, label?: string): T;
-declare function useEffect(effect: EffectCallback, depsOrLabel?: DependencyList | string, label?: string): void;
-declare function useLayoutEffect(effect: EffectCallback, depsOrLabel?: DependencyList | string, label?: string): void;
-declare function useInsertionEffect(effect: EffectCallback, deps?: DependencyList, _label?: string): void;
+interface BasisProviderProps {
+    children: ReactNode;
+    debug?: boolean;
+}
+declare const BasisProvider: React__default.FC<BasisProviderProps>;
+declare const useBasisConfig: () => {
+    debug: boolean;
+};
+
+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>>];
+declare function useRef<T>(initialValue: T): React.RefObject<T>;
+declare function useRef<T>(initialValue: T | null): React.RefObject<T>;
+declare function useRef<T = undefined>(): React.MutableRefObject<T | undefined>;
+declare function useReducer<R extends React.Reducer<any, any>, I>(reducer: R, initialArg: I, init?: any, label?: string): [GetReducerState<R>, React.Dispatch<GetReducerAction<R>>];
+declare function useMemo<T>(factory: () => T, deps: React.DependencyList | undefined, label?: string): T;
+declare function useCallback<T extends (...args: any[]) => any>(callback: T, deps: React.DependencyList, label?: string): T;
+declare function useEffect(effect: React.EffectCallback, deps?: React.DependencyList, label?: string): void;
+declare function useLayoutEffect(effect: React.EffectCallback, deps?: React.DependencyList, label?: string): void;
 declare function useTransition(_label?: string): [boolean, (callback: () => void) => void];
 declare function useDeferredValue<T>(value: T, initialValueOrLabel?: T | string, label?: string): T;
-declare function useRef<T>(initialValue: T, _label?: string): React$1.RefObject<T>;
-declare function createContext<T>(defaultValue: T, label?: string): Context<T>;
-declare function useContext<T>(context: Context<T>): T;
-declare function useId(_label?: string): string;
-declare function useDebugValue<T>(value: T, formatter?: (value: T) => any, _label?: string): void;
-declare function useImperativeHandle<T, R extends T>(ref: React.Ref<T> | undefined, init: () => R, deps?: DependencyList, _label?: string): void;
-declare function useSyncExternalStore<Snapshot>(subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => Snapshot, getServerSnapshot?: () => Snapshot, _label?: string): Snapshot;
+declare function createContext<T>(defaultValue: T, label?: string): React.Context<T>;
+declare const useContext: typeof React.useContext;
+declare const useId: (label?: string) => string;
+declare const useDebugValue: typeof React.useDebugValue;
+declare const useImperativeHandle: typeof React.useImperativeHandle;
+declare const useInsertionEffect: typeof React.useInsertionEffect;
+declare const useSyncExternalStore: any;
+declare function use<T>(usable: React.Usable<T>): T;
+declare function useOptimistic<S, P>(passthrough: S, reducer?: (state: S, payload: P) => S, label?: string): [S, (payload: P) => void];
+declare function useActionState<State, Payload>(action: (state: State, payload: Payload) => Promise<State> | State, initialState: State, permalink?: string, label?: string): [state: State, dispatch: (payload: Payload) => void, isPending: boolean];
 declare const __test__: {
     registerVariable: (label: string) => void;
     unregisterVariable: (label: string) => void;
@@ -53,13 +71,30 @@ declare const __test__: {
     currentTickBatch: any;
 };
 
-interface BasisProviderProps {
-    children: ReactNode;
-    debug?: boolean;
-}
-declare const BasisProvider: React__default.FC<BasisProviderProps>;
-declare const useBasisConfig: () => {
-    debug: boolean;
+declare const Children: {
+    map<T, C>(children: C | readonly C[], fn: (child: C, index: number) => T): C extends null | undefined ? C : Array<Exclude<T, boolean | null | undefined>>;
+    forEach<C>(children: C | readonly C[], fn: (child: C, index: number) => void): void;
+    count(children: any): number;
+    only<C>(children: C): C extends any[] ? never : C;
+    toArray(children: React.ReactNode | React.ReactNode[]): Array<Exclude<React.ReactNode, boolean | null | undefined>>;
 };
+declare const Component: typeof React.Component;
+declare const Fragment: React.ExoticComponent<React.FragmentProps>;
+declare const Profiler: React.ExoticComponent<React.ProfilerProps>;
+declare const PureComponent: typeof React.PureComponent;
+declare const StrictMode: React.ExoticComponent<{
+    children?: React.ReactNode | undefined;
+}>;
+declare const Suspense: React.ExoticComponent<React.SuspenseProps>;
+declare const cloneElement: typeof React.cloneElement;
+declare const createRef: typeof React.createRef;
+declare const forwardRef: typeof React.forwardRef;
+declare const isValidElement: typeof React.isValidElement;
+declare const lazy: typeof React.lazy;
+declare const memo: typeof React.memo;
+declare const startTransition: typeof React.startTransition;
+declare const version: string;
+declare const createPortal: any;
+declare const flushSync: any;
 
-export { type BasisConfig, BasisProvider, __testEngine__, __test__, beginEffectTracking, config, configureBasis, createContext, currentTickBatch, endEffectTracking, history, printBasisHealthReport, recordUpdate, registerVariable, unregisterVariable, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, useTransition };
+export { BasisProvider, Children, Component, Fragment, Profiler, PureComponent, StrictMode, Suspense, __testEngine__, __test__, beginEffectTracking, cloneElement, config, configureBasis, createContext, createPortal, createRef, currentTickBatch, endEffectTracking, flushSync, forwardRef, history, isValidElement, lazy, memo, printBasisHealthReport, recordUpdate, registerVariable, startTransition, unregisterVariable, use, useActionState, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition, version };