react-state-basis 0.4.2 → 0.5.1

package/README.md

@@ -4,416 +4,168 @@
 
 <div align="center">
 
-# 📐 react-state-basis
-### Runtime Architectural Auditor & State Profiler for React
+# react-state-basis
+### Runtime Architectural Auditor for React
+
+**Basis tracks when state updates (never what) to catch architectural debt that standard tools miss, while keeping your data private.**
 
 [![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)
 
-**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>
 
 ---
 
-## What Does It Do?
-
-**react-state-basis** watches your React app in development and flags common architectural issues:
-
-- **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
-
-It works by tracking *when* state updates happen (temporal patterns), not *what* the values are.
-
----
-
-## Quick Example
-```tsx
-// ❌ Basis will flag this
-const [user, setUser] = useState(null);
-const [isLoggedIn, setIsLoggedIn] = useState(false);
-
-useEffect(() => {
-  setIsLoggedIn(!!user);  // Double render - flagged as sync leak
-}, [user]);
-
-// ✅ Better
-const [user, setUser] = useState(null);
-const isLoggedIn = !!user;  // Computed, no second render
-```
-
----
-
-## See It Work
-
-The optional HUD shows your state basis matrix in real-time:
-
-<p align="center">
-  <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)
+## Quick Start
 
 ### 1. Install
 ```bash
 npm i react-state-basis
 ```
 
-### 2. Add to `vite.config.ts`
-```tsx
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
+### 2. Setup (Vite)
+Add the plugin to your `vite.config.ts`. The Babel plugin auto-labels your hooks—you continue importing from `react` as normal.
+
+```ts
 import { basis } from 'react-state-basis/vite';
 
 export default defineConfig({
   plugins: [
-    react({
-      babel: { plugins: [['react-state-basis/plugin']] }
+    react({ 
+      babel: { plugins: [['react-state-basis/plugin']] } 
     }),
     basis()
   ]
 });
 ```
 
-### 3. Wrap your app
+### 3. Initialize
 ```tsx
 import { BasisProvider } from 'react-state-basis';
 
 root.render(
-  <BasisProvider debug={true}>
+  <BasisProvider 
+    debug={true}
+    showHUD={true} // Set to false for console-only forensics
+  >
     <App />
   </BasisProvider>
 );
 ```
 
-### 4. Verify It's Working
+### 4. Verify the Signal
+Drop this pattern into any component. Basis will identify the rhythm of the debt within ~100ms.
 
-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
+  setB(a); // ⚡ BASIS: "Double Render Detected"
 }, [a]);
-```
 
-Trigger an update (e.g., click a button that calls `setA(1)`). You should see a console alert within ~100ms.
-
----
-
-## What You'll See
-
-### 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.
+return <button onClick={() => setA(a + 1)}>Pulse Basis</button>;
 ```
 
-**Sync Leak (Causal Chain):**
-Detected when one variable consistently triggers another with a temporal lag.
+Click the button. You should see this in your console within ~100ms:
 ```
-💡 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.
+⚡ BASIS | DOUBLE RENDER
+📍 Location: YourComponent.tsx
+Issue: a triggers b in a separate frame.
+Fix: Derive b during the first render.
 ```
 
-**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.
-```
-
-### Health Report
-
-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)
-
-### 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.x)
+### 5. Control & Scope
+*   **Ghost Mode:** Disable the Matrix UI while keeping console-based forensics active by setting `showHUD={false}` on the provider.
+*   **Selective Auditing:** Add `// @basis-ignore` at the top of any file to disable instrumentation. Recommended for:
+    *   High-frequency animation logic (>60fps)
+    *   Third-party library wrappers
+    *   Intentional synchronization (e.g., local mirrors of external caches)
 
-### 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
-```
-
-For every pair of variables, Basis checks three temporal relationships:
-
-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.
-
-### Performance Optimizations
+---
 
-- **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
+## Visual Proof
 
-### What Gets Flagged?
+The optional HUD shows your **State Basis Matrix** in real-time. Purple pulses ($\Omega$) are Context anchors; Red pulses (!) are redundant shadows.
 
-**Redundant Pattern Example:**
-```tsx
-// ❌ Before (Basis flags this)
-const [count, setCount] = useState(0);
-const [doubled, setDoubled] = useState(0);
+<p align="center">
+  <img src="./assets/050Basis.gif" width="800" alt="Basis v0.5.0 Demo" />
+</p>
 
-useEffect(() => {
-  setDoubled(count * 2);
-}, [count]);
+---
 
-// ✅ After (Basis suggestion)
-const [count, setCount] = useState(0);
-const doubled = useMemo(() => count * 2, [count]);
-```
+## What Basis Detects
 
-**Sync Leak Example:**
-```tsx
-// ❌ Before (causes double render)
-const [user, setUser] = useState(null);
-const [isLoggedIn, setIsLoggedIn] = useState(false);
+Basis treats every hook as a signal to catch these architectural violations:
 
-useEffect(() => {
-  setIsLoggedIn(!!user);
-}, [user]);
+- **Ω Context Mirroring** - Local state shadowing global context
+- **♊ Duplicate State** - Independent variables that always update together  
+- **⚡ Sync Leaks** - 1-frame delays forcing double renders
+- **🛑 Recursive Oscillation** - Infinite loops (with circuit breaker)
 
-// ✅ After (single render)
-const [user, setUser] = useState(null);
-const isLoggedIn = !!user; // Derived, no effect needed
-```
+[**See examples & fixes →**](https://github.com/liovic/react-state-basis/wiki/The-Forensic-Catalog)
 
 ---
 
-## 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"
-  }
-}
-```
+## Reports & Telemetry
 
----
-
-## When to Skip Files
+### Architectural Health Report
+Check your entire app's state architecture by running `window.printBasisReport()` in the console.
 
-Add `// @basis-ignore` at the top of a file to disable instrumentation:
-```tsx
-// @basis-ignore
-// This file contains external protocols or hardware-bound synchronization outside the scope of architectural auditing.
-```
+*   **Efficiency Score:** Ratio of independent signals to total hooks.
+*   **Entangled Clusters:** Groups of variables that move in sync (Boolean Explosion).
+*   **Correlation Matrix:** Raw pairwise similarity data for deep-dive forensics.
 
-**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)
+### Hardware Telemetry
+Verify engine efficiency and heap stability in real-time via `window.getBasisMetrics()`.
 
 ---
 
