@vanduo-oss/vd3-flowchart 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 All notable changes to `@vanduo-oss/vd3-flowchart` are documented here.
 
+## 1.4.0 — 2026-10-03
+
+### Changed
+
+- **Behavior change:** with the new default `keyboardShortcuts: 'mindmap'`,
+  Enter on a selected node adds a sibling; F2, Space, or typing edits the
+  label. While editing, Enter saves (Shift+Enter: new line; textbox nodes keep
+  Enter for a new line). Use `keyboardShortcuts: 'basic'` for the 1.3.0 keys.
+- Arrow keys select the nearest node in that direction instead of cycling
+  through document order.
+- Selected nodes no longer draw side resize dots; sides resize by dragging the
+  edge. Corner handles are squares on a slightly outset frame.
+- Connection handles sit outside each side, appear on hover as well as on
+  selection, and no longer shift on hover (the scale transform used the node
+  origin).
+- **Document format 1.3.0:** nodes may carry `collapsed: true` (written only
+  on collapsed nodes). Every 1.x document through 1.3.0 still loads; packages
+  older than 1.4.0 reject 1.3.0 files as a future version.
+- Double-clicking a connection edits its label instead of entering reconnect
+  mode (a single click already shows the reconnect endpoints).
+- The `select` event payload adds `nodeIds`; `selection` keeps its shape.
+
+### Added
+
+- `keyboardShortcuts` option and Vue prop (`'mindmap' | 'basic'`) with
+  `FLOWCHART_KEYBOARD_SHORTCUTS`. Mind-map keys: Tab adds a child, Enter /
+  Shift+Enter add a sibling below / above, Tab while editing saves and adds a
+  child. All modes: Alt+Arrow nudge (Shift for 1 px), Cmd/Ctrl+D duplicate,
+  Cmd/Ctrl + `=` / `-` / `0` zoom, Shift+1 fit, staged Esc, and a `?` overlay
+  (also on the toolbar). Shift+Tab is never captured.
+- Clicking a connection handle adds a connected node in that direction and
+  opens it for editing; dragging still connects.
+- `insertBranchNode()`, `insertSiblingNode()`, `navigateSelection()`,
+  `nudgeNode()`, `duplicateSelection()`, `zoomTo()`, `revealNode()`, and
+  `toggleShortcutsHelp()`; `startTextEdit()` accepts `{ initialText }`.
+- Dashed selection frame for circle, diamond, and label nodes.
+- Multi-select: Shift+click toggles, Shift+drag on empty canvas draws a
+  marquee, Cmd/Ctrl+A selects all. Groups drag, nudge, copy, cut, paste,
+  duplicate (with internal connections), and delete as one undo step each.
+  `selectNodes()`, `toggleNodeSelection()`, `getSelectedNodeIds()`,
+  `isNodeSelected()`, `nudgeNodes()`.
+- Collapsible branches with a "+N" badge, a "−" toggle on a selected parent,
+  and Cmd/Ctrl+/; hidden nodes are skipped by navigation, fit, minimap,
+  guides, connection targets, and selection. `setCollapsed()`,
+  `toggleCollapsed()`, `getVisibleNodes()`, `isNodeHidden()`.
+- Connection labels from the keyboard: Shift+Arrow selects a node's connection
+  on that side (repeat to cycle); Enter, F2, or typing edits inline; arrows
+  move to the end nodes. `startEdgeLabelEdit()`, `selectSideEdge()`.
+- Alignment guides while dragging, with Alt to bypass; `snapGuides` option.
+- Minimap with click/drag panning, a toolbar toggle, and the `minimap` option;
+  it hides on canvases narrower than 480px. `setMinimapEnabled()`,
+  `centerViewOn()`.
+- `autoLayout` option: re-run the current tree or radial layout after
+  keyboard or handle insertions, in the same undo step.
+
+### Fixed
+
+- A node and its edge from `addChildNode()`, a handle click, or the keyboard
+  undo in one step; naming a just-inserted node joins that step. New branch
+  edges copy the sibling's or parent's edge style.
+- Deleting a node from the keyboard selects its parent.
+- The palette "Shapes" title no longer wraps mid-word in narrow columns.
+- Inserted sibling connections keep sibling order for tree and radial layouts.
+- The label editor no longer re-selects text that the user has already
+  started typing.
+
+## 1.3.0 — 2026-09-17
+
+### Added
+
+- Keyboard canvas navigation (arrows, Home/End, Enter to edit) and a native
+  **Graph outline** with labelled Edit/Connect controls.
+- `FLOWCHART_DOCUMENT_VERSION` owns saved `version`. Package release stays on
+  `VD_FLOWCHART_VERSION`.
+
+### Fixed
+
+- Option updates (read-only, grid, history) keep the live editor, camera,
+  selection, and applicable history. Parent echoes of emitted documents do
+  not loop.
+- Malformed JSON and unsupported future documents throw before the active
+  document, selection, or history change. Unversioned input and numeric or
+  shortened 1.x versions through 1.2.0 still load.
+- Graph outline refuses self-connection.
+- Node drag translates the moved SVG node and rebuilds only incident edges;
+  pointer-up still records history.
+
 ## 1.2.0 — 2026-09-13
 
 Extracted from `@vanduo-oss/vd3-cbun@1.4.2` as a standalone package. Component

