Mermix/README.md

# Mermix

A cross-platform **Mermaid diagram editor & viewer** with **Git-backed projects**.
Organize many diagrams into projects, edit them with a live preview, export to
SVG/PNG, and version everything with real Git branches and commits — all in a
native desktop app.

Built with **Rust + Tauri 2**, **SQLite (sqlx)**, **git2**, and a **Svelte 5 +
TypeScript** frontend using **CodeMirror 6** and **Mermaid 11**.

---

## Features

- **Projects** — each project is a folder on disk that is a real Git repository
  with a `mermix.toml` config and a `diagrams/` directory of `.mmd` files.
- **Many diagrams per project** with a sidebar explorer; create, rename, delete.
- **Live editor + preview** — CodeMirror source on the left, debounced Mermaid
  render on the right, with zoom/pan and inline syntax-error reporting.
- **Git version control built in** — view the working-tree status, write commit
  messages, browse history, create branches and switch between them. Each branch
  keeps its own set of diagrams, just like normal Git.
- **Optimize panel (Diagram Doctor)** — analyse a tangled flowchart and declutter
  it in one click: a readability score and metrics (hubs, density, cross-group
  edges), plus source rewrites for the **ELK layered layout**, extra
  spacing/curved edges, **de-emphasising cross-cutting hub edges** (event bus,
  audit, cost-style fan-ins), and removing duplicate edges. A non-destructive
  **focus mode** spotlights any node and its neighbours so you can read a dense
  graph without changing it. Every rewrite lands in the editor and is reversible
  with ⌘Z.
- **Export** the current diagram to **SVG** or **PNG** (2× scale).
- **Project registry** — recently opened projects are remembered in a local
  SQLite database so you can jump back in from the start screen.
- **Themes** — switch the Mermaid theme (default / neutral / dark / forest /
  base) per project.

## Architecture

```
Mermix/
├─ src/                     # Svelte 5 + TS frontend
│  ├─ App.svelte            # layout, resizable editor/preview split
│  ├─ lib/
│  │  ├─ api.ts             # typed wrappers over Tauri commands
│  │  ├─ store.svelte.ts    # central rune-based app state
│  │  ├─ mermaid.ts         # render + error capture (registers ELK layout)
│  │  ├─ optimize.ts        # flowchart analysis + declutter transforms (pure)
│  │  ├─ export.ts          # SVG / PNG export via save dialog
│  │  └─ components/        # Sidebar, Editor, Preview, GitPanel, OptimizePanel, …
│  └─ main.ts
└─ src-tauri/               # Rust backend
   ├─ src/
   │  ├─ lib.rs             # Tauri builder, state, command registry
   │  ├─ commands.rs        # the IPC surface
   │  ├─ db.rs              # sqlx/SQLite project registry + settings
   │  ├─ project.rs         # mermix.toml, create/open, slugify
   │  ├─ diagram.rs         # .mmd CRUD, frontmatter titles
   │  ├─ git_ops.rs         # git2: commit, history, branches, status
   │  ├─ error.rs / state.rs
   │  └─ tests.rs           # headless core-logic tests
   └─ tauri.conf.json
```

**Data model.** Mermix keeps one small app-level SQLite database (in the OS app
data directory) that only tracks the *registry* of known projects and user
settings. All real content lives on disk inside each project's Git repository —
so projects are portable, inspectable, and work with any other Git tooling.

A project on disk looks like:

```
my-diagrams/
├─ mermix.toml          # project id, name, description, default theme
├─ README.md
├─ .gitignore
├─ .git/                # full Git history
└─ diagrams/
   ├─ welcome.mmd
   └─ login-flow.mmd    # Mermaid source, optional YAML frontmatter title
```

## Prerequisites

- **Rust** (stable) and **Cargo**
- **Node.js** 18+ and npm
- Platform webview deps:
  - **macOS** — nothing extra (system WebKit)
  - **Windows** — WebView2 (preinstalled on Windows 11)
  - **Linux** — `webkit2gtk` and related packages (see Tauri docs)

## Getting started

```bash
npm install          # install frontend deps + Tauri CLI

npm run app:dev      # run the desktop app in dev mode (hot reload)
npm run app:build    # build a production bundle for your platform
```

Other useful scripts:

```bash
npm run dev          # frontend only (Vite) on http://localhost:1420
npm run build        # type-check + build the frontend bundle
npm run check        # svelte-check type checking
```

Backend logic is covered by headless tests:

```bash
cd src-tauri && cargo test
```

## Keyboard shortcuts

| Shortcut            | Action                |
| ------------------- | --------------------- |
| `⌘/Ctrl + S`        | Save current diagram  |
| `⌘/Ctrl + Enter`    | Commit (in commit box)|
| `⌘/Ctrl + scroll`   | Zoom the preview      |

## How Git is used

- Creating a project runs `git init` (default branch `main`) and makes an
  initial commit.
- **Commit** stages every change (adds, edits, deletes) and records it with the
  message you type; the author defaults to your global Git identity, falling back
  to `Mermix <mermix@localhost>` if none is configured.
- **Branches** are listed in the Git panel; create one and Mermix checks it out
  for you. Switching branches reloads the diagram list from that branch.
- **History** shows the most recent commits with short SHA, message, author and
  relative time.

## License

MIT