docs: update README and AGENTS.md with boolean ops, undo tree, new architecture
- Document boolean shape operations feature and boolean_op MCP tool - Document visual undo tree with Cmd+H shortcut - Add BooleanOp to WebSocket protocol examples - Update architecture tree with history.rs, boolean.rs modules - Add i_overlay and earcutr to dependency table - Update roadmap: mark boolean ops and undo tree as complete
This commit is contained in:
David Ibia
15
AGENTS.md
15
AGENTS.md
@@ -11,6 +11,7 @@ Guidelines for AI agents working in this Rust codebase.
|
||||
- WebSocket: tokio-tungstenite
|
||||
- Serialization: serde/serde_json
|
||||
- Error handling: anyhow/thiserror
|
||||
- Boolean ops: i_overlay, triangulation: earcutr
|
||||
- Logging: tracing
|
||||
|
||||
## Build/Lint/Test Commands
|
||||
@@ -37,8 +38,19 @@ cargo doc --open # Generate and open docs
|
||||
src/
|
||||
├── main.rs # Entry point, window setup
|
||||
├── app.rs # Main app state, UI (eframe::App impl)
|
||||
├── session.rs # Session/tab state with history integration
|
||||
├── history.rs # Undo tree: branching history, snapshots, checkout, fork
|
||||
├── persistence.rs # Workspace save/load
|
||||
├── command_palette.rs # Cmd+K fuzzy command palette
|
||||
├── element_tree.rs # ElementTree, Element, ElementKind types
|
||||
├── clipboard.rs # System clipboard integration
|
||||
├── mermaid.rs # Mermaid -> SVG rendering
|
||||
├── drawing/
|
||||
│ ├── element.rs # DrawingElement, Shape (incl. Path), ShapeStyle, hit testing
|
||||
│ ├── boolean.rs # Boolean shape ops (union, intersection, difference, xor)
|
||||
│ ├── tool.rs # Tool enum, DragState, ResizeHandle
|
||||
│ ├── render.rs # Shape rendering via egui Painter + triangulation
|
||||
│ └── mod.rs # Re-exports
|
||||
├── canvas/
|
||||
│ ├── state.rs # Pan/zoom transformation state
|
||||
│ └── interaction.rs # Mouse/keyboard input handling
|
||||
@@ -46,7 +58,7 @@ src/
|
||||
│ ├── parser.rs # SVG -> ElementTree conversion
|
||||
│ └── renderer.rs # SVG -> pixels (resvg/tiny-skia)
|
||||
└── agent/
|
||||
├── protocol.rs # JSON message types
|
||||
├── protocol.rs # JSON message types (incl. BooleanOp)
|
||||
└── server.rs # WebSocket server (ws://127.0.0.1:9876)
|
||||
```
|
||||
|
||||
@@ -163,6 +175,7 @@ WebSocket server on `ws://127.0.0.1:9876`:
|
||||
{"type": "GetElementById", "id": "button-1"}
|
||||
{"type": "Describe"}
|
||||
{"type": "GenerateCode", "target": "react", "element_id": null}
|
||||
{"type": "BooleanOp", "operation": "union", "element_ids": ["id1", "id2"], "consume_sources": true}
|
||||
|
||||
// Response
|
||||
{"type": "Tree", "tree": {...}}
|
||||
|
||||
52
README.md
52
README.md
@@ -31,9 +31,11 @@ agcanvas (short for **Augmented Canvas**) bridges the gap between visual design
|
||||
### Canvas & Drawing
|
||||
- **SVG Paste** — Copy frames from Figma, paste directly (Cmd+V)
|
||||
- **Shape Drawing** — Rectangles, ellipses, lines, arrows, text directly on canvas
|
||||
- **Boolean Shape Operations** — Union, intersection, difference, XOR on overlapping shapes via agent API
|
||||
- **Selection & Editing** — Select, move, resize shapes with corner handles
|
||||
- **Mermaid Diagrams** — Write Mermaid syntax, render as SVG on canvas
|
||||
- **Sessions/Tabs** — Multiple canvases in tabs, each with independent state, creator tracking (human vs agent), descriptions, and timestamps
|
||||
- **Visual Undo Tree** — Git-like branching history with checkout, fork, and tree visualization (Cmd+H)
|
||||
- **Pan/Zoom** — Smooth canvas navigation
|
||||
- **Session Persistence** — Auto-saves workspace to `~/Library/Application Support/agcanvas/`, restores all tabs on launch
|
||||
- **Command Palette** — Cmd+K to search and execute any command with fuzzy matching
|
||||
@@ -99,36 +101,23 @@ agcanvas-mcp --help
|
||||
|
||||
### macOS `.app` Bundle
|
||||
|
||||
agcanvas compiles into a native macOS application. The release binary (`target/release/agcanvas`) runs directly, but if you want a proper `.app` bundle you can double-click in Finder or drag to `/Applications`, use [`cargo-bundle`](https://github.com/burtonageo/cargo-bundle):
|
||||
agcanvas compiles into a native macOS application (Apple Silicon and Intel). Use the bundling script to create an `Augmented Canvas.app` you can open from Finder or drag to `/Applications`:
|
||||
|
||||
1. **Install cargo-bundle:**
|
||||
```bash
|
||||
cargo install cargo-bundle
|
||||
./scripts/bundle-macos.sh
|
||||
```
|
||||
|
||||
2. **Add bundle metadata** to `crates/agcanvas/Cargo.toml`:
|
||||
```toml
|
||||
[package.metadata.bundle]
|
||||
name = "Augmented Canvas"
|
||||
identifier = "com.agcanvas.app"
|
||||
icon = ["assets/icon.icns"]
|
||||
category = "public.app-category.developer-tools"
|
||||
short_description = "Interactive canvas for agent-human collaboration"
|
||||
```
|
||||
This builds a release binary and packages it into `target/release/bundle/Augmented Canvas.app`.
|
||||
|
||||
To install directly to `/Applications`:
|
||||
|
||||
3. **Bundle it:**
|
||||
```bash
|
||||
cargo bundle --release -p agcanvas
|
||||
./scripts/bundle-macos.sh --install
|
||||
```
|
||||
|
||||
This produces `target/release/bundle/osx/Augmented Canvas.app`.
|
||||
To add a custom icon, place an `AppIcon.icns` file in `assets/` before bundling.
|
||||
|
||||
4. **Install:**
|
||||
```bash
|
||||
cp -r "target/release/bundle/osx/Augmented Canvas.app" /Applications/
|
||||
```
|
||||
|
||||
> **Note:** The raw `cargo build --release` binary already works as a native macOS app — `cargo-bundle` just wraps it in a `.app` bundle with an icon, metadata, and Finder integration. No code changes are needed.
|
||||
> **Note:** The raw `cargo build --release` binary already runs as a native macOS app — the bundle script wraps it in a `.app` with Info.plist, Finder integration, and HiDPI support. No third-party tools required.
|
||||
|
||||
### Requirements
|
||||
|
||||
@@ -169,6 +158,7 @@ agcanvas compiles into a native macOS application. The release binary (`target/r
|
||||
| Close Tab | Cmd+W |
|
||||
| Save workspace | Cmd+S |
|
||||
| Command palette | Cmd+K |
|
||||
| Toggle history panel | Cmd+H |
|
||||
| Reset zoom | Cmd+0 |
|
||||
|
||||
## MCP Server (AI Agent Integration)
|
||||
@@ -229,6 +219,7 @@ Same MCP config format — add the `agcanvas` entry to your Codex MCP configurat
|
||||
| `update_drawing_element` | Update an existing drawing element's shape or style |
|
||||
| `delete_drawing_element` | Delete a drawing element by ID |
|
||||
| `clear_drawing_elements` | Clear all drawing elements from the canvas |
|
||||
| `boolean_op` | Perform boolean operations (union, intersection, difference, xor) on two or more shapes |
|
||||
|
||||
All tools accept an optional `session_id` parameter. If omitted, the active session is used.
|
||||
|
||||
@@ -332,6 +323,14 @@ Response:
|
||||
|
||||
Targets: `html`, `react`, `tailwind`, `svelte`, `vue`
|
||||
|
||||
#### Boolean operation on shapes
|
||||
|
||||
```json
|
||||
{"type": "BooleanOp", "operation": "union", "element_ids": ["elem-1", "elem-2"], "consume_sources": true}
|
||||
```
|
||||
|
||||
Operations: `union`, `intersection`, `difference`, `xor`. Set `consume_sources` to `true` to delete the source shapes after the operation. Optional `style` object to override the result's appearance.
|
||||
|
||||
#### Ping
|
||||
|
||||
```json
|
||||
@@ -374,7 +373,8 @@ crates/
|
||||
│ └── src/
|
||||
│ ├── main.rs # Entry point, window setup
|
||||
│ ├── app.rs # Main app state, UI, toolbar, drawing interaction
|
||||
│ ├── session.rs # Session/tab state management
|
||||
│ ├── session.rs # Session/tab state management with history integration
|
||||
│ ├── history.rs # Undo tree: branching history with snapshots, checkout, fork
|
||||
│ ├── persistence.rs # Workspace save/load (~/.agcanvas/)
|
||||
│ ├── command_palette.rs # Cmd+K command palette with fuzzy search
|
||||
│ ├── element_tree.rs # Structured element representation
|
||||
@@ -382,8 +382,9 @@ crates/
|
||||
│ ├── mermaid.rs # Mermaid → SVG rendering
|
||||
│ ├── drawing/
|
||||
│ │ ├── element.rs # DrawingElement, Shape, ShapeStyle, hit testing
|
||||
│ │ ├── boolean.rs # Boolean shape operations (union, intersection, difference, xor)
|
||||
│ │ ├── tool.rs # Tool enum, DragState, ResizeHandle
|
||||
│ │ └── render.rs # Shape rendering via egui Painter
|
||||
│ │ └── render.rs # Shape rendering via egui Painter (incl. Path triangulation)
|
||||
│ ├── canvas/
|
||||
│ │ ├── state.rs # Pan/zoom transformation state
|
||||
│ │ └── interaction.rs # Mouse/keyboard input handling
|
||||
@@ -412,6 +413,8 @@ crates/
|
||||
| `tokio-tungstenite` | WebSocket (both server and client) |
|
||||
| `rmcp` | MCP server SDK (Anthropic official) |
|
||||
| `dirs` | Platform data directory paths |
|
||||
| `i_overlay` | Boolean shape operations (union, intersection, difference, xor) |
|
||||
| `earcutr` | Polygon triangulation for Path rendering |
|
||||
| `serde`/`serde_json` | Serialization |
|
||||
|
||||
## Roadmap
|
||||
@@ -425,11 +428,12 @@ crates/
|
||||
- [x] Session metadata (creator tracking, descriptions, timestamps, sorting)
|
||||
- [x] Session persistence (auto-save/restore workspace)
|
||||
- [x] Command palette (Cmd+K)
|
||||
- [x] Boolean shape operations (union, intersection, difference, xor)
|
||||
- [x] Visual undo tree with branching history
|
||||
- [ ] Real code generation (not just stubs)
|
||||
- [ ] Export to file
|
||||
- [ ] Diff view (before/after agent changes)
|
||||
- [ ] Plugin system for code generators
|
||||
- [ ] Undo/redo
|
||||
- [ ] Multi-select and group operations
|
||||
|
||||
## License
|
||||
|
||||
Reference in New Issue
Block a user