Minimal Mermaid Editor

A lightweight, browser-based Mermaid diagram editor with real-time preview and collaborative editing capabilities.

Features

• 🎨 Real-time diagram preview
• 👥 Collaborative editing (when using room parameter)
• 📱 Responsive design with resizable editor
• 🔍 Pan and zoom preview
• 🤖 AI-powered diagram generation through the coding agents on your computer (agentd)
• 🎯 Smart code completion
• 🔗 Shareable diagram URLs
• 🧩 WebMCP tools for in-browser AI agents
• 🎨 Syntax highlighting
• ⌨️ Auto-closing brackets
• 📝 Comment support

Getting Started

Prerequisites

• bun

Installation

1. Clone the repository:

git clone https://github.com/nguyenvanduocit/mimaid.git
cd mimaid

2. Install dependencies:

bun install

3. Create a .env file in the root directory and add your Liveblocks API key (optional, only needed for collaborative editing):

VITE_LIVEBLOCKS_PUBLIC_API_KEY=your_api_key_here

4. Start the development server:

bun run dev

Running Tests

bun run test         # Watch mode
bun run test:run     # Single run (CI)
bun run typecheck    # TypeScript check only

The test suite covers pure-logic surfaces (URL compression, error parsing, event bus, AI prompt building, the agentd connection state, the ACP chat against a fake agent). DOM-heavy code is covered after the planned god-class refactor in Sub-Project 1.

Usage

Basic Usage

1. Write your Mermaid diagram syntax in the left editor pane
2. See the live preview in the right pane
3. Pan the preview by dragging
4. Zoom using mouse wheel
5. Resize the editor/preview split using the center handle

AI Generation

AI runs on your computer through agentd, so no API key is involved:

1. Install and open agentd (the settings panel links the Mac downloads).
2. Open the settings panel (gear icon) and press Connect agentd. agentd asks you to allow this page and to pick a folder.
3. Choose an agent (Claude Code, Codex, Grok) and, when the agent offers a choice, its model. Then describe a diagram in the input box.

The prompt tells the agent not to use tools, and the page rejects every tool permission the agent asks for. An agent that runs without asking permission is outside the page's control, so choose a folder you are comfortable with. A page's grant lasts 30 days.

Collaborative Editing

To enable collaborative editing, add the following URL parameters:

• ?room=your-room-name - Creates/joins a collaborative room
• ?name=your-name - Sets your display name (optional)

Example: http://localhost:5173/?room=team-diagram&name=Alice

Note: The URL hash contains the compressed diagram code, allowing for easy sharing without a server.

View-Only Mode

To share a view-only version of your diagram:

1. Add ?hideEditor to the URL
2. The editor will be hidden, showing only the diagram preview

WebMCP (for AI agents)

The editor registers WebMCP tools on document.modelContext, so an agent running in the browser can draw and share diagrams without scraping the UI. Browsers without WebMCP ignore it. In Chrome, enable chrome://flags/#enable-webmcp-testing or join the origin trial.

Tool	What it does
get_diagram	Current source and whether it renders (error with line and column if not)
set_diagram	Replace the editor content; the preview and URL hash update
validate_diagram	Check a draft for syntax errors without touching the editor
export_svg	Render source to a standalone SVG string
get_share_url	Link with the source in the hash: edit, embed (?hideEditor) or collab (?room=)
create_short_link	Upload to the server and return /s/<id> (90-day expiry; marked consequentialHint)
get_syntax_guide	Mermaid syntax rules for this app

Technology Stack

The project uses several key technologies:

• Vite + TypeScript for development
• Monaco Editor for code editing
• pele for diagram rendering
• Liveblocks + Yjs for collaboration
• LZ-String for URL compression
• agentd client + ACP for AI generation

License

This project is open source and available under the MIT license.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request