dotcanvas

A `.canvas` is a Grida design **board** — a directory bundle, not a single file. You work it like any other files: with `read_file` / `write_file` / `edit_file` (no special canvas tool). It is the durable, spatial home for a piece of work: reference images, generated outputs, and notes, arranged on an infinite canvas. Prefer a `.canvas` board for freeform visual/design work; for a linear **deck / presentation / pitch / slideshow**, use the `slides` skill. ## Structure - The bundle is a folder whose name ends in `.canvas` (e.g. `poster.canvas/`). - `.canvas.json` (the manifest) holds the STRUCTURE: which documents are on the board, their placement, order, and the `editor` mode. - Each document's CONTENT is a separate file (or a URL) referenced by its `src`. - Manifest shape (only `src` is required per document): ```json { "editor": "board", "documents": [ { "src": "https://…/ref.jpg", "id": "ref1", "layout": { "x": 0, "y": 0, "w": 480, "h": 320 } }, { "src": "outputs/hero.png", "id": "hero", "layout": { "x": 520, "y": 0, "w": 768, "h": 512 } } ] } ``` - `editor: "board"` = freeform infinite canvas (placement via `layout`). `editor: "slides"` = linear deck (order) — see the `slides` skill. - `layout` is `{ x, y, w, h, z? }` in world space (z = paint order, optional). A document with no `layout` is **unplaced** — the host positions it; set a `layout` to place it deliberately. ## Working pattern - To start, **make the bundle folder first** — a NEW directory whose name ends in `.canvas` (e.g. `poster.canvas/`); a plain folder, or files loose in the workspace root, is NOT a board and won't open. Then `write_file` its `.canvas.json` and each document file INSIDE that folder. To add to an existing board, `read_file` `.canvas.json` first (preserve `version`/`$schema`/`editor` and any unknown fields), then write the FULL updated manifest back. - A document's `src` may be a **URL** (a pointable reference — a picked library image, used as-is, no download) OR a **file path inside the bundle**. Both are first-class placed documents. - To place a **generated image** (or any produced file) on the board: **materialize it into the bundle, then reference it.** Copy it from your scratch dir into the bundle with the shell — e.g. `cp <scratch>/image-….png <board>.canvas/outputs/hero.png` — then add a document whose `src` is that bundle-relative path. (A `src` can point at any file the host can read, but a file inside the bundle is the durable, portable choice.) - To move / resize / reorder, edit the `layout` (and document order) in the manifest. The human can also drag pins directly — re-read `.canvas.json` before editing so you don't clobber their changes (last write per file wins). ## Show the result - Treat presentation as the first production milestone, not the final "validate and open" step. For a new board, establish a meaningful renderable checkpoint early: the manifest references at least one existing, valid document with a basic visible composition. Call `surface_open` immediately with the workspace-rooted `.canvas` bundle directory (for example, `/poster.canvas`), then continue building and polishing it while the user can watch. Intentionally use a lightweight initial composition instead of authoring the finished board before opening it. Do not wait for all content, assets, polish, preview generation, exhaustive validation, or task completion. - Never open an empty bundle or a broken manifest. Open only when the manifest references at least one existing, renderable document. Pass the bundle directory, never its `.canvas.json` manifest. - For an existing primary board, open it after reading its manifest and before substantial edits. - If the `.canvas` bundle itself is mounted as `/` in a dedicated file surface, it is already presented; do not call `surface_open` just to reopen it. - Treat presentation as auxiliary: continue regardless of the result, never retry based on presentation status, and do not call `surface_open` after every write. - Use `surface_list_open` only when the current host surface state is materially useful. It is not required before `surface_open`.