# VISION: typst-leaf

## 1. Product Philosophy
**typst-leaf** is a high-performance, self-hosted LaTeX alternative built for the modern era. It rejects the bloated, slow architecture of traditional LaTeX editors in favor of the **Typst** ecosystem.

It is designed for:
1.  **Speed:** Sub-50ms compile times.
2.  **Sovereignty:** Your data lives in a standard Git repository on your filesystem, not a proprietary database.
3.  **Developer Experience:** First-class Vim support, fast LSP feedback, and CLI-based workflows.

## 2. Architecture Overview
The system follows a strict **Client-Server** model, even when running locally.

### The Stack
* **Monorepo Structure:** Flat directory structure (`typst-leaf-backend`, `typst-leaf-frontend`).
* **Frontend:** React (Vite) + Monaco Editor.
* **Desktop Wrapper:** Tauri v2 (integrated into `typst-leaf-frontend`).
* **Backend:** TypeScript (Node.js) + Express.
* **Core Engine:** `tinymist` (Binary) for LSP and compilation.

### Component Breakdown

#### A. Backend (`typst-leaf-backend`)
The backend is a stateless orchestration layer that sits on top of the file system.
* **Role:**
    * Spawns and manages the `tinymist` process.
    * Proxies WebSocket connections for LSP (Language Server Protocol).
    * Proxies WebSocket connections for the Preview (SVG stream).
    * Exposes a REST API for file management (CRUD) and Git operations (`git commit`, `git push`).
* **Data Source:** Standard OS file system. Each "Project" is a directory.

#### B. Frontend (`typst-leaf-frontend`)
A Single Page Application (SPA) that acts as the IDE interface.
* **Editor:** Monaco Editor configured with a custom ~300-line raw JSON-RPC LSP client (no `monaco-languageclient`).
* **Preview:** A high-performance SVG renderer that receives delta updates from Tinymist.
* **Vim Mode:** `monaco-vim` toggleable via toolbar, persisted to `localStorage`.
* **Tauri Integration:** The frontend folder contains `src-tauri`, allowing it to build as a native desktop application.

## 3. Critical Technical Decisions

### 3.1 The "No-Database" Database
We do not use MongoDB, Postgres, or SQL.
* **State:** The state is the file system.
* **History:** The history is the `.git` folder.
* **Collaboration:** We do not implement Operational Transforms (OT) or CRDTs for simultaneous editing. Collaboration is handled via Git (Commit/Push/Pull) logic exposed in the UI.

### 3.2 The Rendering Pipeline
We **do not** render PDFs in the browser for preview.
1.  User types in Monaco.
2.  Frontend sends `textDocument/didChange` (LSP) to Backend.
3.  Backend pipes to `tinymist`.
4.  `tinymist` computes layout and pushes an **SVG** diff to the preview socket.
5.  Frontend renders the SVG.
*Rationale:* SVGs are selectable, zoomable without blur, and significantly lighter than streaming PDF binaries.

### 3.3 The LSP Connection
We use a raw JSON-RPC WebSocket client (no `monaco-languageclient`) to connect Monaco to the backend. The backend simply pipes this socket to the stdin/stdout of the running `tinymist` binary. We do not reimplement LSP logic in TypeScript.

## 4. User Stories
* **As a User,** I want to type code and see the result instantly (<100ms lag).
* **As a User,** I want to double-click an element in the preview and have my cursor jump to the code (SyncTeX/Source Mapping).
* **As a User,** I want to hit `Cmd+S` to save to disk and `Cmd+Shift+S` to create a Git commit.