@bpmnkit/editor 0.0.35 → 0.2.0

package/dist/dock.js

@@ -1,131 +1,109 @@
+import { injectChromeStyles } from "./chrome.js";
 const DOCK_STYLE_ID = "bpmnkit-side-dock-styles-v1";
 const STORAGE_KEY_WIDTH = "bpmnkit-side-dock-width";
 const STORAGE_KEY_COLLAPSED = "bpmnkit-side-dock-collapsed";
 const MIN_WIDTH = 280;
 const MAX_WIDTH = 700;
-const DEFAULT_WIDTH = 360;
+const DEFAULT_WIDTH = 340;
 const DOCK_CSS = `
-/* ── Side Dock ──────────────────────────────────────────────────────────── */
-.bpmnkit-side-dock__tab:disabled { opacity: 0.3; cursor: default; }
+/* ── Side dock ───────────────────────────────────────────────────────────
+   The properties panel, in the bpmnkit.com design system: flat, square,
+   hairline-bounded, mono uppercase labels. Grounds follow the HUD theme
+   variables declared in css.ts, so the two read as one piece of chrome.
+   ──────────────────────────────────────────────────────────────────────── */
 .bpmnkit-side-dock {
   position: fixed; right: 0; top: 36px; bottom: 0;
   z-index: 9999; display: flex; flex-direction: column;
-  background: rgba(18, 18, 26, 0.98);
-  border-left: 1px solid rgba(255,255,255,0.1);
-  box-shadow: -8px 0 40px rgba(0,0,0,0.6);
-  font-family: system-ui, -apple-system, sans-serif;
+  background: var(--bpmnkit-chrome-ground, #ffffff);
+  border-left: 1px solid var(--bpmnkit-chrome-line, rgba(255, 255, 255, 0.14));
+  font-family: var(--bpmnkit-ds-font-sans, system-ui, -apple-system, sans-serif);
   transition: width 0.22s ease;
 }
-/* Pill handle — sticks out from the left edge; always visible + clickable */
+/* Square handle — sticks out from the left edge; always visible + clickable */
 .bpmnkit-side-dock__collapse-handle {
   position: absolute; left: -20px; top: 50%; transform: translateY(-50%);
   width: 20px; height: 52px;
-  background: rgba(18, 18, 26, 0.98);
-  border: 1px solid rgba(255,255,255,0.1); border-right: none;
-  border-radius: 8px 0 0 8px;
+  background: var(--bpmnkit-chrome-ground, #ffffff);
+  border: 1px solid var(--bpmnkit-chrome-line, rgba(255, 255, 255, 0.14)); border-right: none;
   display: flex; align-items: center; justify-content: center;
   cursor: pointer; z-index: 1;
-  color: rgba(255,255,255,0.45); font-size: 14px; line-height: 1;
-  transition: color 0.1s, background 0.1s;
+  color: var(--bpmnkit-chrome-ink-4, #9aa1aa);
+  font-family: var(--bpmnkit-ds-font-mono, ui-monospace, monospace);
+  font-size: 13px; line-height: 1;
+  font-variant-emoji: text;
   user-select: none;
 }
-.bpmnkit-side-dock__collapse-handle:hover { color: #fff; background: rgba(40,40,60,0.99); }
+.bpmnkit-side-dock__collapse-handle:hover { color: var(--bpmnkit-chrome-ink, #f4f5f7); background: var(--bpmnkit-chrome-hover, rgba(255,255,255,0.07)); }
 .bpmnkit-side-dock__resize-handle {
   position: absolute; left: 0; top: 0; bottom: 0;
   width: 5px; cursor: ew-resize; z-index: 2;
 }
-.bpmnkit-side-dock__resize-handle:hover { background: rgba(76,142,247,0.35); }
+.bpmnkit-side-dock__resize-handle:hover { background: var(--bpmnkit-chrome-accent, #c9755c); }
+
+/* ── Tabs — equal-width row, the underline sits on the row's own rule ── */
 .bpmnkit-side-dock__tab-strip {
-  display: flex; align-items: center; height: 38px; flex-shrink: 0;
-  border-bottom: 1px solid rgba(255,255,255,0.08);
+  display: flex; align-items: stretch; height: 34px; flex-shrink: 0;
+  border-bottom: 1px solid var(--bpmnkit-chrome-line, rgba(255, 255, 255, 0.14));
+  overflow-x: auto; scrollbar-width: none;
 }
+.bpmnkit-side-dock__tab-strip::-webkit-scrollbar { display: none; }
+/* Equal-width while the labels fit; the strip scrolls rather than clipping them. */
 .bpmnkit-side-dock__tab {
-  padding: 0 16px; height: 100%; background: none; border: none;
-  border-bottom: 2px solid transparent; color: rgba(255,255,255,0.4);
-  cursor: pointer; font-size: 12px; font-weight: 500; white-space: nowrap;
-  transition: color 0.1s, border-color 0.1s;
-  font-family: system-ui, -apple-system, sans-serif;
+  flex: 1 0 auto;
+  padding: 0 10px; height: 100%; background: none; border: none;
+  border-bottom: 2px solid transparent; color: var(--bpmnkit-chrome-ink-4, #9aa1aa);
+  cursor: pointer; white-space: nowrap;
+  font-family: var(--bpmnkit-ds-font-mono, ui-monospace, monospace);
+  font-size: var(--bpmnkit-ds-t-mono-micro, 10.5px);
+  letter-spacing: 0.08em; text-transform: uppercase;
+}
+.bpmnkit-side-dock__tab:hover { color: var(--bpmnkit-chrome-ink-2, #c8ccd2); }
+.bpmnkit-side-dock__tab.active {
+  color: var(--bpmnkit-chrome-ink, #f4f5f7);
+  border-bottom-color: var(--bpmnkit-chrome-accent, #c9755c);
+  margin-bottom: -1px;
 }
-.bpmnkit-side-dock__tab:hover { color: rgba(255,255,255,0.75); }
-.bpmnkit-side-dock__tab.active { color: #4c8ef7; border-bottom-color: #4c8ef7; }
+.bpmnkit-side-dock__tab:disabled { opacity: 0.3; cursor: default; }
 .bpmnkit-side-dock__pane {
   flex: 1; display: flex; flex-direction: column; overflow: hidden; min-height: 0;
 }
 .bpmnkit-side-dock__pane--hidden { display: none; }
-/* Empty state — info widget + hint, shown when no element is selected */
+
+/* ── Empty state — info rows + hint, shown when nothing is selected ── */
 .bpmnkit-side-dock__empty {
   flex: 1; display: flex; flex-direction: column;
-  overflow-y: auto; padding: 14px 16px;
-  gap: 0;
+  overflow-y: auto; padding: 0 20px;
 }
 .bpmnkit-side-dock__info-row {
   display: flex; flex-direction: column;
-  padding: 10px 0;
-  border-bottom: 1px solid rgba(255,255,255,0.06);
-  gap: 3px;
+  padding: 14px 0;
+  border-bottom: 1px solid var(--bpmnkit-chrome-line-soft, rgba(255, 255, 255, 0.08));
+  gap: 7px;
 }
 .bpmnkit-side-dock__info-label {
-  font-size: 10px; font-weight: 700; text-transform: uppercase;
-  letter-spacing: 0.08em; color: rgba(255,255,255,0.3);
+  font-family: var(--bpmnkit-ds-font-mono, ui-monospace, monospace);
+  font-size: var(--bpmnkit-ds-t-mono-micro, 10.5px); letter-spacing: 0.12em;
+  text-transform: uppercase; color: var(--bpmnkit-chrome-ink-4, #9aa1aa);
 }
 .bpmnkit-side-dock__info-value {
-  font-size: 13px; color: rgba(255,255,255,0.75); word-break: break-word;
+  font-family: var(--bpmnkit-ds-font-mono, ui-monospace, monospace);
+  font-size: 12.5px; color: var(--bpmnkit-chrome-ink-2, #c8ccd2); word-break: break-word;
 }
+/* A sentence, not a label — --ink-4 does not clear 4.5:1 on a light ground. */
 .bpmnkit-side-dock__empty-hint {
-  font-size: 12px; color: rgba(255,255,255,0.25);
-  text-align: center; padding: 20px 0;
+  font-family: var(--bpmnkit-ds-font-mono, ui-monospace, monospace);
+  font-size: var(--bpmnkit-ds-t-mono-label, 11.5px); letter-spacing: 0.04em;
+  color: var(--bpmnkit-chrome-ink-2, #c8ccd2);
+  padding: 24px 0;
 }
-/* Collapsed state — only the pill handle remains visible */
+/* Collapsed state — only the handle remains visible */
 .bpmnkit-side-dock--collapsed .bpmnkit-side-dock__tab-strip,
 .bpmnkit-side-dock--collapsed .bpmnkit-side-dock__pane { display: none; }
 /* Push watermark left of the dock using a CSS variable updated by JS */
 .bpmnkit-watermark { right: calc(var(--bpmnkit-dock-width, 0px) + 8px) !important; }
-/* Light theme */
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock {
-  background: rgba(248,248,252,0.99); border-left-color: rgba(0,0,0,0.08);
-  box-shadow: -8px 0 40px rgba(0,0,0,0.12);
-}
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__collapse-handle {
-  background: rgba(248,248,252,0.99); border-color: rgba(0,0,0,0.08); color: rgba(0,0,0,0.4);
-}
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__collapse-handle:hover {
-  background: rgba(235,235,242,0.99); color: rgba(0,0,0,0.9);
-}
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__tab-strip { border-bottom-color: rgba(0,0,0,0.07); }
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__tab { color: rgba(0,0,0,0.4); }
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__tab:hover { color: rgba(0,0,0,0.7); }
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__tab.active { color: #1a56db; border-bottom-color: #1a56db; }
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__resize-handle:hover { background: rgba(26,86,219,0.2); }
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__info-label { color: rgba(0,0,0,0.3); }
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__info-value { color: rgba(0,0,0,0.75); }
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__info-row { border-bottom-color: rgba(0,0,0,0.06); }
-[data-bpmnkit-hud-theme="light"] .bpmnkit-side-dock__empty-hint { color: rgba(0,0,0,0.25); }
-/* Neon theme */
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock {
-  background: oklch(6% 0.04 280);
-  border-left: 1px solid oklch(65% 0.28 280 / 0.35);
-  box-shadow: -8px 0 40px oklch(0% 0 0 / 0.8), -1px 0 20px oklch(65% 0.28 280 / 0.12);
-}
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__collapse-handle {
-  background: oklch(6% 0.04 280);
-  border-color: oklch(65% 0.28 280 / 0.35);
-  color: oklch(65% 0.28 280 / 0.6);
-}
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__collapse-handle:hover {
-  background: oklch(12% 0.04 270 / 0.99);
-  color: oklch(73% 0.16 280);
-}
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__tab-strip { border-bottom-color: oklch(65% 0.28 280 / 0.25); }
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__tab { color: oklch(50% 0.1 280); }
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__tab:hover { color: oklch(73% 0.16 280); }
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__tab.active { color: oklch(72% 0.18 185); border-bottom-color: oklch(72% 0.18 185); }
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__resize-handle:hover { background: oklch(65% 0.28 280 / 0.25); }
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__info-label { color: oklch(50% 0.06 280); }
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__info-value { color: oklch(73% 0.16 280); }
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__info-row { border-bottom-color: oklch(65% 0.28 280 / 0.1); }
-[data-bpmnkit-hud-theme="neon"] .bpmnkit-side-dock__empty-hint { color: oklch(45% 0.08 280); }
 `;
 function injectDockStyles() {
+    injectChromeStyles();
     if (document.getElementById(DOCK_STYLE_ID))
         return;
     const style = document.createElement("style");

package/dist/editor.d.ts

@@ -1,5 +1,5 @@
 import { OverlayManager } from "@bpmnkit/canvas";
-import type { Theme } from "@bpmnkit/canvas";
+import type { Theme, ViewportState } from "@bpmnkit/canvas";
 import type { BpmnDefinitions, DiColor } from "@bpmnkit/core";
 import type { Translate } from "./i18n.js";
 import type { CreateShapeType, EditorEvents, EditorOptions, LabelPosition, Tool } from "./types.js";
@@ -94,10 +94,30 @@ export declare class BpmnEditor {
     }>;
     undo(): void;
     redo(): void;
+    /**
+     * Moves to a document already on the command stack — an undo or a redo.
+     *
+     * It describes itself as a `snapshot` op, which is the only honest option: a
+     * step back through the stack is a state change like any other, and a
+     * listener relaying edits elsewhere that never heard about it would be
+     * silently wrong from then on. There is no smaller description available —
+     * the inverse of an op is not something the stack records.
+     */
+    private _stepTo;
     canUndo(): boolean;
     canRedo(): boolean;
     getDefinitions(): BpmnDefinitions | null;
     applyChange(fn: (defs: BpmnDefinitions) => BpmnDefinitions): void;
+    /**
+     * The raw pan and zoom, for restoring it later.
+     *
+     * Paired with {@link setViewport} so a viewer can hand its view to an editor
+     * taking its place — without it the swap re-fits, and the diagram jumps under
+     * the cursor at the moment someone starts editing.
+     */
+    getViewport(): ViewportState;
+    /** Restores a viewport captured by {@link getViewport}. */
+    setViewport(state: Partial<ViewportState>): void;
     fitView(padding?: number): void;
     /** The host element that receives the `data-theme` attribute. */
     get container(): HTMLElement;
@@ -124,7 +144,15 @@ export declare class BpmnEditor {
     private _getDuplicateIds;
     private _setDuplicateIdWarning;
     private _renderDefs;
-    private _executeCommand;
+    /**
+     * Performs an edit: the editor's single mutation path.
+     *
+     * Every change goes through {@link applyOp}, including the ones typed right
+     * here — see `ops.ts` for why local edits are not allowed their own shortcut.
+     * Returns the ids the op brought into being, which a caller may need for a
+     * follow-up (starting a label edit on a fresh annotation, say).
+     */
+    private _executeOp;
     /** Label of the change `undo()` would revert (for HUD tooltips), or null. */
     getUndoLabel(): string | null;
     /** Label of the change `redo()` would re-apply (for HUD tooltips), or null. */

package/dist/editor.js

@@ -1,11 +1,13 @@
 import { KeyboardHandler, OverlayManager, ViewportController, computeDiagramBounds, createDefs, createGrid, injectStyles, render, } from "@bpmnkit/canvas";
-import { Bpmn, applyAutoLayout } from "@bpmnkit/core";
+import { Bpmn } from "@bpmnkit/core";
 import { CommandStack } from "./command-stack.js";
 import { injectEditorStyles } from "./css.js";
 import { closestPort, computeWaypoints, computeWaypointsAvoiding, computeWaypointsWithPorts, diagramToScreen, labelBoundsForPosition, portFromWaypoint, screenToDiagram, } from "./geometry.js";
 import { defaultTranslate } from "./i18n.js";
+import { newIdSeed } from "./id.js";
 import { LabelEditor } from "./label-editor.js";
-import { changeElementType as changeElementTypeFn, copyElements, createAnnotation, createAnnotationWithLink, createBoundaryEvent, createConnection, createEmptyDefinitions, createShape, deleteElements, insertEdgeWaypoint, insertShapeOnEdge, moveEdgeSegment, moveEdgeWaypoint, moveShapes, pasteElements, removeCollinearWaypoints, resizeShape, updateEdgeEndpoint, updateLabel, updateLabelPosition, updateShapeColor, } from "./modeling.js";
+import { copyElements, createEmptyDefinitions, insertEdgeWaypoint, moveEdgeSegment, moveEdgeWaypoint, } from "./modeling.js";
+import { applyOp } from "./ops.js";
 import { OverlayRenderer } from "./overlay.js";
 import { canAttach, canConnect, canMorph, canResize } from "./rules.js";
 import { EditorStateMachine } from "./state-machine.js";
@@ -295,8 +297,10 @@ export class BpmnEditor {
         injectEditorStyles();
         this._id = String(_instanceCounter++);
         this._t = options.translate ?? defaultTranslate;
-        // Resolve initial theme — localStorage overrides the options.theme when persistTheme is on
-        let initialTheme = options.theme ?? "neon";
+        // Resolve initial theme — localStorage overrides the options.theme when persistTheme is on.
+        // The shell's default is the design system's light `--canvas` ground; `neon` stays a
+        // white-label theme a host opts into.
+        let initialTheme = options.theme ?? "light";
         if (options.persistTheme) {
             try {
                 const stored = localStorage.getItem("bpmnkit-theme");
@@ -374,7 +378,7 @@ export class BpmnEditor {
             previewResize: (bounds) => this._overlay.setResizePreview(bounds),
             commitResize: (id, bounds) => {
                 this._overlay.setResizePreview(null);
-                this._executeCommand((d) => resizeShape(d, id, bounds), "Resize");
+                this._executeOp({ kind: "resize", id, bounds }, { label: "Resize" });
             },
             previewConnect: (ghostEnd, targetId) => {
                 const src = this._connectSourceBounds();
@@ -399,7 +403,7 @@ export class BpmnEditor {
             startLabelEdit: (id) => this._startLabelEdit(id),
             setHovered: (id) => this._overlay.setHovered(id, this._shapes),
             executeDelete: (ids) => {
-                this._executeCommand((d) => deleteElements(d, ids), "Delete");
+                this._executeOp({ kind: "delete", ids }, { label: "Delete" });
                 this._setSelection([]);
             },
             executeCopy: () => this._doCopy(),
@@ -429,7 +433,7 @@ export class BpmnEditor {
                 this._overlay.setEndpointDragGhost(null);
                 this._overlay.setAlignmentGuides([]);
                 const snap = this._snapWaypoint(pt);
-                this._executeCommand((d) => removeCollinearWaypoints(insertEdgeWaypoint(d, edgeId, segIdx, snap.pt), edgeId), "Add waypoint");
+                this._executeOp({ kind: "insertWaypoint", edgeId, segIdx, point: snap.pt }, { label: "Add waypoint" });
             },
             cancelWaypointInsert: () => {
                 this._overlay.setEndpointDragGhost(null);
@@ -448,7 +452,7 @@ export class BpmnEditor {
                 this._overlay.setEndpointDragGhost(null);
                 this._overlay.setAlignmentGuides([]);
                 const snap = this._snapWaypoint(pt);
-                this._executeCommand((d) => removeCollinearWaypoints(moveEdgeWaypoint(d, edgeId, wpIdx, snap.pt), edgeId), "Move waypoint");
+                this._executeOp({ kind: "moveWaypoint", edgeId, wpIdx, point: snap.pt }, { label: "Move waypoint" });
             },
             cancelWaypointMove: () => {
                 this._overlay.setEndpointDragGhost(null);
@@ -463,7 +467,7 @@ export class BpmnEditor {
             },
             commitSegmentMove: (edgeId, segIdx, isHoriz, delta) => {
                 this._overlay.setEndpointDragGhost(null);
-                this._executeCommand((d) => removeCollinearWaypoints(moveEdgeSegment(d, edgeId, segIdx, isHoriz, delta), edgeId), "Move segment");
+                this._executeOp({ kind: "moveSegment", edgeId, segIdx, isHoriz, delta }, { label: "Move segment" });
             },
             cancelSegmentMove: () => {
                 this._overlay.setEndpointDragGhost(null);
@@ -489,7 +493,7 @@ export class BpmnEditor {
         this._stateMachine = new EditorStateMachine(callbacks);
         // ── Label editor ─────────────────────────────────────────────
         this._labelEditor = new LabelEditor(this._host, (id, text) => {
-            this._executeCommand((d) => updateLabel(d, id, text), "Rename", `label:${id}`);
+            this._executeOp({ kind: "rename", id, name: text }, { label: "Rename", coalesceKey: `label:${id}` });
             this._stateMachine.setMode({ mode: "select", sub: { name: "idle", hoveredId: null } });
         }, () => {
             this._stateMachine.setMode({ mode: "select", sub: { name: "idle", hoveredId: null } });
@@ -550,7 +554,7 @@ export class BpmnEditor {
      * The operation is undoable.
      */
     autoLayout() {
-        this._executeCommand(applyAutoLayout, "Auto-layout");
+        this._executeOp({ kind: "autoLayout" }, { label: "Auto-layout" });
         this.fitView();
     }
     loadDefinitions(defs) {
@@ -623,7 +627,7 @@ export class BpmnEditor {
         if (this._selectedIds.length === 0)
             return;
         const ids = [...this._selectedIds];
-        this._executeCommand((d) => deleteElements(d, ids), "Delete");
+        this._executeOp({ kind: "delete", ids }, { label: "Delete" });
         this._setSelection([]);
     }
     /** Bounds of the currently-selected shapes (edges have none, and are skipped). */
@@ -676,7 +680,7 @@ export class BpmnEditor {
                 moves.push({ id: b.id, dx, dy });
         }
         if (moves.length > 0)
-            this._executeCommand((d) => moveShapes(d, moves), "Align");
+            this._executeOp({ kind: "move", moves }, { label: "Align" });
     }
     /**
      * Distributes the selected shapes so the gaps between them are equal along
@@ -711,7 +715,7 @@ export class BpmnEditor {
             cursor += size(b) + gap;
         }
         if (moves.length > 0)
-            this._executeCommand((d) => moveShapes(d, moves), "Distribute");
+            this._executeOp({ kind: "move", moves }, { label: "Distribute" });
     }
     /**
      * Searches the model (recursively, including sub-process children) for
@@ -753,17 +757,27 @@ export class BpmnEditor {
     }
     undo() {
         const prev = this._commandStack.undo();
-        if (prev) {
-            this._renderDefs(prev);
-            this._emit("diagram:change", prev);
-        }
+        if (prev)
+            this._stepTo(prev);
     }
     redo() {
         const next = this._commandStack.redo();
-        if (next) {
-            this._renderDefs(next);
-            this._emit("diagram:change", next);
-        }
+        if (next)
+            this._stepTo(next);
+    }
+    /**
+     * Moves to a document already on the command stack — an undo or a redo.
+     *
+     * It describes itself as a `snapshot` op, which is the only honest option: a
+     * step back through the stack is a state change like any other, and a
+     * listener relaying edits elsewhere that never heard about it would be
+     * silently wrong from then on. There is no smaller description available —
+     * the inverse of an op is not something the stack records.
+     */
+    _stepTo(defs) {
+        this._renderDefs(defs);
+        this._emit("diagram:change", defs);
+        this._emit("diagram:op", { kind: "snapshot", defs }, defs);
     }
     canUndo() {
         return this._commandStack.canUndo();
@@ -775,7 +789,23 @@ export class BpmnEditor {
         return this._defs;
     }
     applyChange(fn) {
-        this._executeCommand(fn);
+        if (this._readOnly || !this._defs)
+            return;
+        this._executeOp({ kind: "snapshot", defs: fn(this._defs) });
+    }
+    /**
+     * The raw pan and zoom, for restoring it later.
+     *
+     * Paired with {@link setViewport} so a viewer can hand its view to an editor
+     * taking its place — without it the swap re-fits, and the diagram jumps under
+     * the cursor at the moment someone starts editing.
+     */
+    getViewport() {
+        return this._viewport.state;
+    }
+    /** Restores a viewport captured by {@link getViewport}. */
+    setViewport(state) {
+        this._viewport.set(state);
     }
     fitView(padding = 40) {
         if (!this._defs)
@@ -986,15 +1016,31 @@ export class BpmnEditor {
         }
         this._emit("diagram:load", defs, { missingShapes: [], missingEdges: [] });
     }
-    _executeCommand(fn, label = "", coalesceKey) {
+    /**
+     * Performs an edit: the editor's single mutation path.
+     *
+     * Every change goes through {@link applyOp}, including the ones typed right
+     * here — see `ops.ts` for why local edits are not allowed their own shortcut.
+     * Returns the ids the op brought into being, which a caller may need for a
+     * follow-up (starting a label edit on a fresh annotation, say).
+     */
+    _executeOp(op, options = {}) {
         if (this._readOnly || !this._defs)
-            return;
-        const newDefs = fn(this._defs);
-        this._commandStack.push(newDefs, label, coalesceKey);
-        this._renderDefs(newDefs);
-        if (label)
-            this._announce(this._t(label));
-        this._emit("diagram:change", newDefs);
+            return [];
+        const { defs, created } = applyOp(this._defs, op);
+        // Selection is set before the render so the new element comes up selected.
+        const select = options.select === "all" ? created : options.select === "first" ? created.slice(0, 1) : null;
+        if (select)
+            this._selectedIds = select;
+        this._commandStack.push(defs, options.label ?? "", options.coalesceKey);
+        this._renderDefs(defs);
+        if (options.label)
+            this._announce(this._t(options.label));
+        this._emit("diagram:change", defs);
+        this._emit("diagram:op", op, defs);
+        if (select)
+            this._emit("editor:select", select);
+        return created;
     }
     /** Label of the change `undo()` would revert (for HUD tooltips), or null. */
     getUndoLabel() {
@@ -1101,10 +1147,10 @@ export class BpmnEditor {
         const moves = this._selectedIds.map((id) => ({ id, dx: snap.dx, dy: snap.dy }));
         const shapeId = this._selectedIds.length === 1 ? this._selectedIds[0] : undefined;
         if (edgeDropId && shapeId) {
-            this._executeCommand((d) => insertShapeOnEdge(moveShapes(d, moves), edgeDropId, shapeId), "Insert on flow");
+            this._executeOp({ kind: "move", moves, onEdge: { edgeId: edgeDropId, shapeId } }, { label: "Insert on flow" });
         }
         else {
-            this._executeCommand((d) => moveShapes(d, moves), "Move");
+            this._executeOp({ kind: "move", moves }, { label: "Move" });
         }
         if (this._isDragging) {
             this._isDragging = false;
@@ -1179,7 +1225,7 @@ export class BpmnEditor {
             }
         }
         if (moves.length > 0) {
-            this._executeCommand((d) => moveShapes(d, moves), "Move");
+            this._executeOp({ kind: "move", moves }, { label: "Move" });
         }
     }
     _cancelSpace() {
@@ -1201,13 +1247,9 @@ export class BpmnEditor {
             return;
         const bounds = defaultBounds(type, actualCenter.x, actualCenter.y);
         if (type === "textAnnotation") {
-            const result = createAnnotation(this._defs, bounds);
-            this._selectedIds = [result.id];
-            this._commandStack.push(result.defs);
-            this._renderDefs(result.defs);
-            this._emit("diagram:change", result.defs);
-            this._emit("editor:select", [result.id]);
-            this._startLabelEdit(result.id);
+            const [id] = this._executeOp({ kind: "createAnnotation", bounds, seed: newIdSeed() }, { select: "first" });
+            if (id)
+                this._startLabelEdit(id);
             return;
         }
         // If hovering over an activity, create a boundary event
@@ -1221,24 +1263,23 @@ export class BpmnEditor {
                 const eventBounds = snapToBoundary(actualCenter, hostBounds, 18);
                 // Map palette type to event definition type
                 const eventDefType = intermediateEventDefType(type);
-                const result = createBoundaryEvent(this._defs, boundaryHostId, eventDefType, eventBounds);
-                this._selectedIds = [result.id];
-                this._commandStack.push(result.defs);
-                this._renderDefs(result.defs);
-                this._emit("diagram:change", result.defs);
-                this._emit("editor:select", [result.id]);
+                this._executeOp({
+                    kind: "createBoundaryEvent",
+                    hostId: boundaryHostId,
+                    eventDefType,
+                    bounds: eventBounds,
+                    seed: newIdSeed(),
+                }, { select: "first" });
                 return;
             }
         }
-        const result = createShape(this._defs, type, bounds);
-        this._selectedIds = [result.id];
-        const finalDefs = pendingEdgeDrop
-            ? insertShapeOnEdge(result.defs, pendingEdgeDrop, result.id)
-            : result.defs;
-        this._commandStack.push(finalDefs);
-        this._renderDefs(finalDefs);
-        this._emit("diagram:change", finalDefs);
-        this._emit("editor:select", [result.id]);
+        this._executeOp({
+            kind: "createShape",
+            type,
+            bounds,
+            onEdge: pendingEdgeDrop ?? undefined,
+            seed: newIdSeed(),
+        }, { select: "first" });
     }
     _doConnect(srcId, tgtId) {
         const srcShape = this._shapeById.get(srcId);
@@ -1253,7 +1294,7 @@ export class BpmnEditor {
             .filter((s) => s.id !== srcId && s.id !== tgtId)
             .map((s) => s.shape.bounds);
         const waypoints = computeWaypointsAvoiding(srcShape.shape.bounds, tgtShape.shape.bounds, obstacles);
-        this._executeCommand((d) => createConnection(d, srcId, tgtId, waypoints).defs, "Connect");
+        this._executeOp({ kind: "createConnection", sourceId: srcId, targetId: tgtId, waypoints, seed: newIdSeed() }, { label: "Connect" });
     }
     _doCopy() {
         if (!this._defs || this._selectedIds.length === 0)
@@ -1263,20 +1304,14 @@ export class BpmnEditor {
     _doPaste() {
         if (!this._clipboard)
             return;
-        const base = this._defs ?? createEmptyDefinitions();
-        const result = pasteElements(base, this._clipboard, 20, 20);
-        this._selectedIds = result.topLevelIds;
-        this._commandStack.push(result.defs, "Paste");
-        this._renderDefs(result.defs);
-        this._emit("diagram:change", result.defs);
-        this._emit("editor:select", result.topLevelIds);
+        this._executeOp({ kind: "paste", clipboard: this._clipboard, offsetX: 20, offsetY: 20, seed: newIdSeed() }, { label: "Paste", select: "all" });
     }
     _doCut() {
         if (!this._defs || this._selectedIds.length === 0)
             return;
         this._doCopy();
         const ids = [...this._selectedIds];
-        this._executeCommand((d) => deleteElements(d, ids), "Cut");
+        this._executeOp({ kind: "delete", ids }, { label: "Cut" });
         this._setSelection([]);
     }
     _startLabelEdit(id) {
@@ -1388,15 +1423,17 @@ export class BpmnEditor {
         }
         const newBounds = this._smartPlaceBounds(srcBounds, sourceId, w, h);
         const obstacles = this._shapes.filter((s) => s.id !== sourceId).map((s) => s.shape.bounds);
-        const r1 = createShape(this._defs, type, newBounds, name);
         const waypoints = computeWaypointsAvoiding(srcBounds, newBounds, obstacles);
-        const r2 = createConnection(r1.defs, sourceId, r1.id, waypoints);
-        this._selectedIds = [r1.id];
-        this._commandStack.push(r2.defs);
-        this._renderDefs(r2.defs);
-        this._emit("diagram:change", r2.defs);
-        this._emit("editor:select", [r1.id]);
-        return r1.id;
+        const [id] = this._executeOp({
+            kind: "createConnected",
+            sourceId,
+            type,
+            name,
+            bounds: newBounds,
+            waypoints,
+            seed: newIdSeed(),
+        }, { select: "first" });
+        return id ?? null;
     }
     _smartPlaceBounds(srcBounds, sourceId, w, h) {
         const GAP = 60;
@@ -1493,7 +1530,7 @@ export class BpmnEditor {
         if (!shape)
             return;
         const labelBounds = labelBoundsForPosition(shape.shape.bounds, position);
-        this._executeCommand((d) => updateLabelPosition(d, shapeId, labelBounds), "Move label");
+        this._executeOp({ kind: "labelPosition", id: shapeId, bounds: labelBounds }, { label: "Move label" });
     }
     /** Starts inline label editing for the element with the given id. */
     editLabel(id) {
@@ -1535,17 +1572,19 @@ export class BpmnEditor {
             width: annW,
             height: annH,
         };
-        const result = createAnnotationWithLink(this._defs, annBounds, sourceId, srcBounds);
-        this._selectedIds = [result.annotationId];
-        this._commandStack.push(result.defs);
-        this._renderDefs(result.defs);
-        this._emit("diagram:change", result.defs);
-        this._emit("editor:select", [result.annotationId]);
-        this._startLabelEdit(result.annotationId);
+        const [id] = this._executeOp({
+            kind: "createAnnotationFor",
+            sourceId,
+            bounds: annBounds,
+            sourceBounds: srcBounds,
+            seed: newIdSeed(),
+        }, { select: "first" });
+        if (id)
+            this._startLabelEdit(id);
     }
     /** Updates the color of a shape in the diagram. Pass `{}` to clear colors. */
     updateColor(id, color) {
-        this._executeCommand((d) => updateShapeColor(d, id, color), "Change colour", `color:${id}`);
+        this._executeOp({ kind: "color", id, color }, { label: "Change colour", coalesceKey: `color:${id}` });
     }
     // ── Private helpers ────────────────────────────────────────────────
     _setEdgeSelected(edgeId) {
@@ -1570,7 +1609,7 @@ export class BpmnEditor {
         const current = this._shapeById.get(id)?.flowElement?.type;
         if (current && !canMorph(current, newType))
             return;
-        this._executeCommand((d) => changeElementTypeFn(d, id, newType), "Change type");
+        this._executeOp({ kind: "changeType", id, type: newType }, { label: "Change type" });
     }
     _findEdgeDropTarget(dx, dy) {
         if (this._selectedIds.length !== 1)
@@ -1675,7 +1714,7 @@ export class BpmnEditor {
         const newPort = isStart
             ? closestPort(diagPoint, srcDi.bounds)
             : closestPort(diagPoint, tgtDi.bounds);
-        this._executeCommand((d) => updateEdgeEndpoint(d, edgeId, isStart, newPort), "Reconnect");
+        this._executeOp({ kind: "reconnect", edgeId, isStart, port: newPort }, { label: "Reconnect" });
     }
     _isResizable(id) {
         const shape = this._shapeById.get(id);