Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Canvas Plugin (@lapis-notes/canvas)

Source: packages/plugins/plugin-canvas/src/

Manifest: id lapis-canvas, version 0.0.1, min app version 1.7.7.

The canvas package owns external official JSON Canvas editing for .canvas files. The package remains in the monorepo for building official release artifacts, but the workspace no longer bundles or registers it by default.

Runtime Surface

  • View type: canvas.
  • Extensions: .canvas.
  • Command: create-new-canvas.
  • Official registry identity: lapis-canvas.
  • Install location: /.obsidian/plugins/lapis-canvas; listed under Core plugins when installed provenance is official.
  • Package exports: plugin runtime entry at @lapis-notes/canvas, read-only embed helpers at @lapis-notes/canvas/embed, and standalone stylesheet artifact at @lapis-notes/canvas/styles.css.

Key Behaviors

  • Parses JSON Canvas documents into Svelte Flow nodes and edges.
  • Serializes edits back into JSON Canvas after changes.
  • Supports creating, editing, resizing, coloring, and connecting text, link, file, and group nodes, including containment-driven group membership that moves contained nodes with the group, adopts dragged-in nodes, releases dragged-out nodes, and leaves contained nodes in place when the group is deleted.
  • Renders whole-file markdown file nodes through the markdown package’s editable inline markdown surface, while markdown subpath targets and non-markdown file nodes reuse the markdown package’s read-only file-embed rendering path.
  • Shows file-node filenames in a badge anchored over the node’s top-left border so the file identity stays visible even when the body is an embedded renderer.
  • Leaves embedded markdown and file-preview surfaces inert until the node is selected, so wheel and pointer gestures keep panning the canvas for unselected nodes.
  • Suppresses per-node action toolbars during multi-node selections and renders one shared bulk toolbar above the selection bounds for actions that apply to the whole selection, including grouping the selection into a newly selected group with immediate label editing, delete, recolor, and zoom.
  • Renders group labels as top-right badge inputs that keep a larger minimum edit size around mid-to-low zoom, use the available badge width instead of shrink-wrapping to the text, and choose black or white text from the computed group-badge background brightness so saturated accents like purple stay readable.
  • Renders JSON Canvas palette colors as tinted node surfaces and maps directional connectors onto compact filled edge markers that stay visible without explicit connector colors.
  • Thickens hovered connectors to the selected stroke width and glow, keeps visible connector labels on normal zoom scaling as padded label chips that mask the line beneath them, routes connectors as curved paths with short straight exit segments from node sides before the bezier span begins, renders the inline connector label editor as a CSS-sized contenteditable surface with a larger minimum edit size at small zoom, and exposes edge-toolbar actions to edit or remove existing connector labels.
  • Switches text and file nodes into low-detail previews below zoom 0.3, showing skeleton placeholders for text nodes and centered filename pills for file nodes while leaving group headers and edge labels on their normal zoom scaling path.
  • Keeps connector handles hidden at rest while their edge anchors still sit on the node boundary, and reveals each side only when its matching resize control is hovered or focused while still exposing connection-state indicators during active drags.
  • Shows valid target handles as visible indicators during connector drags and ignores duplicate identical connect emissions so one drag persists only one edge.
  • Styles the drag-selection overlay with the interactive accent token for both its border and translucent fill.
  • Uses empty-space drag as the default box-selection gesture and switches that drag gesture back to viewport panning while the Space key is held.
  • Uses wheel scrolling to pan the canvas viewport by default, while ctrl-wheel zooms the viewport, with an explicit minimum zoom of 0.03.
  • Renders group nodes as lower-layer container surfaces.
  • Clips the interactive canvas surface to the active pane.
  • Creates new empty canvas files at the vault root.
  • Persists debounced canvas edits through the vault.
  • Exports a read-only CanvasEmbed surface plus JSON Canvas parsing, serialization, flow-conversion, and color helper utilities so external hosts can render supplied canvas data without file-backed view lifecycle or save behavior.
  • Registers .canvas with the markdown embed registry so markdown reading mode and live preview render canvas file embeds through the same read-only surface instead of falling back to raw text.
  • The first embed slice intentionally stays read-only and data-driven: it renders supplied text, file, link, and group nodes without the editable canvas node toolbars, drag/resize controls, or vault-backed file preview lifecycle used by the full plugin view.
  • Hosts may optionally provide explicit file-content previews to CanvasEmbed so file nodes render richer markdown bodies while still staying read-only and vault-independent.
  • Read-only embeds keep connector arrows and passive connector labels visible, and overflowing text/file preview content scrolls inside the node body instead of expanding the host frame.

CSS Ownership

The package injects Svelte Flow and canvas styling at plugin load time, uses canvas-... namespaced selectors, and should remain aligned with the shared Plugin CSS Contract as first-party CSS ownership evolves.