rob
/
artifact-editor
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
artifact-editor/README.md

8.8 KiB
Raw Blame History

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

# 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):

# 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

# 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:

# 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:

# 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:

# 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:

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