package/README.md

@@ -6,8 +6,9 @@ Vanduo **flowchart** for Vue 3: a node/edge editor with undo/redo, layout
 modes, and a framework-agnostic core. Extracted 1-to-1 from
 `@vanduo-oss/vd3-cbun` flowchart **1.2.0**.
 
-**Status: 1.2.0.** `VD_FLOWCHART_VERSION` matches the package version and is
-**load-bearing** — `toJSON()` writes it into user documents. Do not reset it.
+**Status: 1.4.0.** `VD_FLOWCHART_VERSION` tracks the package release.
+`FLOWCHART_DOCUMENT_VERSION` (currently `1.3.0`) is the value `toJSON()`
+writes. Do not reset either independently without a compatibility plan.
 
 ## Install
 
@@ -30,6 +31,7 @@ import {
   LAYOUT_MODES,
   FLOWCHART_NODE_TYPES,
   VD_FLOWCHART_VERSION,
+  FLOWCHART_DOCUMENT_VERSION,
 } from '@vanduo-oss/vd3-flowchart';
 import '@vanduo-oss/vd3-flowchart/css';
 ```
@@ -38,7 +40,8 @@ Named exports only — no default export. `VdFlowchart` is the Vue wrapper; the
 editor class is re-exported as `VdFlowchartCore` (same class name upstream).
 `computeLayout`, `LAYOUT_MODES`, and the `FLOWCHART_*` tables
 (`FLOWCHART_NODE_TYPES`, `FLOWCHART_PORTS`, `FLOWCHART_EDGE_MARKERS`,
-`FLOWCHART_EDGE_ROUTES`) ship alongside. The core does not import Vue.
+`FLOWCHART_EDGE_ROUTES`, `FLOWCHART_KEYBOARD_SHORTCUTS`) ship alongside. The
+core does not import Vue.
 
 `vue` is never bundled — it stays external in both the esm and cjs outputs.
 The build emits `dist/meta.json` and **fails** if any input leaves `src/` or
@@ -47,10 +50,55 @@ if anything but `vue` is externalized. The package declares
 
 ## Version policy
 
-`package.json` version **is** `VD_FLOWCHART_VERSION` (`1.2.0`). Bump both
-together, and only when the serialized document format changes. This continues
-the old-line `@vanduo-oss/flowchart` lineage (never reset to `1.0.0`). Do not
-reuse the retired npm name `@vanduo-oss/flowchart`.
+`package.json` version **is** `VD_FLOWCHART_VERSION` (`1.4.0`). Bump those
+together for a package release. Keep `FLOWCHART_DOCUMENT_VERSION` unchanged
+unless the serialized schema changes; add fixtures and explicit compatibility
+rules for a format change. Unversioned 1.x documents through 1.3.0 still load;
+1.3.0 added the optional node field `collapsed: true`, written only on
+collapsed nodes.
+Malformed JSON and unsupported future versions throw before the active
+document, selection, or history change. This continues the old-line
+`@vanduo-oss/flowchart` lineage (never reset to `1.0.0`). Do not reuse the
+retired npm name `@vanduo-oss/flowchart`.
+
+## Editing and keyboard
+
+Hover or select a node to show a connection handle outside each side. Drag a
+handle to connect; click it to add a connected node in that direction. Resize
+from the corner squares or by dragging a side. Dragged nodes snap to other
+nodes' edges and centres (hold Alt to bypass; `snapGuides: false` turns it
+off). Shift+click or Shift+drag on empty canvas selects several nodes, which
+then move, nudge, copy, duplicate, and delete together. A collapsed branch
+shows a "+N" badge; click it or press Cmd/Ctrl+/ to toggle. The minimap in
+the canvas corner pans the view (`minimap: false` or the toolbar toggle hides
+it). Double-click a connection to edit its label. Set `autoLayout: true` to
+re-run the current tree or radial layout after each keyboard or handle
+insertion.
+
+With the canvas focused, the default `keyboardShortcuts: 'mindmap'` mode
+follows mind-map tools such as XMind and MindNode:
+
+| Keys | Action |
+| --- | --- |
+| Arrow keys | Select the nearest node in that direction |
+| Shift+Arrow | Select a connection on that side (repeat to cycle) |
+| Enter, F2, or typing on a connection | Edit its label |
+| Cmd/Ctrl+A | Select all nodes |
+| Cmd/Ctrl+/ | Collapse or expand the branch |
+| Tab | Add a child node and edit it |
+| Enter / Shift+Enter | Add a sibling below / above and edit it |
+| F2, Space, or typing | Edit the label |
+| Enter / Tab while editing | Save / save and add a child (Shift+Enter: new line) |
+| Alt+Arrow (Shift for 1 px) | Nudge the node by one grid step |
+| Cmd/Ctrl+D | Duplicate the node |
+| Cmd/Ctrl + `=` / `-` / `0`, Shift+1 | Zoom in, out, 100%, fit |
+| Esc | Cancel editing, then the tool, then deselect |
+| Shift+Tab, or Esc then Tab | Leave the canvas |
+| `?` | Show all shortcuts |
+
+`keyboardShortcuts: 'basic'` keeps Tab for focus movement; Enter or F2 edits and
+Ctrl/Cmd+Enter saves. A node plus its edge is one undo step, and naming a
+just-inserted node joins that step.
 
 ## Theming
 
@@ -60,10 +108,13 @@ package dependency; any provider of the tokens works.
 
 ```js
 import '@vanduo-oss/vd3/css';
-// …or the tokens-only layer:
+// Same component styles without bundled icon fonts:
 import '@vanduo-oss/vd3/css/core';
 ```
 
+`@vanduo-oss/vd3/css/core` is **not** tokens-only. Token JSON is
+`@vanduo-oss/vd3/tokens.json`.
+
 Tokens consumed include `--vd-bg-primary`, `--vd-bg-secondary`,
 `--vd-text-primary`, `--vd-text-muted`, `--vd-border-color`, and
 `--vd-color-primary` (via `--vd-flowchart-*` locals).
@@ -83,9 +134,24 @@ Tokens consumed include `--vd-bg-primary`, `--vd-bg-secondary`,
 
 | Export | Contents |
 | --- | --- |
-| `@vanduo-oss/vd3-flowchart` | `VdFlowchart` + `VdFlowchartCore`, layout, `FLOWCHART_*`, `VD_FLOWCHART_VERSION` |
+| `@vanduo-oss/vd3-flowchart` | `VdFlowchart` + `VdFlowchartCore`, layout, `FLOWCHART_*`, `VD_FLOWCHART_VERSION`, `FLOWCHART_DOCUMENT_VERSION` |
 | `@vanduo-oss/vd3-flowchart/css` | Stylesheet (`dist/vd3-flowchart.css`) |
 
+## Tested interaction envelope
+
+Observed on a Mac mini (Apple M4, 10 cores, 24 GB, macOS 26.6.2) with
+Chromium 153 at 1440×1000, no CPU throttling. Two warmups and ten samples per
+synchronous operation; drag used 24 pointer steps. Times include forced layout
+and exclude compositor paint. These are observations, not supported-size
+guarantees.
+
+- Graph label edit: 25 / 100 / 250 / 500 nodes → 2.9 / 11.2 / 29.9 / 57 ms.
+- Graph undo + redo: 3.6 / 14 / 34.5 / 69.8 ms.
+- Graph tree/grid layout: 2.9 / 11.1 / 28.4 / 58.9 ms.
+- Graph drag (translate the moved node SVG and rebuild only incident edges): 0.2 / 0.3 / 0.2 / 0.3 ms, down from 1.6 / 4.5 / 10.7 / 20.7 ms before that path.
+
+Raw JSON: `vd3-docs/reviews/2026-09-16/performance-results.json`.
+
 ## Development
 
 ```sh

