nav.sikand
b00fe3ec9e
- Backend: Express + WebSocket proxy (tsx watch, strict TS, ESM) - Frontend: React 19 + Vite + Monaco + Tailwind v4 + Tauri v2 - pnpm workspace at root for single-install workflow - AGENTS.md with architectural constraints and commands - Removed Tauri greet demo, added minimal App shell - No external database, Git-as-Database philosophy
63 lines
3.3 KiB
Markdown
63 lines
3.3 KiB
Markdown
# 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/Bun) + Express/Fastify.
|
|
* **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 `monaco-languageclient` to talk to the backend LSP.
|
|
* **Preview:** A high-performance SVG renderer that receives delta updates from Tinymist.
|
|
* **Vim Mode:** `monaco-vim` enabled by default or toggleable.
|
|
* **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 `monaco-languageclient` to connect Monaco to the backend via WebSocket. 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.
|