265 lines
8.8 KiB
Markdown
265 lines
8.8 KiB
Markdown
# 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
|
|
- **Format switching** - Change formats on the fly; file extension updates automatically
|
|
- **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
|
|
- **AI-powered generation** - Describe what you want, AI generates the code
|
|
- **Voice input** - Dictation with visual countdown timer (10 seconds)
|
|
- **Save & Exit** - Quick toolbar button for integration workflows
|
|
|
|
## 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 https://gitea.brrd.tech/rob/artifact-editor.git
|
|
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
|
|
```
|
|
|
|
## Docker
|
|
|
|
Run without installing anything locally (all dependencies included):
|
|
|
|
```bash
|
|
# Clone the repo
|
|
git clone https://gitea.brrd.tech/rob/artifact-editor.git
|
|
cd artifact-editor
|
|
|
|
# Build (automatically clones CmdForge from Gitea)
|
|
docker-compose build
|
|
|
|
# Run tests
|
|
docker-compose run --rm test
|
|
|
|
# Use the CLI tools
|
|
docker-compose run --rm cli artifact-ai --format plantuml --instruction "Create a class diagram"
|
|
echo "@startuml\nA->B\n@enduml" | docker-compose run --rm cli artifact-export --format plantuml --to /dev/stdout
|
|
|
|
# Launch GUI (requires X11: xhost +local:docker)
|
|
docker-compose run --rm gui
|
|
|
|
# Interactive shell
|
|
docker-compose run --rm shell
|
|
```
|
|
|
|
## 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
|
|
└── cmdforge/ # CLI tools following Unix philosophy
|
|
├── artifact-ai/ # AI-powered artifact generation/modification
|
|
└── artifact-export/ # Render source to binary formats
|
|
```
|
|
|
|
## CLI CmdForge Tools
|
|
|
|
In addition to the GUI, artifact-editor provides command-line CmdForge tools:
|
|
|
|
### artifact-ai
|
|
|
|
Generate or modify artifacts using AI:
|
|
|
|
```bash
|
|
# Create new artifact
|
|
echo "" | artifact-ai --format plantuml --instruction "Create a sequence diagram for user login"
|
|
|
|
# Modify existing artifact
|
|
cat diagram.puml | artifact-ai --format plantuml --instruction "Add a cache layer between API and database"
|
|
|
|
# Supported formats: plantuml, mermaid, openscad, svg, excalidraw, code
|
|
```
|
|
|
|
### artifact-export
|
|
|
|
Render artifacts to binary formats:
|
|
|
|
```bash
|
|
# PlantUML to SVG
|
|
cat diagram.puml | artifact-export --format plantuml --to output.svg
|
|
|
|
# OpenSCAD to PNG
|
|
cat model.scad | artifact-export --format openscad --to output.png
|
|
|
|
# Mermaid to PDF
|
|
cat flowchart.mmd | artifact-export --format mermaid --to output.pdf
|
|
```
|
|
|
|
Install CmdForge tools with `./install.sh` (requires CmdForge framework).
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
- **Ctrl+S** - Save file
|
|
- **Ctrl+Z** - Undo (works for both code and visual edits)
|
|
- **Ctrl+Y** - Redo
|
|
- **Ctrl+R** - Force re-render preview
|
|
- **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
|
|
|
|
## AI Input Panel
|
|
|
|
The bottom panel provides AI-assisted artifact creation:
|
|
|
|
- **Text input** - Describe what you want in natural language
|
|
- **Dictate button** - Voice input with 10-second countdown timer
|
|
- Shows `🎤 9s`, `🎤 8s`, etc. while recording
|
|
- Transcription appears in the input field for editing
|
|
- **AI Generate button** - Generates or modifies the artifact based on your description
|
|
- For new artifacts: Creates complete diagram code
|
|
- For existing content: Modifies based on instructions
|
|
- Handles retry with error context if generation fails
|
|
|
|
## 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
|