package/SKILL.md

@@ -1,47 +1,60 @@
 ---
 name: vanduo-vd3-flowchart
-description: Use when adding Vanduo Vue 3 flowchart with @vanduo-oss/vd3-flowchart — node/edge editor, undo/redo, layout modes, and a framework-agnostic core. Covers install, CSS, theming, and the load-bearing VD_FLOWCHART_VERSION 1.2.0.
+description: Integrate @vanduo-oss/vd3-flowchart into Vue 3 apps with controlled documents, editing, layouts, undo, and JSON persistence.
 ---
 
-# @vanduo-oss/vd3-flowchart
-
-Standalone Vue 3 flowchart package. `vue >=3.3.0` is a required peer. The root
-import re-exports the Vue wrapper AND the framework-agnostic core
-(`VdFlowchartCore`). `VD_FLOWCHART_VERSION` is `1.2.0` and matches
-`package.json`.
-
-## Install
-
-```sh
-pnpm add @vanduo-oss/vd3-flowchart
-```
-
-Nothing registers globally. For correct theming, provide the Vanduo `--vd-*`
-design tokens (see [Theming](#theming)).
-
-## Flowchart
-
-```js
-import { VdFlowchart, VdFlowchartCore } from '@vanduo-oss/vd3-flowchart';
-import '@vanduo-oss/vd3-flowchart/css';
-```
-
-`VdFlowchart` is the Vue 3 wrapper; the framework-agnostic editor core is the
-same class name upstream, so it is re-exported as `VdFlowchartCore`. The entry
-also re-exports `computeLayout`, `LAYOUT_MODES`, and the `FLOWCHART_*` constant
-tables (`FLOWCHART_NODE_TYPES`, `FLOWCHART_PORTS`, `FLOWCHART_EDGE_MARKERS`,
-`FLOWCHART_EDGE_ROUTES`) plus `VD_FLOWCHART_VERSION`. CSS ships at
-`@vanduo-oss/vd3-flowchart/css`. `VD_FLOWCHART_VERSION` is `1.2.0` — it
-continues the old-line lineage (never reset to `1.0.0`) because the value is
-serialized into user documents via `toJSON().version`; resetting it would
-mislabel documents saved by the old line.
-
-## Theming
-
-Flowchart uses `--vd-*` tokens (via `--vd-flowchart-*` locals) with built-in
-fallbacks. vd3 is not a package dependency.
-
-```js
-import '@vanduo-oss/vd3/css';
-import '@vanduo-oss/vd3/css/core';
-```
+# Vanduo flowchart
+
+Install `@vanduo-oss/vd3-flowchart` alongside Vue. Import `VdFlowchart` and
+`@vanduo-oss/vd3-flowchart/css`; no global registration is needed. Styles have
+token fallbacks. In a VD3 app, share the base stylesheet already imported at
+app entry; choose `/css` or `/css/core`, not both.
+
+Start from [the complete editor recipe](recipes/editor.vue). It includes two
+nodes, an edge, a controlled `data` prop, change events, read-only state, and undo.
+Give the editor a definite height. Set `auto-fit` for its first measurable layout.
+
+## State and persistence
+
+Local edits emit `change` with `{ reason, document }`. Feeding `document` back
+into `data` is safe. External replacements are silent and undoable; identical
+echoes preserve selection/history. Ordinary option changes keep the live editor.
+Disabling history clears it; reenabling starts from the current document.
+
+Save `event.document` or `getInstance().toJSON()`. Core `load()` emits by default;
+catch validation errors so a failed import can be reported to the user. Unknown
+future versions and malformed JSON are rejected before changing current work.
+`FLOWCHART_DOCUMENT_VERSION` describes saved JSON; `VD_FLOWCHART_VERSION`
+describes the package release. Do not replace document versions with app versions.
+
+## Keyboard
+
+`keyboardShortcuts` defaults to `'mindmap'`: with a node selected on the focused
+canvas, Tab adds a child, Enter adds a sibling (Shift+Enter above), and F2, Space,
+or typing edits the label. While editing, Enter saves and Tab saves and adds a
+child. Arrows select the nearest node in that direction; Alt+Arrow nudges.
+Shift+Tab, or Esc then Tab, leaves the canvas. `?` lists every shortcut. Use
+`'basic'` when Tab must always move focus; Enter then edits and Ctrl/Cmd+Enter
+saves. A node plus its edge, and naming a just-inserted node, undo in one step.
+Shift+Arrow selects a connection on that side; Enter, F2, or typing edits its
+label. Shift+click, Shift+drag, and Cmd/Ctrl+A select several nodes (the
+`select` event lists them in `nodeIds`). Cmd/Ctrl+/ collapses a branch.
+
+## Canvas options
+
+`snapGuides` (default true) snaps drags to alignment guides; `minimap`
+(default true) shows the overview; `autoLayout` (default false) re-runs the
+current tree or radial layout after insertions. Saved JSON uses document
+format 1.3.0, which adds `collapsed: true` on collapsed nodes only.
+
+## Verification
+
+Add a node, toggle read-only, and confirm the edit remains. Undo/redo, save/reload,
+and echo a change back through `data`. With only the keyboard, build a small map
+with Tab, typing, and Enter, move with arrows, and use Graph outline to read
+relationships and connect nodes. Check the consumer's screen reader.
+
+Use [Vue declarations](dist/vue.d.ts) for component props/events/exposed methods
+and [core declarations](dist/core.d.ts) for document types and editor methods.
+Core `VdFlowchartCore` requires a browser element and explicit `destroy()`;
+the Vue wrapper mounts and cleans it up automatically.

package/dist/core.d.ts

@@ -11,6 +11,11 @@ export type FlowchartEdgeRoute = 'curve' | 'straight' | 'orthogonal';
 export type FlowchartEdgeKind = 'line' | 'arrow';
 export type FlowchartDirection = 'right' | 'left' | 'up' | 'down';
 export type LayoutMode = 'tree' | 'radial' | 'grid';
+/**
+ * `'mindmap'` (default): Tab adds a child, Enter adds a sibling, F2/Space or
+ * typing edits. `'basic'`: Enter edits and Tab moves focus as usual.
+ */
+export type FlowchartKeyboardShortcuts = 'mindmap' | 'basic';
 
 export interface FlowchartViewport {
   x: number;
@@ -27,6 +32,8 @@ export interface FlowchartNode {
   height: number;
   text: string;
   data: Record<string, unknown>;
+  /** Present (and true) only on collapsed nodes; document format 1.3.0. */
+  collapsed?: true;
 }
 
 export interface FlowchartEndpoint {
@@ -79,6 +86,7 @@ export interface FlowchartNodeInput {
   height?: number;
   text?: string;
   data?: Record<string, unknown>;
+  collapsed?: boolean;
   /** Place relative to another node instead of at the viewport center. */
   relativeTo?: string | FlowchartRelativeTo;
 }
@@ -111,6 +119,27 @@ export interface AddChildNodeOptions extends FlowchartNodeInput {
   edge?: FlowchartEdgeInput;
 }
 
+export interface InsertBranchNodeOptions {
+  /** Side of the parent to grow on; defaults to the branch's growth direction. */
+  direction?: FlowchartDirection;
+  /** Sibling to stack next to; defaults to the last sibling on that side. */
+  anchorId?: string;
+  /** Place before `anchorId` instead of after it. */
+  before?: boolean;
+  /** Open the label editor on the new node. */
+  edit?: boolean;
+}
+
+export interface InsertSiblingNodeOptions {
+  before?: boolean;
+  edit?: boolean;
+}
+
+export interface StartTextEditOptions {
+  /** Replace the label with this text and place the caret at the end. */
+  initialText?: string;
+}
+
 export interface LayoutOptions {
   /** Force a specific root node id; defaults to nodes with no incoming edges. */
   root?: string;
@@ -134,6 +163,8 @@ export interface MutationOptions {
 export interface LoadOptions {
   /** Keep the prior selection if the entity still exists after load. */
   preserveSelection?: boolean;
+  /** Suppress change notification; an identical document is a no-op. Used by Vue data updates. */
+  silent?: boolean;
 }
 
 export interface RemoveNodeOptions {
@@ -154,7 +185,10 @@ export interface FlowchartChangeEvent {
 }
 
 export interface FlowchartSelectEvent {
+  /** Primary item; keeps its single-item shape when several nodes are selected. */
   selection: FlowchartSelection | null;
+  /** Every selected node id, the primary node included. */
+  nodeIds: string[];
 }
 
 export interface FlowchartViewportEvent {
@@ -195,6 +229,14 @@ export interface VdFlowchartOptions {
   history?: boolean;
   /** Maximum retained history entries (default 100). */
   historyLimit?: number;
+  /** Keyboard model on the focused canvas (default `'mindmap'`). */
+  keyboardShortcuts?: FlowchartKeyboardShortcuts;
+  /** Snap dragged nodes to other nodes' edges and centres; Alt bypasses (default true). */
+  snapGuides?: boolean;
+  /** Show the overview minimap; it hides on canvases narrower than 480px (default true). */
+  minimap?: boolean;
+  /** Re-run the current tree or radial layout after insertions, in the same undo step (default false). */
+  autoLayout?: boolean;
 }
 
 export class VdFlowchart {
@@ -209,6 +251,11 @@ export class VdFlowchart {
   selectNode(nodeId: string): this;
   selectEdge(edgeId: string): this;
   deselect(): this;
+  /** Select several nodes; `primary` (default: the last id) drives single-node UI. */
+  selectNodes(nodeIds: string[], options?: { primary?: string }): this;
+  toggleNodeSelection(nodeId: string): this;
+  getSelectedNodeIds(): string[];
+  isNodeSelected(nodeId: string): boolean;
 
   // Events
   on<K extends keyof FlowchartEventMap>(
@@ -226,6 +273,27 @@ export class VdFlowchart {
     parentId: string,
     options?: AddChildNodeOptions,
   ): { node: FlowchartNode; edge: FlowchartEdge | null } | null;
+  /** Add a connected node on a side of the parent; node and edge undo as one step. */
+  insertBranchNode(
+    parentId: string,
+    options?: InsertBranchNodeOptions,
+  ): { node: FlowchartNode; edge: FlowchartEdge | null } | null;
+  /** Add a sibling next to a node (a child when the node has no parent). */
+  insertSiblingNode(
+    nodeId: string,
+    options?: InsertSiblingNodeOptions,
+  ): { node: FlowchartNode; edge: FlowchartEdge | null } | null;
+  duplicateSelection(): FlowchartNode | FlowchartNode[] | null;
+  /** Collapse or expand a node's branch; undoable, reason `node:collapse`. */
+  setCollapsed(nodeId: string, collapsed: boolean): boolean;
+  toggleCollapsed(nodeId: string): boolean;
+  /** Nodes not hidden inside a collapsed branch. */
+  getVisibleNodes(): FlowchartNode[];
+  isNodeHidden(nodeId: string): boolean;
+  nudgeNode(nodeId: string, direction: FlowchartDirection, distance: number): FlowchartNode | null;
+  nudgeNodes(nodeIds: string[], direction: FlowchartDirection, distance: number): FlowchartNode[];
+  /** Select the nearest node in a direction (spatial keyboard navigation). */
+  navigateSelection(direction: FlowchartDirection): boolean;
   updateNode(
     nodeId: string,
     patch?: Partial<FlowchartNodeInput>,
@@ -258,6 +326,16 @@ export class VdFlowchart {
   zoomOut(): this;
   resetView(): this;
   fitView(): this;
+  /** Zoom around the view centre to an absolute scale (clamped). */
+  zoomTo(scale: number): this;
+  /** Pan just enough to bring a node into view. */
+  revealNode(nodeId: string): void;
+  /** Show or hide the minimap. */
+  setMinimapEnabled(enabled: boolean): this;
+  /** Pan so a world point is at the centre of the view. */
+  centerViewOn(worldX: number, worldY: number): this;
+  /** Open, close, or toggle the keyboard shortcuts overlay. */
+  toggleShortcutsHelp(force?: boolean): this;
 
   // Document
   clear(): this;
@@ -265,10 +343,29 @@ export class VdFlowchart {
   toJSON(): FlowchartDocument;
 
   // Text editing
-  startTextEdit(nodeId: string): boolean;
+  startTextEdit(nodeId: string, options?: StartTextEditOptions): boolean;
+  /** Open the inline label editor on a connection. */
+  startEdgeLabelEdit(edgeId: string, options?: StartTextEditOptions): boolean;
+  /** Select a connection on one side of a node; repeated calls cycle. */
+  selectSideEdge(nodeId: string, direction: FlowchartDirection): boolean;
   stopTextEdit(options?: { commit?: boolean }): void;
 
   // Lifecycle
+  /** Update editor options without replacing the document, camera or selection. */
+  updateOptions(
+    options: Pick<
+      VdFlowchartOptions,
+      | 'readonly'
+      | 'gridSize'
+      | 'autoFit'
+      | 'history'
+      | 'historyLimit'
+      | 'keyboardShortcuts'
+      | 'snapGuides'
+      | 'minimap'
+      | 'autoLayout'
+    >,
+  ): this;
   destroy(): void;
 }
 
@@ -282,7 +379,10 @@ export function computeLayout(
 export const LAYOUT_MODES: readonly LayoutMode[];
 
 export const VD_FLOWCHART_VERSION: string;
+/** Schema version used by toJSON(), independent of the package release. */
+export const FLOWCHART_DOCUMENT_VERSION: string;
 export const FLOWCHART_NODE_TYPES: readonly FlowchartNodeType[];
 export const FLOWCHART_PORTS: readonly FlowchartPort[];
 export const FLOWCHART_EDGE_MARKERS: readonly FlowchartEdgeMarker[];
 export const FLOWCHART_EDGE_ROUTES: readonly FlowchartEdgeRoute[];
+export const FLOWCHART_KEYBOARD_SHORTCUTS: readonly FlowchartKeyboardShortcuts[];