# Mermix

A cross-platform Mermaid diagram editor and viewer with Git-backed projects.
Organize many diagrams into projects, edit them with a live preview, export to
SVG or PNG, and version everything with real Git branches and commits 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: Create, rename, and delete diagrams via the
  sidebar explorer.
- Live editor and preview: CodeMirror source on the left, debounced Mermaid
  render on the right, with zoom, pan, and inline syntax-error reporting.
- Git version control: View working-tree status, write commit messages,
  browse history, create and switch branches. Each branch keeps its own
  set of diagrams, just like normal Git.
- Remote sync: Configure an origin remote, then fetch, pull (fast-forward),
  and push from the Git panel with live ahead/behind counts. Network
  operations use your system git, reusing existing credentials (SSH agent,
  keychain, credential helpers) — no separate login.
- Optimize panel (Diagram Doctor): Analyze a tangled flowchart or state
  diagram and declutter it in one click. Provides a readability score and
  metrics (hubs, density, cross-group edges), plus source rewrites for:
  ELK layered layout (flowcharts), extra spacing, layout-direction toggle,
  de-emphasizing cross-cutting hubs (e.g. event-bus fan-ins, faded sink
  states), and removing duplicate edges. A non-destructive focus mode
  spotlights any node and its neighbors so you can read a dense graph
  without changing it. Every rewrite lands in the editor and is reversible
  with Command + Z.
- Export the current diagram to SVG or PNG (2x scale), or copy a PNG
  straight to the clipboard. PNG export re-renders flowcharts with text
  labels so the bitmap rasterizes cleanly across platforms.
- 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, or
  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: A single app-level SQLite database (in the OS app data directory)
tracks the project registry and user settings. All content lives on disk
inside each project's Git repository — 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 dependencies:
  - 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 dependencies and 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 and 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                 |
| ---------------------- | ---------------------- |
| Command / Ctrl + S     | Save current diagram   |
| Command / Ctrl + Enter | Commit (in commit box) |
| Command / 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
  your message. 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; creating one checks it out
  automatically. Switching branches reloads the diagram list.
- History shows recent commits with short SHA, message, author, and
  relative time.
- Remote sync configures an origin remote. Fetch updates remote-tracking
  refs; pull is fast-forward only; push uses `--set-upstream`. All
  require the system `git` binary on PATH.

## License

MIT