Canvas Boards

A .canvas file is a spatial board, an infinite pannable surface whose nodes are your files, shown live, plus notes, links and labelled groups, joined by arrows you can label. Use it to lay out a design review, a system, a reading list or a plan without copying anything.

A board is a view, not a container

A file node does not hold a copy of the file. It points at the file, by a stable id and a portable path, and renders whatever that file is right now. Edit the markdown in a tab and the note on the board updates. Change the HTML and the artboard re-renders.

A board therefore has nothing to sync, but its pointers can break as files move or disappear. The section on keeping a board honest, below, covers how Monofile repairs them.

The format

.canvas is JSON Canvas 1.0, the open canvas format, plus one Monofile extension object for things the spec does not cover, such as file ids and the saved viewport. A board written in Monofile opens in other JSON Canvas tools, and a board written elsewhere opens here. Unknown fields from other apps survive a round trip untouched.

Node kinds

Nodes carry a position, a size, and optionally one of six preset colours. Array order is z-order, so the later node sits on top.

HTML nodes are artboards

An .html file node renders the page live. The node box is the viewport, so the page renders inside it at 1:1 and the canvas scales it. A board can hold the same page at mobile, tablet and desktop widths side by side, each one the live page.

The node toolbar has three presets: Mobile 390 by 844, Tablet 820 by 1180, Desktop 1440 by 900. At very low zoom, or past the live-render budget, a node shows a placeholder so a board full of pages stays responsive.

Edges

An edge runs from one node's side to another node's side and carries an optional label. Label them with a verb: "implements", "depends on", "replaces". You can turn arrowheads off for a plain association.

Editing by hand

• Add a file by dragging it from the file tree onto the board, or from the board's file picker.

• Focus a node by double-clicking it or pressing Enter. Pointer events turn on, so you can scroll a document or click through a page inside the node. Escape leaves.

• Maximize shows the node's file full window when the artboard is too small to read, and Open in tab jumps to the real file for editing.

• Convert to file turns a text note into a real .md file and swaps the node over, for when a sticky note grew into a document.

• Copy, paste, duplicate, undo and redo all work, and auto-layout arranges an unplaced board left to right or top to bottom.

• Cmd + Shift + V (Ctrl + Shift + V) shows the raw JSON.

Saving is automatic, and every write captures a version.

How agents build boards

Agents and the built-in assistant build boards with two tools. One creates a board with its nodes and edges in a single batch. The other applies a batch of operations to an existing board: add, update or delete nodes and edges, or re-run the layout. A batch is atomic, so a failed operation leaves the board unchanged. Later operations in a batch can reference nodes added earlier in it, so a board and its arrows get built in one call. A file node can carry inline content too, so "write this HTML and place it on the board at tablet size" is one operation.

Keeping a board honest

Because a board names files, it can go stale. What Monofile does in each case:

There is also a maintenance check, available as a tool and on the command line:

monofile canvas check /design/system.canvas --repair

It reports every file node whose reference is broken, stale or fragile, and --repair fixes the ones that can be fixed mechanically, in place.

Next steps