From ce2079ad951fdac0ee260b3bc90e5f09b173c084 Mon Sep 17 00:00:00 2001 From: David Ibia Date: Tue, 10 Feb 2026 00:02:01 +0100 Subject: [PATCH] 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 --- AGENTS.md | 15 +++++++++++++- README.md | 58 +++++++++++++++++++++++++++++-------------------------- 2 files changed, 45 insertions(+), 28 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index af72bb8..e072c8f 100644 --- a/AGENTS.md +++ b/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": {...}} diff --git a/README.md b/README.md index e3ab1ca..9b3b2a6 100644 --- a/README.md +++ b/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 - ``` +```bash +./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`. -3. **Bundle it:** - ```bash - cargo bundle --release -p agcanvas - ``` +To install directly to `/Applications`: - This produces `target/release/bundle/osx/Augmented Canvas.app`. +```bash +./scripts/bundle-macos.sh --install +``` -4. **Install:** - ```bash - cp -r "target/release/bundle/osx/Augmented Canvas.app" /Applications/ - ``` +To add a custom icon, place an `AppIcon.icns` file in `assets/` before bundling. -> **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