-## Comparison to Other Tools
+## Real-World Evidence
 
-| 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** |
+Basis is verified against industry-standard codebases to ensure high-fidelity detection:
 
-These tools are complementary - use them together for best results.
+*   **Excalidraw (114k⭐)** - Caught a theme-sync leak forcing a double-render on every toggle. [**PR #10637**](https://github.com/excalidraw/excalidraw/pull/10637)
+*   **shadcn-admin (10k⭐)** - Detected redundant state pattern in viewport detection hooks. [**PR #274**](https://github.com/satnaing/shadcn-admin/pull/274)
 
 ---
 
-## Performance Impact (Measured)
-
-**Development Mode**
-
-**Basis is designed to be statistically invisible to the main thread.** 
+## Performance & Privacy
 
-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.
+**Development:** <1ms overhead per update cycle, zero heap growth  
+**Production:** ~0.01ms per hook (monitoring disabled, ~2-3KB bundle)  
+**Privacy:** Only tracks update timing, never state values
 
-### Audited Benchmarks
-
-These metrics were recorded during a **20-minute high-frequency endurance audit** (1.2M state pulses) using the built-in **Stress Lab**.
-
-*   **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.
-
-> 🔍 **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/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)
-- Monitoring logic: 100% removed
-- HUD component: 100% removed
+[**See benchmarks →**](https://github.com/liovic/react-state-basis/wiki/Performance-Forensics)
 
 ---
 
-## Limitations (v0.4.x)
+## Documentation & Theory
 
-**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
-
-**Heuristic interpretation requires context. Always verify architectural intent before refactoring.**.
+Basis is built on heuristics inspired by **Linear Algebra** and **Signal Processing**. To understand the underlying math, visit the [**Full Wiki**](https://github.com/liovic/react-state-basis/wiki).
 
 ---
 
 ## 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)
+Each era of Basis answers a different architectural question:
 
+✓ **v0.4.x** - The Correlation Era - *Are these states moving together?*  
+→ **v0.5.x** - The Decomposition Era - *Is this local state just a copy of Context?*  
+**v0.6.x** - The Graph Era - *Which bug should I fix first for maximum impact?*  
+**v0.7.x** - The Information Era - *Does this state carry real information, or is it derivative?*   
+**v0.8.x** - The Manifold Era - *How many hooks does your component actually need?*
 
-### 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 (~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).
+[**More info**](https://github.com/liovic/react-state-basis/wiki/Roadmap)
 
 ---
 
 <div align="center">
 
-Built by [LP](https://github.com/liovic) • MIT License
+Built by [LP](https://github.com/liovic) • [MIT License](https://opensource.org/licenses/MIT)
 
-</div>
+</div>

package/dist/index.d.mts

@@ -3,47 +3,55 @@ import React__default, { ReactNode } from 'react';
 export { basis } from './vite-plugin.mjs';
 import 'vite';
 
-declare const configureBasis: (c: any) => void;
 /**
- * DISPLAY: window.printBasisReport()
+ * Standard React Reducer type inference helpers.
  */
-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>>];
-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>>];
+/**
+ * PUBLIC OVERLOAD: Lazy initialization
+ */
+declare function useReducer<R extends React.Reducer<any, any>, I>(reducer: R, initializerArg: I, initializer: (arg: I) => GetReducerState<R>, label?: string): [GetReducerState<R>, React.Dispatch<GetReducerAction<R>>];
+/**
+ * PUBLIC OVERLOAD: Direct initialization
+ */
+declare function useReducer<R extends React.Reducer<any, any>>(reducer: R, initialState: GetReducerState<R>, initializer?: undefined, label?: string): [GetReducerState<R>, React.Dispatch<GetReducerAction<R>>];
+declare function createContext<T>(defaultValue: T, label?: string): React.Context<T>;
+declare function useContext<T>(context: React.Context<T>): T;
 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 useCallback<T extends (...args: unknown[]) => unknown>(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 const useId: (label?: string) => string;
+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 useRef: typeof React.useRef;
+declare const useId: typeof React.useId;
 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 useSyncExternalStore: typeof React.useSyncExternalStore;
+declare const useTransition: typeof React.useTransition;
+declare const useDeferredValue: typeof React.useDeferredValue;
+declare const use: <T>(usable: React.Usable<T>) => T;
 
 interface BasisProviderProps {
     children: ReactNode;
     debug?: boolean;
+    showHUD?: boolean;
 }
 declare const BasisProvider: React__default.FC<BasisProviderProps>;
 declare const useBasisConfig: () => {
     debug: boolean;
 };
 
-export { BasisProvider, configureBasis, getBasisMetrics, printBasisHealthReport, use, useActionState, useBasisConfig, useCallback, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition };
+declare const configureBasis: (c: any) => void;
+declare const printBasisHealthReport: (threshold?: number) => void;
+declare const getBasisMetrics: () => {
+    engine: string;
+    hooks: number;
+    analysis_ms: string;
+    entropy: string;
+};
+
+export { BasisProvider, configureBasis, createContext, getBasisMetrics, printBasisHealthReport, use, useActionState, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition };

package/dist/index.d.ts

@@ -3,47 +3,55 @@ import React__default, { ReactNode } from 'react';
 export { basis } from './vite-plugin.js';
 import 'vite';
 
-declare const configureBasis: (c: any) => void;
 /**
- * DISPLAY: window.printBasisReport()
+ * Standard React Reducer type inference helpers.
  */
-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>>];
-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>>];
+/**
+ * PUBLIC OVERLOAD: Lazy initialization
+ */
+declare function useReducer<R extends React.Reducer<any, any>, I>(reducer: R, initializerArg: I, initializer: (arg: I) => GetReducerState<R>, label?: string): [GetReducerState<R>, React.Dispatch<GetReducerAction<R>>];
+/**
+ * PUBLIC OVERLOAD: Direct initialization
+ */
+declare function useReducer<R extends React.Reducer<any, any>>(reducer: R, initialState: GetReducerState<R>, initializer?: undefined, label?: string): [GetReducerState<R>, React.Dispatch<GetReducerAction<R>>];
+declare function createContext<T>(defaultValue: T, label?: string): React.Context<T>;
+declare function useContext<T>(context: React.Context<T>): T;
 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 useCallback<T extends (...args: unknown[]) => unknown>(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 const useId: (label?: string) => string;
+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 useRef: typeof React.useRef;
+declare const useId: typeof React.useId;
 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 useSyncExternalStore: typeof React.useSyncExternalStore;
+declare const useTransition: typeof React.useTransition;
+declare const useDeferredValue: typeof React.useDeferredValue;
+declare const use: <T>(usable: React.Usable<T>) => T;
 
 interface BasisProviderProps {
     children: ReactNode;
     debug?: boolean;
+    showHUD?: boolean;
 }
 declare const BasisProvider: React__default.FC<BasisProviderProps>;
 declare const useBasisConfig: () => {
     debug: boolean;
 };
 
-export { BasisProvider, configureBasis, getBasisMetrics, printBasisHealthReport, use, useActionState, useBasisConfig, useCallback, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition };
+declare const configureBasis: (c: any) => void;
+declare const printBasisHealthReport: (threshold?: number) => void;
+declare const getBasisMetrics: () => {
+    engine: string;
+    hooks: number;
+    analysis_ms: string;
+    entropy: string;
+};
+
+export { BasisProvider, configureBasis, createContext, getBasisMetrics, printBasisHealthReport, use, useActionState, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition };