gridaco/grida/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.