Canvas Lifecycle and Versions

A Canvas is a named authoring surface in a Space. Each saved change to its content is kept as a version. Versions are not edited or deleted.

Canvas

A Canvas has:

• Name: up to 5000 characters.
• Status: active or archived.
• Pinned: at most one Canvas per Space can be pinned at a time, and only active Canvases can be pinned.
• Deleted: a deleted Canvas is removed from lists.

Canvas Version

Each version records the Canvas content as saved, who saved it, when, and an optional change summary. For the content format, see Canvas Snapshot Format.

Operations

Canvas lists show active and archived Canvases. Deleted Canvases are not listed.

Version Append Semantics

No-op edits. An edit that does not change the Canvas content, such as panning or selecting, does not create a version.

Conflicts. If another session saved a new version after you started editing, your save is rejected and the Canvas does not move to your version. The editor then shows Canvas changed in another session. See Canvas Editor Actions.

Restore. Restoring a version saves its content as a new current version with the summary Restored version <versionId>. If the content already matches the current version, nothing is saved. Restoring never removes versions saved after the restored one.

Duplicate. Duplicating creates a new Canvas whose first version has the same content as the source Canvas, with the summary Duplicated from Canvas <canvasId>.

Editor Save Cadence

The editor saves changes automatically. The delay depends on the kind of change:

Continuous dragging does not save on every frame. A structural save includes the current positions, so it replaces a pending geometry save. Leaving the editor, switching away from the tab, or closing the page saves any pending changes.

Selecting nodes saves nothing.

History Grouping

The version menu groups consecutive versions by the same author that were created within 5 minutes of the group's newest version. Each group is one expandable entry. Grouping changes only how the list is shown. Every version is still listed, and none are reordered, merged, or deleted.

Lifecycle Changes

Renaming, archiving, pinning, and deleting do not create Canvas versions.

Pinning a Canvas unpins the Space's previously pinned Canvas. Pinning a Canvas that is not active returns BAD_REQUEST with the message Only active Canvases can be pinned.

Auto Layout

Auto layout repositions a set of nodes around a pinned node and saves a version with the summary Auto-arranged <n> nodes.

Requirements:

• The pinned node must be included in the nodes to arrange. Otherwise, the request returns BAD_REQUEST with Pinned node must be included in nodeIds.
• Every node to arrange must exist. Otherwise, the request returns BAD_REQUEST with Canvas node not found: <nodeId>.

Nodes without an explicit size use default dimensions: 180×64 for step: nodes and 280×180 for all other nodes.