canvas # canvas Collaborate with Pi through editable Excalidraw drawings in a local browser canvas. ## First drawing 1. Run `/canvas open`. 2. In local browser canvas, sketch a few boxes and arrows, then finish any active text edit. 3. Ask Pi to improve, rearrange, or explain the sketch in chat. For example, draw a checkout flow, then ask: `Turn this into a happy-path flow and add the missing payment failure branch.` Pi inspects current scene before making its own editable drawing changes. Use native Undo and Redo in Excalidraw to review each Pi contribution. Choose **Download drawing** to save native Excalidraw scene at any time. ## Use in Pi Run `/canvas open` to open local canvas and enable canvas tools for current agent. Keep Pi running; agent drawings can commit while your browser is backgrounded, suspended, or closed. Returning to the tab resynchronizes the shared scene without requiring a page reload. Unsent local edits stay in the tab and are never silently overwritten. The agent automatically receives the full session URL, including its ephemeral access token, in active drawing-mode context without an extra model turn. `canvas inspect` also returns the current URL and runtime diagnostics. For browser inspection and troubleshooting, see [Debugging](DEBUGGING.md). Chat and canvas are two channels of one conversation: write normally in Pi or draw in the browser. Pi uses both as context for brainstorming, simplifying, clarifying, and improving the shared drawing. Shapes, boxes, arrows, layout, and space take priority over lengthy prose; concise chat remains available for discussion. Small reversible improvements can happen directly; substantial reinterpretations should be discussed first. Drawing saves continuously, but unfinished text edits and active gestures do not request agent responses. After interaction finishes, observations coalesce for at least 1.2 seconds and automatic deliveries are spaced at least 5 seconds apart. Changes arriving while Pi is busy merge into the latest pending observation rather than queueing every edit. A chat turn receives current canvas context and consumes already-covered pending changes without a duplicate drawing follow-up. There is no routine notification or acknowledgement for every drawing update. Observations include bounded scene metadata and, when available, a matching full-scene image from the same revision. Full-scene exports include off-screen drawing without moving your selection, pan, or zoom. Images are bounded to 1024 pixels on the longest edge and 256 KiB of base64 data; large scenes may lose fine detail. Image failure never blocks saving. Pi's contributions are ordinary editable shapes, not separate comments or threads. Only actual assistant messages update the quiet notification icon beside sharing status, including on mobile. Open it to read the latest reply; opening clears its unread dot, and a new reply lights it again. Long replies wrap and scroll inside the notification sidebar. No automatic canvas notification popups appear. The Excalidraw Pi menu group appears only when an actual assistant reply is available. Persistent sharing status shows connection and whether your drawing is shared with Pi. Canvas tools activate only in drawing mode; ordinary coding tools remain available. **Download drawing** saves the native Excalidraw scene, including Pi's visual contributions. Agent commits create one native Undo step when applied in a surviving tab, including updates caught up after suspension. Replay retains up to 64 revisions within 8 MiB; if that history expires, the latest shared state is applied as one undoable catch-up step with a warning. A full page reload starts a fresh native Undo history. Stale or conflicting changes are rejected. Stale draws require fresh inspection and reassessed placement before one retry. A blocked or abandoned contribution requires an actual assistant reply explaining why, not silent abandonment. Run `/canvas close` to disable canvas tools and stop the local server and any isolated layout process. Drawings and assistant conversation belong to the current Pi session branch. Restoring a branch cancels unfinished generation. ## Browser example ![Canvas in Firefox: an editable rectangle shared with Pi](assets/browser-drawing.png) Sketch two checkout paths in browser: a card-payment path and a payment-failure path. Finish the active text edit, then ask Pi to connect the paths and label the recovery step. Inspect the resulting editable shapes in the same tab, then use Undo and Redo to decide whether to keep each Pi change. If a second tab has conflicting unsaved work, choose **Keep my drawing**, **Use shared drawing**, or **Save copy** rather than losing either version. ## Limits and privacy Agent-created shapes, text measurement, and Mermaid require a local Chrome or Chromium installation. Canvas starts its own isolated headless process when needed; your editing tab can remain in Firefox or another browser. No browser is downloaded automatically. Style changes, moves, and deletions of existing shapes do not require the layout process. Proposals support shape additions, style changes, translation of complete connected/grouped sets, standalone auto-sizing text relabels, and deletion of complete connected/grouped sets. Moving an individual connected node while rerouting arrows, resizing existing shapes, and changing bound or fixed-width labels remain manual. Image elements are unsupported. Scenes support ≤1000 elements and 512 KiB serialized data. Concurrent tabs cannot silently overwrite each other's edits. On conflict, **Not shared with Pi** explains that your latest edits remain in this browser tab and are not reaching the agent. Visible recovery actions are **Keep my drawing**, **Use shared drawing**, and **Save copy**. Keep my drawing replaces the shared scene; Use shared drawing discards this tab's unsaved edits. Both require an inline confirmation that is revalidated against the latest scene before changing either drawing. Save copy downloads the current local scene without resolving the conflict. Temporary sharing failures and dropped event streams retry up to three times automatically. After stream retries stop, **Reconnect** restarts the connection. Leaving with unsaved edits still triggers the browser's data-loss warning; normal drawing and recovery do not use browser dialogs. Canvas binds only loopback address. The ephemeral access URL scopes browser access to this canvas server and is shared with the current agent; anyone holding it can access the drawing while the server is open. Do not publish it publicly. The browser moves its token from the URL fragment into tab-local session storage. Browser assets and fonts are served locally; CSP blocks Excalidraw's upstream CDN fallback. Full-scene images are sent to the main Pi agent's configured model provider alongside drawing observations, chat context, or inspection results; visual interpretation requires an image-capable model. Images are not included in persisted drawing snapshots or browser state streams, but observation and tool-result messages can retain images in Pi session history. Requests to model provider remain within main Pi agent, using its existing configuration. [Installation](../../README.md#install) ### Commands | Command | Purpose | | --- | --- | | `/canvas` | Open, close, or inspect drawing mode |