@vanduo-oss/vd3-flowchart 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to `@vanduo-oss/vd3-flowchart` are documented here.
 
+## 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.3.0.** `VD_FLOWCHART_VERSION` tracks the package release.
+`FLOWCHART_DOCUMENT_VERSION` (currently `1.2.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';
 ```
@@ -47,10 +49,14 @@ 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.3.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.2.0 still load.
+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`.
 
 ## Theming
 
@@ -60,10 +66,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 +92,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,40 @@
 ---
 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
+# Vanduo 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 `@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.
 
-## Install
+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.
 
-```sh
-pnpm add @vanduo-oss/vd3-flowchart
-```
+## State and persistence
 
-Nothing registers globally. For correct theming, provide the Vanduo `--vd-*`
-design tokens (see [Theming](#theming)).
+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.
 
-## Flowchart
+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.
 
-```js
-import { VdFlowchart, VdFlowchartCore } from '@vanduo-oss/vd3-flowchart';
-import '@vanduo-oss/vd3-flowchart/css';
-```
+## Verification
 
-`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.
+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, select nodes using
+canvas arrows, edit with Enter, save with Ctrl/Cmd+Enter, and use Graph outline
+to read relationships and connect nodes. Check the consumer's screen reader.
 
-## 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';
-```
+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

@@ -134,6 +134,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 {
@@ -269,6 +271,13 @@ export class VdFlowchart {
   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'
+    >,
+  ): this;
   destroy(): void;
 }
 
@@ -282,6 +291,8 @@ 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[];

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var index_exports = {};
 __export(index_exports, {
+  FLOWCHART_DOCUMENT_VERSION: () => FLOWCHART_DOCUMENT_VERSION,
   FLOWCHART_EDGE_MARKERS: () => FLOWCHART_EDGE_MARKERS,
   FLOWCHART_EDGE_ROUTES: () => FLOWCHART_EDGE_ROUTES,
   FLOWCHART_NODE_TYPES: () => FLOWCHART_NODE_TYPES,
@@ -292,7 +293,8 @@ var EDGE_STROKE_PRESETS = [
   { id: "medium", label: "Medium", width: DEFAULT_EDGE_STROKE_WIDTH },
   { id: "bold", label: "Bold", width: 3.5 }
 ];
-var VD_FLOWCHART_VERSION = "1.2.0";
+var VD_FLOWCHART_VERSION = "1.3.0";
+var FLOWCHART_DOCUMENT_VERSION = "1.2.0";
 var FLOWCHART_NODE_TYPES = [
   "rounded-rect",
   "rect",
@@ -529,17 +531,45 @@ function normalizeEdge(rawEdge, index, nodeIds, usedIds) {
   syncEdgeKind(edge);
   return edge;
 }
+function parseDocumentVersion(value) {
+  const raw = typeof value === "number" && Number.isFinite(value) ? String(value) : typeof value === "string" ? value.trim() : "";
+  const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(raw);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2] ?? 0),
+    patch: Number(match[3] ?? 0)
+  };
+}
+function isSupportedDocumentVersion(value) {
+  const parsed = parseDocumentVersion(value);
+  const max = parseDocumentVersion(FLOWCHART_DOCUMENT_VERSION);
+  if (!parsed || !max || parsed.major !== max.major) return false;
+  if (parsed.minor > max.minor) return false;
+  if (parsed.minor === max.minor && parsed.patch > max.patch) return false;
+  return true;
+}
 function normalizeDocument(input) {
   let source = input;
   if (typeof source === "string") {
     try {
       source = JSON.parse(source);
     } catch {
-      source = {};
+      throw new TypeError("Invalid flowchart JSON. The current document was not changed.");
     }
   }
   if (!isPlainObject(source)) {
-    source = {};
+    throw new TypeError("A flowchart document must be an object.");
+  }
+  if (source.version !== void 0 && !isSupportedDocumentVersion(source.version)) {
+    throw new RangeError(
+      `Unsupported flowchart document version: ${String(source.version)}. Supported through ${FLOWCHART_DOCUMENT_VERSION}.`
+    );
+  }
+  for (const key of ["nodes", "edges"]) {
+    if (source[key] !== void 0 && !Array.isArray(source[key])) {
+      throw new TypeError(`Flowchart ${key} must be an array.`);
+    }
   }
   const usedNodeIds = /* @__PURE__ */ new Set();
   const nodes = (Array.isArray(source.nodes) ? source.nodes : []).slice(0, MAX_NODES).map((node, index) => normalizeNode(node, index, usedNodeIds));
@@ -547,7 +577,7 @@ function normalizeDocument(input) {
   const usedEdgeIds = /* @__PURE__ */ new Set();
   const edges = (Array.isArray(source.edges) ? source.edges : []).slice(0, MAX_EDGES).map((edge, index) => normalizeEdge(edge, index, nodeIds, usedEdgeIds)).filter(Boolean);
   return {
-    version: VD_FLOWCHART_VERSION,
+    version: FLOWCHART_DOCUMENT_VERSION,
     viewport: normalizeViewport(source.viewport),
     nodes,
     edges
@@ -1002,6 +1032,8 @@ function getBounds(nodes) {
 function createField(labelText, control) {
   const wrapper = createElement("div", { className: "vd-flowchart-field" });
   const label = createElement("label", { text: labelText });
+  control.id || (control.id = nextId("flowchart-field"));
+  label.htmlFor = control.id;
   wrapper.appendChild(label);
   wrapper.appendChild(control);
   return wrapper;
@@ -1386,14 +1418,127 @@ var VdFlowchart = class {
     this.jsonActions.appendChild(this.loadJsonButton);
     this.jsonPanel.appendChild(this.jsonTextarea);
     this.jsonPanel.appendChild(this.jsonActions);
+    this.jsonStatus = createElement("p", { className: "vd-flowchart-json-status" });
+    this.jsonStatus.setAttribute("role", "status");
+    this.jsonPanel.appendChild(this.jsonStatus);
     this.inspectorPanel.appendChild(this.jsonPanel);
     this.body.appendChild(this.palettePanel);
     this.body.appendChild(this.canvasEl);
     this.body.appendChild(this.inspectorPanel);
     this.root.appendChild(this.toolbar);
     this.root.appendChild(this.body);
+    this.buildGraphOutline();
     this.element.appendChild(this.root);
   }
+  buildGraphOutline() {
+    this.graphOutline = createElement("details", { className: "vd-flowchart-outline" });
+    this.graphOutline.appendChild(createElement("summary", { text: "Graph outline" }));
+    this.graphOutline.addEventListener("toggle", () => {
+      if (this.graphOutline.open) this.renderGraphOutline();
+    });
+    this.graphStatus = createElement("p", { className: "vd-flowchart-sr-only" });
+    this.graphStatus.setAttribute("role", "status");
+    this.canvasEl.appendChild(this.graphStatus);
+    this.graphControls = createElement("div", { className: "vd-flowchart-outline-controls" });
+    this.graphNodeSelect = createElement("select");
+    this.graphNodeSelect.setAttribute("aria-label", "Selected node");
+    this.graphNodeSelect.addEventListener(
+      "change",
+      () => this.selectNode(this.graphNodeSelect.value)
+    );
+    this.graphTargetSelect = createElement("select");
+    this.graphTargetSelect.setAttribute("aria-label", "Connection target");
+    this.graphTargetSelect.addEventListener("change", () => this.renderGraphOutline());
+    this.graphConnectButton = createElement("button", {
+      text: "Connect nodes",
+      type: "button",
+      className: "vd-flowchart-btn"
+    });
+    this.graphConnectButton.addEventListener("click", () => {
+      if (this.readonly || this.graphNodeSelect.value === this.graphTargetSelect.value) {
+        return;
+      }
+      this.addEdge({
+        from: this.graphNodeSelect.value,
+        to: this.graphTargetSelect.value,
+        autoPort: true
+      });
+    });
+    this.graphEditButton = createElement("button", {
+      text: "Edit selected label",
+      type: "button",
+      className: "vd-flowchart-btn"
+    });
+    this.graphEditButton.addEventListener(
+      "click",
+      () => this.startTextEdit(this.graphNodeSelect.value)
+    );
+    this.graphControls.append(
+      createField("Selected node", this.graphNodeSelect),
+      createField("Connection target", this.graphTargetSelect),
+      this.graphConnectButton,
+      this.graphEditButton
+    );
+    this.graphOutline.appendChild(this.graphControls);
+    this.graphList = createElement("ul");
+    this.graphList.setAttribute("aria-label", "Nodes and connections");
+    this.graphOutline.appendChild(this.graphList);
+    this.root.appendChild(this.graphOutline);
+    this.canvasEl.setAttribute("role", "group");
+    this.canvasEl.setAttribute(
+      "aria-label",
+      "Diagram canvas. Arrow keys select nodes; Enter edits a label. Graph outline provides connections."
+    );
+    this.jsonTextarea.setAttribute("aria-label", "Flowchart JSON");
+  }
+  renderGraphOutline() {
+    if (!this.graphOutline) return;
+    const nodes = this.documentData.nodes;
+    const edges = this.documentData.edges;
+    const labels = new Map(nodes.map((node) => [node.id, node.text || node.id]));
+    const selected = this.selection?.kind === "node" ? this.selection.id : null;
+    this.graphStatus.textContent = selected ? `Selected: ${labels.get(selected)}. ${nodes.length} nodes, ${edges.length} connections.` : `${nodes.length} nodes, ${edges.length} connections.`;
+    if (!this.graphOutline.open) return;
+    const signature = JSON.stringify([
+      nodes.map((node) => [node.id, node.text]),
+      edges.map((edge) => [edge.id, edge.from.nodeId, edge.to.nodeId, edge.label])
+    ]);
+    if (signature !== this.graphSignature) {
+      this.graphSignature = signature;
+      for (const select of [this.graphNodeSelect, this.graphTargetSelect]) {
+        const previous = select.value;
+        select.replaceChildren();
+        for (const node of nodes)
+          select.appendChild(
+            createElement("option", { value: node.id, text: labels.get(node.id) })
+          );
+        if (labels.has(previous)) select.value = previous;
+      }
+      this.graphList.replaceChildren();
+      const outgoing = new Map(nodes.map((node) => [node.id, []]));
+      const incoming = new Map(nodes.map((node) => [node.id, []]));
+      for (const edge of edges) {
+        outgoing.get(edge.from.nodeId)?.push(`${labels.get(edge.to.nodeId)}${edge.label ? ` (${edge.label})` : ""}`);
+        incoming.get(edge.to.nodeId)?.push(labels.get(edge.from.nodeId));
+      }
+      for (const node of nodes) {
+        const to = outgoing.get(node.id);
+        const from = incoming.get(node.id);
+        const relationships = [
+          to.length ? `Connects to ${to.join(", ")}.` : "No outgoing connections.",
+          from.length ? `Connected from ${from.join(", ")}.` : ""
+        ];
+        this.graphList.appendChild(
+          createElement("li", { text: `${labels.get(node.id)}. ${relationships.join(" ")}` })
+        );
+      }
+    }
+    if (selected) this.graphNodeSelect.value = selected;
+    this.graphNodeSelect.disabled = nodes.length === 0;
+    this.graphTargetSelect.disabled = this.readonly || nodes.length < 2;
+    this.graphConnectButton.disabled = this.readonly || nodes.length < 2 || this.graphNodeSelect.value === this.graphTargetSelect.value;
+    this.graphEditButton.disabled = this.readonly || nodes.length === 0;
+  }
   bindEvents() {
     this.toolbar.addEventListener("click", this.handleToolbarClick);
     this.arrangeSelect.addEventListener("change", this.handleArrangeChange);
@@ -1500,7 +1645,12 @@ var VdFlowchart = class {
       return;
     }
     if (action === "load" && !this.readonly) {
-      this.load(this.jsonTextarea.value);
+      try {
+        this.load(this.jsonTextarea.value);
+        this.jsonStatus.textContent = "";
+      } catch (error) {
+        this.jsonStatus.textContent = error.message;
+      }
     }
   }
   handleSelectionFieldInput(event) {
@@ -1571,10 +1721,31 @@ var VdFlowchart = class {
     }
   }
   handleKeyDown(event) {
-    if (this.readonly) return;
     if (event.target && (event.target.tagName === "INPUT" || event.target.tagName === "TEXTAREA" || event.target.tagName === "SELECT")) {
       return;
     }
+    if (event.target === this.canvasEl) {
+      const nodes = this.documentData.nodes;
+      const index = nodes.findIndex((node) => node.id === this.selection?.id);
+      let next = -1;
+      if (event.key === "ArrowDown" || event.key === "ArrowRight")
+        next = (index + 1) % nodes.length;
+      if (event.key === "ArrowUp" || event.key === "ArrowLeft")
+        next = index < 0 ? nodes.length - 1 : (index - 1 + nodes.length) % nodes.length;
+      if (event.key === "Home") next = 0;
+      if (event.key === "End") next = nodes.length - 1;
+      if (nodes[next]) {
+        event.preventDefault();
+        this.selectNode(nodes[next].id);
+        return;
+      }
+      if (event.key === "Enter" && !this.readonly && this.selection?.kind === "node") {
+        event.preventDefault();
+        this.startTextEdit(this.selection.id);
+        return;
+      }
+    }
+    if (this.readonly) return;
     if (event.key === "Escape" && this.activeTool) {
       event.preventDefault();
       this.setActiveTool(null);
@@ -1865,7 +2036,7 @@ var VdFlowchart = class {
         node.x = nextX;
         node.y = nextY;
         this.interaction.moved = true;
-        this.render({ inspector: false, json: false });
+        this.renderDraggedNode(node);
       }
       return;
     }
@@ -2240,11 +2411,13 @@ var VdFlowchart = class {
       if (event.key === "Escape") {
         event.preventDefault();
         this.stopTextEdit({ commit: false });
+        this.canvasEl.focus();
         return;
       }
       if (event.key === "Enter" && (event.ctrlKey || event.metaKey)) {
         event.preventDefault();
         this.stopTextEdit({ commit: true });
+        this.canvasEl.focus();
       }
     });
     textarea.addEventListener("blur", () => {
@@ -2318,6 +2491,7 @@ var VdFlowchart = class {
     if (shouldRenderScene) this.renderScene();
     if (shouldRenderInspector) this.renderSelectionPanel();
     if (shouldRenderJson) this.syncJsonTextarea();
+    if (shouldRenderInspector) this.renderGraphOutline();
     this.updateToolbarLabel();
     this.updatePaletteState();
     this.positionTextEditor();
@@ -2333,15 +2507,28 @@ var VdFlowchart = class {
     clearChildren(this.nodesLayer);
     clearChildren(this.overlayLayer);
     const nodeMap = new Map(this.documentData.nodes.map((node) => [node.id, node]));
+    this.sceneNodeMap = nodeMap;
+    this.nodeElements = /* @__PURE__ */ new Map();
+    this.edgeElements = /* @__PURE__ */ new Map();
+    this.incidentEdges = /* @__PURE__ */ new Map();
     this.documentData.edges.forEach((edge) => {
       const edgeElement = this.renderEdge(edge, nodeMap);
-      if (edgeElement) this.edgesLayer.appendChild(edgeElement);
+      if (edgeElement) {
+        this.edgesLayer.appendChild(edgeElement);
+        this.edgeElements.set(edge.id, edgeElement);
+        for (const id of /* @__PURE__ */ new Set([edge.from.nodeId, edge.to.nodeId])) {
+          if (!this.incidentEdges.has(id)) this.incidentEdges.set(id, []);
+          this.incidentEdges.get(id).push(edge);
+        }
+      }
     });
     if (this.interaction?.kind === "connect" || this.interaction?.kind === "reconnect") {
       this.previewLayer.appendChild(this.renderPreviewEdge(this.interaction));
     }
     this.documentData.nodes.forEach((node) => {
-      this.nodesLayer.appendChild(this.renderNode(node));
+      const element = this.renderNode(node);
+      this.nodesLayer.appendChild(element);
+      this.nodeElements.set(node.id, element);
     });
     if (this.reconnectEdgeId && !this.readonly) {
       const reconnectEdge = this.findEdge(this.reconnectEdgeId);
@@ -2357,6 +2544,25 @@ var VdFlowchart = class {
     }
     this.syncConnectingState();
   }
+  // Drag frames change one translation and its connected paths. Keep unrelated
+  // SVG elements intact; the release event still refreshes inspector/history.
+  renderDraggedNode(node) {
+    const element = this.nodeElements?.get(node.id);
+    if (!element) {
+      this.render({ inspector: false, json: false });
+      return;
+    }
+    element.setAttribute("transform", `translate(${formatNumber(node.x)} ${formatNumber(node.y)})`);
+    element.classList.add("is-dragging");
+    for (const edge of this.incidentEdges.get(node.id) || []) {
+      const previous = this.edgeElements.get(edge.id);
+      const next = this.renderEdge(edge, this.sceneNodeMap);
+      if (previous && next) {
+        previous.replaceWith(next);
+        this.edgeElements.set(edge.id, next);
+      }
+    }
+  }
   applyEdgeMarkers(pathElement, edge) {
     if (edge.startMarker && edge.startMarker !== "none") {
       pathElement.setAttribute(
@@ -3371,20 +3577,69 @@ var VdFlowchart = class {
     this.emitChange("clear");
     return this;
   }
+  updateOptions(options = {}) {
+    if (this.destroyed) return this;
+    if ("readonly" in options) {
+      if (options.readonly && !this.readonly) {
+        this.stopTextEdit({ commit: true });
+        this.interaction = null;
+        this.activeTool = null;
+        this.reconnectEdgeId = null;
+      }
+      this.readonly = Boolean(options.readonly);
+      this.root.classList.toggle("vd-flowchart-readonly", this.readonly);
+      this.arrangeSelect.disabled = this.readonly;
+      this.clearButton.disabled = this.readonly;
+      this.loadJsonButton.disabled = this.readonly;
+    }
+    if ("gridSize" in options) {
+      this.gridSize = clamp(toFiniteNumber(options.gridSize, DEFAULT_GRID_SIZE), 12, 64);
+      const pattern = this.svg.querySelector("pattern");
+      pattern.setAttribute("width", this.gridSize);
+      pattern.setAttribute("height", this.gridSize);
+      pattern.querySelector("path").setAttribute("d", `M ${this.gridSize} 0 L 0 0 0 ${this.gridSize}`);
+    }
+    if ("autoFit" in options) this.autoFit = Boolean(options.autoFit);
+    if ("history" in options && options.history !== false !== this.historyEnabled) {
+      this.historyEnabled = options.history !== false;
+      this.history = [];
+      this.historyIndex = -1;
+      this.seedHistory();
+    }
+    if ("historyLimit" in options) {
+      this.historyLimit = Math.max(1, Math.floor(toFiniteNumber(options.historyLimit, 100)));
+      if (this.history.length > this.historyLimit) {
+        const start = Math.max(0, this.historyIndex - this.historyLimit + 1);
+        this.history = this.history.slice(start, start + this.historyLimit);
+        this.historyIndex -= start;
+      }
+    }
+    this.render();
+    this.updateHistoryButtons();
+    return this;
+  }
   load(data, options = {}) {
+    const documentData = normalizeDocument(data);
+    if (options.silent && JSON.stringify(documentData) === JSON.stringify(this.documentData)) {
+      return this;
+    }
     this.stopTextEdit({ commit: false });
     this.activeTool = null;
     this.reconnectEdgeId = null;
     const previousSelection = this.selection;
-    this.documentData = normalizeDocument(data);
+    this.documentData = documentData;
     this.selection = this.resolvePreservedSelection(previousSelection, options.preserveSelection);
     this.render();
-    this.emitChange("load");
+    if (options.silent) {
+      if (this.historyEnabled) this.recordHistory("load");
+    } else {
+      this.emitChange("load");
+    }
     return this;
   }
   toJSON() {
     return deepClone({
-      version: VD_FLOWCHART_VERSION,
+      version: FLOWCHART_DOCUMENT_VERSION,
       viewport: this.documentData.viewport,
       nodes: this.documentData.nodes,
       edges: this.documentData.edges
@@ -3398,6 +3653,10 @@ var VdFlowchart = class {
     this.resizeObserver?.disconnect();
     this.resizeObserver = null;
     this.unbindEvents();
+    this.sceneNodeMap?.clear();
+    this.nodeElements?.clear();
+    this.edgeElements?.clear();
+    this.incidentEdges?.clear();
     this.element.innerHTML = "";
     this.element.classList.remove("vd-flowchart-host");
   }
@@ -3449,7 +3708,7 @@ var VdFlowchart2 = (0, import_vue.defineComponent)({
       () => props.data,
       (next) => {
         if (instance && typeof instance.load === "function") {
-          instance.load(next, { preserveSelection: props.preserveSelection });
+          instance.load(next, { preserveSelection: props.preserveSelection, silent: true });
         }
       },
       { deep: true }
@@ -3458,8 +3717,13 @@ var VdFlowchart2 = (0, import_vue.defineComponent)({
       () => [props.readonly, props.gridSize, props.autoFit, props.history, props.historyLimit],
       () => {
         if (!instance) return;
-        instance.destroy();
-        create();
+        instance.updateOptions({
+          readonly: props.readonly,
+          gridSize: props.gridSize,
+          autoFit: props.autoFit,
+          history: props.history,
+          historyLimit: props.historyLimit
+        });
       }
     );
     (0, import_vue.onBeforeUnmount)(() => {