update readme and add icons

2026-03-29 23:40:07 -07:00
parent 52da360804
commit 79b89da023
25 changed files with 865 additions and 198 deletions
--- a/docs/building.md
+++ b/docs/building.md
@@ -0,0 +1,167 @@
+# Building
+
+## Prerequisites
+
+**Python** ≥ 3.10
+**Node.js** ≥ 18, **npm** ≥ 9
+
+### First-time setup
+
+```bash
+# Install Python dependencies
+pip install -e .
+
+# Install frontend dependencies
+npm install
+
+# For running tests
+pip install -e ".[dev]"
+
+# For building desktop executables
+pip install -e ".[desktop]"
+```
+
+Using a virtual environment is recommended:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev,desktop]"
+```
+
+---
+
+## Development
+
+Two servers run in development: the Vite frontend dev server and the Python backend. Vite proxies all API and WebSocket requests to the backend, so you only open the Vite URL in your browser.
+
+```bash
+# Terminal 1 — Python backend (http://127.0.0.1:8188)
+npm run backend
+
+# Terminal 2 — Vite frontend with hot-reload
+npm run dev
+```
+
+Open the URL printed by Vite (typically `http://localhost:5173`).
+
+Changes to Python files take effect after restarting the backend. Changes to frontend files hot-reload automatically.
+
+---
+
+## Web deployment
+
+Build the frontend bundle and serve the backend:
+
+```bash
+# Build frontend to frontend/dist/
+npm run build
+
+# Start the server (serves the built frontend at /)
+python -m backend.main
+```
+
+The server listens on `http://127.0.0.1:8188` by default. It serves the built frontend from `frontend/dist/` and exposes the REST + WebSocket API.
+
+The web mode is a multi-session server: each browser tab gets its own session and isolated file workspace. Local filesystem access is disabled (users upload files through the browser).
+
+---
+
+## Desktop app
+
+The desktop app uses pywebview to embed the frontend in a native window. The Python server runs in a background thread; the app picks a free port automatically.
+
+```bash
+# Build frontend + launch desktop app
+npm run desktop
+```
+
+This is equivalent to `npm run build && python desktop.py`.
+
+In desktop mode `allow_local_filesystem=True`, which means:
+- Users can open files directly from their filesystem
+- The plugin system is enabled (see [plugins.md](plugins.md))
+
+---
+
+## Building desktop executables
+
+The build scripts use PyInstaller to produce a self-contained executable. They build the frontend first, then package everything (Python runtime, backend, `frontend/dist/`, `demo/`) into a single distributable.
+
+### macOS
+
+Produces a `.app` bundle and a `.dmg` installer.
+
+```bash
+npm run build:mac
+# Output: desktop-dist/tono.dmg
+```
+
+Options:
+```bash
+bash scripts/build-mac.sh --onefile   # Single executable instead of bundle
+bash scripts/build-mac.sh --no-dmg    # Skip DMG creation
+```
+
+### Linux
+
+Produces a `.tar.gz` archive containing the app directory.
+
+```bash
+npm run build:linux
+# Output: desktop-dist/tono-linux.tar.gz
+```
+
+Options:
+```bash
+bash scripts/build-linux.sh --onefile  # Single executable
+bash scripts/build-linux.sh --no-tar   # Skip archive creation
+```
+
+### Windows
+
+Produces a `tono.exe` inside an output folder.
+
+```powershell
+npm run build:windows
+# Output: desktop-dist\tono\tono.exe
+```
+
+Options:
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\build-windows.ps1 -OneFile
+```
+
+> **Note:** Run the build scripts from the repo root. They expect a `.venv` at the repo root; if not found, they fall back to the system `python` / `python3`.
+
+---
+
+## Runtime data directories
+
+| Mode | Directory |
+|---|---|
+| Development | Repo root (`input/`, `output/`, `plugins/`) |
+| macOS packaged | `~/Library/Application Support/tono/` |
+| Linux packaged | `~/.local/share/tono/` |
+| Windows packaged | `%LOCALAPPDATA%\tono\` |
+
+Override with the `TONO_APPDATA` environment variable:
+
+```bash
+TONO_APPDATA=/my/data/dir python desktop.py
+```
+
+---
+
+## Key npm scripts summary
+
+| Command | Description |
+|---|---|
+| `npm run dev` | Start Vite dev server + Python backend |
+| `npm run backend` | Start Python backend only |
+| `npm run build` | Build frontend to `frontend/dist/` |
+| `npm run preview` | Preview the production frontend build |
+| `npm run desktop` | Build frontend + launch desktop app |
+| `npm run build:mac` | Build macOS `.dmg` |
+| `npm run build:linux` | Build Linux `.tar.gz` |
+| `npm run build:windows` | Build Windows `.exe` |