artifact-editor/README.md

# Artifact Editor

**AI-enhanced editor for creating diagrams, sketches, 3D models, and other artifacts from code.**

A standalone PyQt6-based editor for creating visual artifacts. Designed to integrate with discussion tools, documentation systems, and IDEs.

## Features

- **Split-view interface** - Code editor on the left, live preview on the right
- **Multi-format support** - PlantUML, Mermaid, OpenSCAD, Code, SVG, and Excalidraw
- **Interactive SVG editing** - Click to select, drag to move, resize with handles
- **Elements panel** - View and manage diagram elements
- **Visual editing** - Add, edit, and delete elements via dialogs or directly in preview
- **Templates** - Start from pre-built templates for common diagrams
- **Syntax highlighting** - Format-specific code highlighting
- **Live preview** - See changes as you type (bidirectional sync)
- **Undo/Redo** - Works for both code and visual changes
- **3D controls** - Rotate/pan OpenSCAD models with mouse

## Supported Artifact Types

| Type | Description | Features |
|------|-------------|----------|
| `plantuml` | UML diagrams (class, sequence, component, etc.) | Element editing, relationships, click-to-select |
| `mermaid` | Flowcharts, sequence, ER, state diagrams | Node editing with shapes, connections |
| `openscad` | 3D parametric CAD models | Transform controls (translate/rotate/scale), module insertion |
| `code` | Syntax-highlighted code snippets | 500+ languages, multiple themes, line numbers, font size |
| `svg` | Direct SVG graphics editing | Interactive visual editing, drag/resize, UI wireframes |
| `excalidraw` | Hand-drawn style diagrams | Sketch-like visuals, AI-readable JSON, whiteboard style |

## Installation

```bash
# Clone and install
git clone <repo>
cd artifact-editor
pip install -e .

# Or just install dependencies
pip install PyQt6

# Optional renderers
sudo apt install plantuml              # For PlantUML
npm install -g @mermaid-js/mermaid-cli # For Mermaid
sudo apt install openscad              # For 3D CAD
pip install pygments pillow            # For code syntax highlighting
```

## Usage

### Launch the GUI Editor

```bash
# Launch with default (PlantUML)
artifact-editor

# Launch for specific format
artifact-editor --type mermaid
artifact-editor --type openscad
artifact-editor --type code
artifact-editor --type svg
artifact-editor --type excalidraw

# Open existing file
artifact-editor --type plantuml --initial-file diagram.puml
```

### GUI Features

**Elements Panel (right sidebar):**
- **+Element** - Add new elements (nodes, shapes, primitives)
- **+Connection** - Add relationships between elements
- **Double-click** - Edit existing elements in a dialog
- **Delete** - Remove selected elements

**For PlantUML:**
- Add classes, interfaces, actors, components, etc.
- Define relationships (inheritance, composition, etc.)
- Click on elements in the preview to select in code

**For Mermaid:**
- Add flowchart nodes with various shapes (rectangle, diamond, circle, etc.)
- Add sequence diagram participants
- Create connections between nodes

**For OpenSCAD:**
- Add 3D primitives (cube, sphere, cylinder)
- Add 2D shapes (circle, square)
- Boolean operations (union, difference, intersection)
- Transform wrappers (translate, rotate, scale)
- Insert at cursor, end of file, or inside modules
- 3D preview with mouse rotation

**For Code:**
- Syntax highlighting for 500+ programming languages
- Multiple color themes (Monokai, Dracula, GitHub, etc.)
- Line numbers toggle
- Adjustable font size
- Live preview as you type

**For SVG:**
- **Interactive visual editing** - Click elements to select, drag to move, resize with corner handles
- Direct vector graphics editing in code or visually
- UI wireframe templates (login forms, dashboards, mobile screens)
- Pre-built UI components (buttons, inputs, cards, modals, navbars)
- System architecture and flowchart templates
- Pixel-perfect element positioning using SVG renderer bounds
- Delete key removes selected elements
- All visual changes are undoable with Ctrl+Z

**For Excalidraw:**
- Hand-drawn/sketch-style diagrams
- AI-readable JSON format (perfect for AI collaboration)
- Whiteboard-style visuals that invite discussion
- Flowcharts, mind maps, and wireframe templates
- Exports to SVG or native .excalidraw format

## Architecture

```
artifact-editor/
├── src/artifact_editor/
│   ├── cli.py              # CLI entry point
│   ├── gui.py              # PyQt6 main window
│   ├── dialogs.py          # Element/relationship dialogs
│   ├── parser.py           # PlantUML parser
│   ├── mermaid_parser.py   # Mermaid parser
│   ├── openscad_parser.py  # OpenSCAD parser
│   ├── templates.py        # Diagram templates
│   └── renderers/          # Convert source to visual output
│       ├── plantuml.py
│       ├── mermaid.py
│       ├── openscad.py
│       ├── code.py         # Pygments-based syntax highlighting
│       ├── svg.py          # Direct SVG editing with UI components
│       └── excalidraw.py   # Hand-drawn style diagrams
```

## Keyboard Shortcuts

- **Ctrl+S** - Save file
- **Ctrl+Z** - Undo (works for both code and visual edits)
- **Ctrl+Y** - Redo
- **Delete** - Remove selected element (SVG mode)
- **Ctrl+Mouse wheel** - Zoom preview
- **Click+Drag** - Move elements in SVG preview
- **Corner handles** - Resize selected elements in SVG preview

## Integration

The editor can be launched from other applications:

```bash
# Launch and specify output
artifact-editor --type TYPE --output /path/to/output.svg

# Exit codes:
# 0 - Saved successfully (stdout: "ARTIFACT_SAVED:/path/to/output.svg")
# 1 - Cancelled by user
# 2 - Error (stderr: error message)
```

Example Python integration:
```python
import subprocess

result = subprocess.run([
    "artifact-editor",
    "--type", "mermaid",
    "--output", "/tmp/diagram.svg",
], capture_output=True, text=True)

if result.returncode == 0:
    for line in result.stdout.split('\n'):
        if line.startswith("ARTIFACT_SAVED:"):
            artifact_path = line.split(":", 1)[1]
            print(f"Created: {artifact_path}")
```

## License

MIT