> For the complete documentation index, see [llms.txt](https://docs.rowsncolumns.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rowsncolumns.app/getting-started/roadmap.md).

# Roadmap

This document outlines the planned architectural improvements to evolve the spreadsheet engine into a high-performance, WebAssembly-driven calculation platform.

## Phase 1: Critical Reliability & Performance Fixes

*(Status: Planned)*

### 1. Fix Iterative Calculation Convergence

* **Problem**: Circular dependency checks currently return `POSITIVE_INFINITY` for non-numeric types (strings, booleans), causing infinite loops until `maxIterations` is hit.
* **Solution**: Implement strict equality checks (`===`) for non-numeric values in the convergence detection logic.
* **Impact**: Prevents wasted CPU cycles and unresponsive workers during circular reference evaluation involving status toggles or text.

### 2. Optimize Formula Parser Instantiation

* **Problem**: A new `FormulaParser` instance is created for *every single cell* during evaluation, causing massive memory churn and initialization overhead.
* **Solution**:
  * Implement a singleton `FormulaParser` in the worker.
  * Use a mutable `TaskContext` to swap out the `scopeMap` and `sheetId` for each evaluation pass without recreating the parser.
* **Impact**: Significant reduction in garbage collection pauses and faster batch processing.

### 3. Coalesce User Inputs

* **Problem**: Rapid user inputs (e.g., dragging a handle, fast typing) can flood the worker with calculation requests.
* **Solution**: Set a default `coalesceDelayMs` (e.g., 16ms) in `useCalculationWorker`.
* **Impact**: Smoother UI interactions by batching rapid-fire updates into single calculation frames.

## Phase 2: Architecture Evolution (WASM & Rust)

*(Status: Design Phase)*

### 1. In-Memory Cell Store (The "Source of Truth" Shift)

Move the authoritative state from React/JS to the Web Worker (Rust/WASM).

* **Current Architecture**:
  * React holds state → Serializes JSON → Worker calculates → Returns JSON.
  * Performance bottleneck: Data serialization and Main Thread blocking.
* **New Architecture**:
  * **Worker/WASM**: Acts as the In-Memory Database. Stores `Grid { cells: HashMap<Coord, CellData> }`.
  * **React**: Acts as the "View". Stores only the `ViewportCache` (visible cells) and `Y.Doc` (for sync).
  * **Flow**:
    1. React sends lightweight "Delta" (`A1 = 5`) to Worker.
    2. Worker updates internal WASM state.
    3. Worker recalculates affected dependencies in-memory (Zero-Copy).
    4. Worker sends back only the diffs (`B1 changed to 10`).
  * **Impact**: 60 FPS rendering regardless of dataset size (1M+ rows).

### 2. Rust-Based Formula Evaluation

* **Goal**: Replace `fast-formula-parser` (JS) with a Rust-based evaluation engine.
* **Why**: JS parsing is slow; Rust allows SIMD optimizations for array formulas and strictly typed math.
* **Plan**:
  * Expand `dag-wasm` to include an `EvaluationEngine`.
  * Port standard Excel functions to Rust.
  * Expose `evaluate(formula: &str)` directly to the DAG.

### 3. Yjs Synchronization Bridge

* **Goal**: Efficiently sync concurrent edits (CRDTs) with the linear memory of WASM.
* **Implementation**:
  * Use `Y.Doc` on the Main Thread for networking and conflict resolution.
  * Create a "Bridge" that observes `Y.Doc` changes and pushes binary/flat updates to the Worker.
  * Worker treats these updates as "External Inputs" and never writes back to Yjs directly (Unidirectional Data Flow).

## Phase 3: Excel Compatibility & Advanced Features

### 1. Precision & Date Systems

* **Date Systems**: Add support for both 1900 and 1904 date systems (Excel compatibility).
* **Number Precision**: Handle IEEE 754 floating-point quirks (e.g., `0.1 + 0.2`) to match Excel's 15-digit precision behavior.

### 2. "Smart" Range Recalculation

* **Problem**: Dependencies on large ranges (e.g., `SUM(A1:A10000)`) trigger massive data transfers.
* **Solution**: With the **In-Memory Cell Store**, range functions read directly from WASM memory. No data transfer is required between the calculation logic and the data store.

***

## Architecture Diagrams

### Data Flow (Target State)

```mermaid
graph TD
    User[User Input] --> React[React Main Thread]
    
    subgraph "Main Thread (View & Sync)"
        React -->|1. Optimistic Update| ViewCache[Viewport Cache (Zustand/useState)]
        ViewCache -->|Render| UI[Grid Component]
        
        React -->|2. Sync Changes| YDoc[Yjs Doc (CRDT)]
        YDoc -->|3. Observe & Broadcast| Bridge[Sync Bridge]
    end
    
    Bridge -->|4. Push Delta (Binary/JSON)| Worker[Web Worker]
    
    subgraph "Worker Thread (The Brain)"
        Worker -->|5. Update Memory| WasmStore[WASM Cell Store]
        
        subgraph "Rust/WASM Engine"
            WasmStore -->|Read| DAG[Dependency Graph]
            DAG -->|Topological Sort| Calc[Calculation Engine]
            Calc -->|Evaluate (In-Memory)| WasmStore
        end
        
        WasmStore -->|6. Extract Diff| DiffGen[Diff Generator]
    end
    
    DiffGen -->|7. Computed Updates (Visible Only)| React
    React -->|8. Merge Diffs| ViewCache
```