# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rowsncolumns.app/getting-started/roadmap.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.