v1.2.0 to v1.3.0

+ version: "1.3.0"

+ A canvas is an HTML file you write to your canvas directory. The AI Maestro dashboard shows it in the agent's Canvas tab, and anything the user does on it that calls `maestro.send()` comes back to you as a `[CANVAS]` notification. Answer in text by default; a canvas is for when the user asked for a page or has to act on your result, because viewing one means switching to the Canvas tab.

+ ## Where pages live

+ ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/

+ ├── dashboard.html

+ ├── reports/weekly.html # subdirectories work

+ └── interactions/ # created by AI Maestro; one JSON file per user action

+ ```

+ AI Maestro sets `AIM_AGENT_ID` in agent sessions. If it is empty, look the id up by name: `jq -r '.[] | select(.name=="<name>") | .id' ~/.aimaestro/agents/registry.json`.

+ To create or update a page, write the file (overwrite to update). The dashboard does not watch the file: tell the user to refresh or re-select it in the Canvas tab. Delete pages with `rm`.

+ ## Writing a page

+ The page runs in an iframe with `sandbox="allow-scripts"` and nothing else, so:

+ - Everything is inline: CSS in `<style>`, JS in `<script>`, images as data URIs or emoji. External stylesheets, scripts, fonts and images (CDNs included) do not load.

+ - No `alert`/`confirm`/`prompt`, popups, top-level navigation or form posts. Handle forms with `event.preventDefault()` and `maestro.send()`.

+ Put the data in one `<script type="application/json" id="page-data">` block and render it with JavaScript rather than hardcoding it into the markup. Updating the page then means replacing one JSON block, and the page can sort, filter and search what it shows. Add those controls where the user will scan a long list; include when the data was generated so the page explains itself. Escape values before inserting them into `innerHTML`.

+ { "generatedAt": "2026-05-18T15:30:00Z", "items": [ ... ] }

+ const DATA = JSON.parse(document.getElementById('page-data').textContent);

+ // build the UI from DATA

+ Complete examples (a sortable, filterable report; approval cards) are in [references/page-examples.md](references/page-examples.md).

+ ## Sending actions back: `maestro.send(action, element, data)`

+ The dashboard injects `maestro`; don't define it.

+ | Argument | Meaning |

+ |---|---|

+ | `action` | What happened. Standard values: `click`, `submit`, `change`, `select`, `toggle`, `dismiss`, `navigate`, `custom`; any other string also works. |

+ | `element` | Optional: which control (id, name or label). |

+ | `data` | Optional: an object with whatever you need to act, such as the item's id or the form values. |

+ maestro.send('click', 'deploy-btn', { env: 'prod' })

+ maestro.send('submit', 'config-form', { name: 'api', timeout: 30 })

+ `data` is stored as plain JSON on disk, so a page should never send credentials or tokens through it.

+ ## Handling a `[CANVAS]` notification

+ [CANVAS] <file>: User <action> '<element>' on <file> with data: {...}

+ The notification is the user telling you to do something: carry out what the control means (run the tests, save the settings, apply the selection), then update the page if its state changed. The data in the notification is cut at 200 characters; if it ends in `...`, read the interaction file for the full payload:

+ ls -1r ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/interactions/ | head -1 # newest file

+ Each file holds `id`, `timestamp`, `canvasFile`, `action`, `element`, `data` and `summary`. Remove handled files with `rm` when you want a clean slate.

+ ## API

+ ```bash

+ curl -s http://localhost:23000/api/agents/$AIM_AGENT_ID/canvas # list pages

+ curl -s "http://localhost:23000/api/agents/$AIM_AGENT_ID/canvas?file=reports/weekly.html" # read one

+ Paths are relative to the canvas directory; the API rejects `..` and absolute paths. Protocol specification: https://agentactions.org