# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Test Commands

```bash
# Install in development mode
pip install -e .

# Install with all dependencies
pip install -e ".[dev]"

# Run the editor
artifact-editor

# Run from source (development)
PYTHONPATH=src python3 -m artifact_editor.cli

# Run with specific format
artifact-editor --type svg --output /tmp/test.svg
```

## Architecture

Artifact Editor is a standalone PyQt6-based GUI for creating visual artifacts (diagrams, 3D models, code snippets) from code-based formats. It's designed to integrate with other tools via stdin/stdout and exit codes.

### Project Ecosystem

This is part of a three-project stack:
1. **SmartTools** - AI provider abstraction and tool execution (dependency)
2. **Orchestrated Discussions** - Conversation orchestration (launches this editor)
3. **Artifact Editor** (this) - Visual artifact creation

### Integration Protocol

When launched by a parent application (e.g., Orchestrated Discussions):

```
Parent App                          Artifact Editor
    │                                     │
    ├─ subprocess.run([                   │
    │    "artifact-editor",               │
    │    "--output", "path.puml"          │
    │  ])                                 │
    │                                     ├─ User edits/creates artifact
    │                                     ├─ User may switch format (e.g., .puml → .svg)
    │                                     ├─ User clicks Save & Exit
    │                                     │
    │  ◄────────────────────────────────  ├─ stdout: "ARTIFACT_SAVED:/actual/path.svg"
    │                                     ├─ exit code: 0 (success)
    │                                     │
    ├─ Parse stdout for ARTIFACT_SAVED    │
    ├─ Use actual path (not suggested)    │
```

**Exit Codes:**
- `0` - Success, file saved. stdout contains `ARTIFACT_SAVED:/path`
- `1` - User cancelled (closed without saving)
- `2` - Error (stderr contains message)

### Key Design Decisions

1. **Code-based formats** - All artifacts are stored as text (PlantUML, Mermaid, SVG, etc.) so AI can read and modify them
2. **Format switching** - User can change format; `output_path` extension updates automatically
3. **Non-destructive** - Undo/redo works for both code and visual edits
4. **Subprocess integration** - Clean stdin/stdout contract, no shared state

### Source Structure

```
src/artifact_editor/
├── cli.py              # Entry point, argument parsing
├── gui.py              # PyQt6 main window (~2800 lines)
├── dialogs.py          # Element editing dialogs per format
├── templates.py        # Pre-built templates (100+)
├── parser.py           # PlantUML parser
├── mermaid_parser.py   # Mermaid parser
├── openscad_parser.py  # OpenSCAD parser
├── excalidraw_parser.py # Excalidraw JSON parser
├── svg_parser.py       # SVG XML parsing
├── svg_interactive.py  # Qt-based SVG interaction
├── svg_scene.py        # QGraphicsScene SVG rendering
└── renderers/
    ├── __init__.py     # Renderer registry
    ├── plantuml.py     # Calls `plantuml` CLI
    ├── mermaid.py      # Calls `mmdc` CLI
    ├── openscad.py     # Calls `openscad` CLI
    ├── code.py         # Pygments syntax highlighting
    ├── svg.py          # Direct SVG rendering
    └── excalidraw.py   # Excalidraw JSON → SVG
```

### Key Classes

- **`ArtifactEditorWindow`** - Main PyQt6 window with split view
- **`RenderThread`** - Background rendering to avoid UI freezes
- **`DictateThread`** - Voice input with countdown timer
- **`AIThread`** - AI generation in background
- **`SVGSceneManager`** - Interactive SVG editing with QGraphicsScene

### AI Integration

Uses the `artifact-ai` SmartTool for AI-powered generation:
```python
subprocess.run(
    ["artifact-ai", "--format", format_type, "--instruction", instruction],
    input=current_code,
    capture_output=True
)
```

No direct AI provider imports - follows Unix philosophy.

### SmartTools

Artifact Editor includes SmartTools for CLI/scripting use:

```
smarttools/
├── artifact-ai/         # AI-powered artifact generation/modification
│   └── config.yaml      # Supports all formats: plantuml, mermaid, openscad, svg, excalidraw, code
└── artifact-export/     # Render source to binary formats (PNG, SVG, PDF)
    └── config.yaml
```

**artifact-ai** - Generate or modify artifacts using AI:
```bash
# Create new artifact
echo "" | artifact-ai --format plantuml --instruction "Create a sequence diagram for login"

# Modify existing artifact
cat diagram.puml | artifact-ai --format plantuml --instruction "Add a cache layer"
```

**artifact-export** - Render artifacts to binary formats:
```bash
cat diagram.puml | artifact-export --format plantuml --to output.svg
cat model.scad | artifact-export --format openscad --to output.png
```

These tools are installed to `~/.smarttools/` and `~/.local/bin/` by `./install.sh`.

### Supported Formats

| Format | Extension | Renderer | Visual Editing |
|--------|-----------|----------|----------------|
| PlantUML | `.puml` | `plantuml` CLI | Element dialogs |
| Mermaid | `.mmd` | `mmdc` CLI | Node/edge dialogs |
| OpenSCAD | `.scad` | `openscad` CLI | 3D rotation, primitives |
| Code | `.py`, etc. | Pygments | Syntax highlighting |
| SVG | `.svg` | Direct | Interactive drag/resize |
| Excalidraw | `.json` | Built-in | Hand-drawn style |

### Toolbar Actions

- **Format selector** - Switch between artifact types (updates file extension)
- **Save** - Save to current path
- **Save & Exit** - Save and close (for integration workflows)
- **Render** button by preview - Force re-render (Ctrl+R)

### AI Panel

Bottom of window:
- **Text input** - Natural language instructions
- **Dictate** - 10-second voice recording with countdown (`🎤 9s`, `🎤 8s`...)
- **AI Generate** - Sends to Claude, updates code editor

### External Dependencies

Required for rendering:
- `plantuml` - For PlantUML diagrams
- `mmdc` (mermaid-cli) - For Mermaid diagrams
- `openscad` - For 3D CAD models
- `pygments` - For code syntax highlighting