2. The canvas and the selection model

The document model, in one paragraph#

A diagram is nodes and edges, not paths. A node has a kind (which shape to draw), a rectangle, a label, an optional description, an optional style key into the theme, and optional per-node style overrides. An edge has two ends — each either node + port or a free point — plus a routing mode and optional waypoints. That is why moving a shape re-routes its connectors, why changing a shape's kind keeps its text and its connections, and why an export can be read back in without losing anything.

Tools#

After placing a shape with the shape or text tool the editor returns to Select and opens the inline editor, so the usual rhythm is click, type, Escape.

Double-clicking empty canvas also creates the currently armed shape there and starts editing it; double-clicking an existing shape edits that shape instead (the surface handler hit-tests first, so double-clicking an icon or an image renames it rather than dropping a box on top of it).

Selecting#

• Click a shape or a connector. Shift-click to extend.
• Marquee: drag on empty canvas.
• Ctrl/⌘ A selects everything on the page.
• The right-click menu has Select entries: all, all connectors, same kind, invert, none, and — on a container — its children.
• Escape clears the selection, cancels a pending connection and returns to the select tool.

The status bar always says what is selected; the Inspector retitles itself (Node · Process, 3 nodes, Edge, 2 edges) to match.

Moving, resizing, rotating#

• Move — drag. Alignment guides appear against the edges and centres of neighbouring shapes; with Snap to grid on (⇧G) positions also snap to the grid. Guides pulled off the rulers snap too, unless you turn that off.
• Nudge — arrow keys, Shift + arrow for 10 px.
• Resize — eight handles on the selection frame. Shift keeps the aspect ratio, Alt resizes from the centre.
• Rotate — the handle above the frame. Shift snaps the angle.
• Z-order — Ctrl/⌘ ] / Ctrl/⌘ [ for front/back, add Shift for one step.
• Lock — Ctrl/⌘ L. A locked shape cannot be moved, resized or deleted by a drag; the canvas shows a hint when you try.
• Hide — Ctrl/⌘ ⇧ H.

Resizing a container carries its subtree with it; hold Ctrl/⌘ while dragging a resize handle to scale only the container and leave the children where they are. Deleting a container asks what should happen to its children (keep them and promote them, or delete the whole subtree).

Panning and zooming#

Zoom presets, fit-width, the minimap (Alt M), rulers and guides (Alt R), the dark-canvas override (Alt D) and presentation mode (F5) live in the view group of the toolbar and in the palette under View.

The dark canvas is a view setting: it never touches the document theme, so exports are unaffected. View: apply dark canvas to the document theme in the palette is the opt-in that does change the document.

The context menu#

Right-click builds a menu for the target under the pointer. The targets are canvas, node, nodes, edge, edges, mixed, container, image, erd, table and page, and each gets its own sections. Typical contents:

• canvas — paste, paste in place, insert a shape or a stencil here, select…, grid/snap/dark toggles, zoom to fit, export.
• node(s) — cut/copy/duplicate/delete, Appearance (fill and border swatches, border style and width, transparent fill, no border, copy/paste style, named styles), Arrange (order, align, distribute, size, rotate, group/ungroup, move to layer), Change shape (the whole morph grid, core and stencil), edit text, link, lock, hide.
• edge(s) — routing (orthogonal, elbow, straight, curved), line colour, style and width, start and end arrow heads (including the UML and crow's-foot heads), swap ends, add/clear waypoints, edit the label.
• image — fit mode, replace the picture, open the Images panel.
• erd — the entity helpers; table — row and column operations.
• page (right-click a page tab) — add, duplicate, rename, delete, switch.

The menu is generated from a pure model (src/ui/menuModel.ts), which is why the entries are always the ones that apply and why every one of them is covered by a test.

Undo#

Undo is patch-based and coalesced per gesture: one drag, one resize, one dialog edit and one AI plan are each a single undo entry. Ctrl/⌘ Z undoes, Ctrl/⌘ ⇧ Z (or Ctrl/⌘ Y) redoes. The status bar names the most recent entry — what Ctrl/⌘ Z would undo — and its tooltip gives the depth of the stack.

The library rail#

The left panel's libraries — Shapes, Icons, Images, Figures, Assets, Stencils, Branding, Legend, Workspace, Templates, Layers, Data, Help — sit on a vertical rail down the left edge. All of them are one click away, and the rail stays put when the panel is collapsed ([), so picking a library from a collapsed panel opens it on that library.

The selection toolbar#

Selecting something raises a small toolbar beside it:

• Tidy — runs the layout engine on the selection alone; nothing outside the selection moves.
• Fill and Style — the swatches and the style menu for what is selected.
• Change shape (single shape) — swaps the kind, keeping connectors, text, badge, image and style overrides, and the shape's centre.
• Align and distribute (multi-select).
• Insert between — for two connected shapes, or one selected connector, drops a shape in the middle and rewires both halves, pushing the downstream shapes aside only if the gap is too small.
• Select more — connected (everything reachable from the selection) and similar (same kind, same style, or both).
• Duplicate and delete.

The bar flips above, below or to the side to stay on screen, and stands down while you are dragging or editing text.

Quick-add and spacing#

A selected shape shows a faint + on each side: click one (or press Alt+←↑→↓) to create a connected shape in that direction, on the grid, at the layout engine's own spacing, stepping past anything already there.

Where several shapes are aligned in a run, a grip appears in each gap. Dragging one re-spaces the whole run to a uniform gap, anchored on the run's head, as a single undo step.

Drop a shape on a connector#

Dragging a shape from the library over an existing connector lights that connector up; dropping splices the shape in, replacing the connector with two halves that keep its routing, style, layer and arrow heads.

Universal search (Ctrl/⌘ K)#

The palette searches the whole product, not just the menus:

• commands — everything the menus and toolbar can do;
• shapes and stencils — every core shape and every BPMN, UML, ERD, network and data stencil, inserted at the centre of the view;
• icons — all 201 bundled marks, by name, set and tag ("postgres", "kafka", "docker");
• figures and templates — loads the diagram;
• panels — "Open Legend panel" opens it, whether or not the panel is collapsed;
• pages — "Go to page 2 — …", when the document has more than one;
• what is on the page — every shape with words on it and every labelled connector. Running one selects it and centres the view, so the palette is also "find in diagram".

A query has to actually match: a scattered letter-by-letter match is rejected, so an unknown word returns nothing rather than a page of near-misses.

The navigator#

Bottom right, collapsible. Beyond click-and-drag to pan:

The selection is drawn on the map in the accent colour, and when it is off screen an arrow on the viewport rectangle points at it.

An amber count appears when shapes sit outside the page. Those shapes are cut off by every export — the map draws them in amber and clicking the count selects them, so they can be moved back or the page fitted to them (Inspector → Canvas → Fit page to content).

Appearance — light, dark, or your system#

The sun/moon button in the toolbar's view group cycles Light → Dark → System. It repaints the whole application: toolbar, library rail, panels, inspector, dialogs, menus, the command palette and the navigator. The choice is remembered, and System follows your machine and re-follows it when you change it there.

The moon button next to it is a different thing and always has been: it dims the drawing only, as a view, and exports keep the document's own theme. Two buttons, because they are two decisions.

The page sizes itself#

New documents have Auto-size page on (Inspector → Canvas):

• Move, paste or lay out a shape past the edge and the page grows to contain it, so it is exported rather than silently cut off.
• When the drawing retreats, the page returns to the size you last set by hand — not to the content, so the empty space you are deliberately working into stays.
• Typing a width or height, dragging the page handle, or Fit page to content re-bases it: your number becomes the new floor.

It is one undo step with the edit that caused it. Documents that arrive from the figure library or a file have it off, because their page sizes are exact.

The title bar's colour#

Inspector → Document → Title bar, or the Branding panel for a session-wide choice. Pick the two gradient stops; the text and badge inks are derived to clear AA against whatever you choose, and the canvas and the export agree.