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):

  {
    "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.