Basis is a runtime diagnostic tool for React. It treats your application state as a stream of discrete-time signals rather than a static collection of values. By analyzing the timing and topology of these signals, it can identify structural problems that static analysis tools can't see.

The name comes from linear algebra. In a vector space, a Basis is the minimal set of independent vectors needed to span the space. Any vector that can be expressed as a combination of others is redundant - it doesn't belong in the Basis.

We borrow this as a mental model for thinking about state hygiene:

• Independent State (The Basis): State variables that represent unique, non-derived sources of truth.
• Computed Projections: Values that should be derived from the independent state (e.g., via useMemo).

To be clear: react-state-basis does not perform formal mathematical analysis on your source code. It uses runtime topology as a heuristic proxy.

For example, if the engine observes that an external event consistently triggers three different Context providers at the same time, it flags this as a "Split State" architecture. This is technically valid React - but the tool reports it as a fragmented Basis and suggests consolidation to prevent tearing.

The goal is to approximate a minimal state set and help the developer spot areas where things could be simplified. It's a heuristic, not a proof.

Under the hood, the engine runs as a background process that turns React updates into a directed causal graph.

Engine "Ticks" are synchronized with requestAnimationFrame. This ties the sampling frequency to the hardware refresh rate (60Hz–144Hz), so the engine observes updates at the same rhythm the user actually sees on screen.

Unlike profilers that just count renders, Basis builds a Directed Dependency Graph in real-time.

• Implicit Events: It detects external triggers (clicks, timers) and groups the resulting updates as "siblings" - not as causal chains.
• Prime Movers: It calculates the "Spectral Influence" of every node to find which specific hook or event is the root cause of a cascade.

To keep the overhead as close to zero as possible, the engine uses a static memory model:

• Ring Buffers: Signals are stored in pre-allocated Uint8Array buffers.
• Zero-Alloc Heartbeat: Recording an update is a constant-time overwrite - no new objects, no GC pressure, no re-indexing.

Basis is a diagnostic tool, not a debugger. It operates under specific constraints that are worth understanding:

• Black-Box Observation: The engine tracks when state updates happen and who triggered them - not what the actual data is.
• Temporal Context: The topological graph keeps high-fidelity history for the active interaction window (roughly 10 seconds). Older data is pruned to prevent memory leaks.
• Asynchronous Gaps: If a logic chain has a delay longer than the analysis window (e.g., a slow API call), the engine treats the signals as independent. It can't connect what it can't observe.
• Performance First: All heavy analysis runs inside requestIdleCallback. The math only happens when the browser is idle - the frame budget is reserved for your actual UI.

This page covers the internal mechanics and heuristic approach of the Basis engine. For installation and usage, see the [README]