Canvas

Project Canvas

A .canvas file is a board: an infinite canvas whose cards can be sticky notes, text, images, frames, or live editors mounted on real workspace files and shared documents. A mockup card renders the mockup. A spreadsheet card renders the grid. A mindmap card renders the mindmap.

The editor is built into Nimbalyst, so any workspace can open a .canvas file you write. Write the JSON directly with the Write tool; there is no MCP tool for boards.

When to use a canvas

• Laying out several existing files spatially — screens of a flow, docs in a workstream, a review board
• A workspace or project overview that mixes documents, mockups, data, and notes
• Anything where the point is the arrangement of real artifacts, not a drawing

Use Excalidraw for freeform drawings and architecture sketches. Use MockupLM for a single UI screen. A canvas is the thing that holds several of those at once.

File format

JSON Canvas 1.0 superset. Every spec field keeps its spec meaning, Nimbalyst data lives under x-nimbalyst, and unknown keys at any level are preserved verbatim so a board written by another tool survives a round-trip.

{
  "nodes": [],
  "edges": [],
  "x-nimbalyst": {
    "version": 1,
    "meta": {
      "name": "Onboarding flow",
      "description": "Sign-up through first document",
      "viewport": { "x": 0, "y": 0, "zoom": 1 }
    }
  }
}

meta.viewport is the board's deliberate home view — where a reader lands on open. Each user's own scroll position is stored separately, so setting this is a choice about the board, not about you. Omit it and the board opens fit-to-content.

Nodes

Every node needs id (unique, non-empty), type, and x / y / width / height. Geometry is written as integers; the editor rounds on save either way.

color is optional on nodes and edges: the presets "1" red, "2" orange, "3" yellow, "4" green, "5" cyan, "6" purple, or any #rrggbb. Anything else is ignored.

Array order is z-order. The last node in nodes paints on top — put a frame before the cards that sit inside it. Do not invent a z-index or rank field; the editor derives ordering from array position and never writes one to the file.

Serialization is canonical, not preserved

On save the editor rewrites keys into a fixed order, sorts edges by id, and rounds geometry. Your key ordering and edge ordering will change the first time someone opens the board. That is expected — write it readably and let the editor normalize.

Cards

What a card draws as is decided by x-nimbalyst.reference, not by the spec type. The spec type is chosen so a plain JSON Canvas reader still shows something true. Always write both.

x-nimbalyst.label sets the card's label.

File card — mounts the real editor

{
  "id": "login",
  "type": "file",
  "x": 0,
  "y": 0,
  "width": 640,
  "height": 440,
  "file": "design/mockups/login.mockup.html",
  "x-nimbalyst": {
    "reference": { "kind": "file", "path": "design/mockups/login.mockup.html" },
    "label": "Login"
  }
}

The path is workspace-relative and must appear in both file and reference.path. Any file type with a registered editor works — .mockup.html, .mindmap, .excalidraw, .csv, .md, and so on. The card mounts that editor live; it is not a screenshot.

Point a file card at a file that exists. A card for a missing path renders as an unresolved placeholder.

Doc card — a shared document

{
  "id": "prd",
  "type": "link",
  "x": 700,
  "y": 0,
  "width": 640,
  "height": 440,
  "url": "nimbalyst://doc/{orgId}/{documentId}",
  "x-nimbalyst": {
    "reference": { "kind": "doc", "uri": "nimbalyst://doc/{orgId}/{documentId}" },
    "label": "Product brief"
  }
}

Only write a doc card when you have a real org and document id. Do not guess them — prefer a file card.

Native cards

reference.kind: "native" with a nativeKind, paired with the spec type below:

{
  "id": "note-open-question",
  "type": "text",
  "x": -260,
  "y": 0,
  "width": 240,
  "height": 180,
  "color": "5",
  "text": "Do we verify email before or after the first document?",
  "x-nimbalyst": { "reference": { "kind": "native", "nativeKind": "sticky" } }
}

A node with no x-nimbalyst.reference still renders — it falls back to its spec type, which is what makes a board from another tool useful rather than a wall of placeholders. Writing the reference is what gets you a sticky note instead of a plain text card.

A node whose type is outside the spec renders as an "unsupported card" placeholder and is written back untouched. Never use that as a way to smuggle in data.