@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/collab/undo.js

@@ -0,0 +1,388 @@
+"use strict";
+// Wave 9 — Card 4: COLLABORATION-AWARE UNDO.
+//
+// ---------------------------------------------------------------------------
+// CTRL-Z MUST UNDO *MY* LAST EDIT, NOT THE LAST EDIT
+// ---------------------------------------------------------------------------
+//
+// If Alice moves a node and Bob presses Ctrl-Z, Bob must not undo Alice's move. It is the
+// single most infuriating bug in every home-grown multiplayer editor, and it comes from
+// the same place every time: one global history stack, shared by everyone, popped by
+// whoever pressed the key.
+//
+// Here the property is STRUCTURAL, not a filter. `OpCapture` emits ops for LOCAL edits
+// only — remote ops are applied with capture suppressed (that same three-character
+// re-entrancy guard that stops two peers ping-ponging). So an op that reaches this stack
+// is MINE BY CONSTRUCTION. There is nothing to filter out, and therefore no filter to get
+// wrong later. The test still asserts it, because a structural guarantee that nobody
+// checks is one refactor away from not being one.
+//
+// ---------------------------------------------------------------------------
+// THE HARD PART: UNDO MUST NOT RESURRECT STALE STATE
+// ---------------------------------------------------------------------------
+//
+// A naive undo restores the value it captured when the edit was made. That is wrong the
+// moment anyone else is in the document, and wrong in a way that destroys other people's
+// work:
+//
+//     Bob moves node N to (10,10).            [Bob's op]
+//     Alice moves N to (900,900).             [newer — this is what everyone now sees]
+//     Bob presses Ctrl-Z.
+//
+// Naive undo: "restore N to where it was before MY move" → N jumps back to its original
+// spot and ALICE'S MOVE IS SILENTLY DESTROYED. Bob undid his own edit and deleted hers.
+//
+// The correct answer is that BOB'S EDIT IS ALREADY GONE. Alice overwrote that register; the
+// document does not contain Bob's move any more. Undoing an edit that has no effect must
+// have no effect. So:
+//
+//     UNDO OF OP `O` ON REGISTER `R` IS SKIPPED IFF THE NEWEST SURVIVING WRITE TO `R`
+//     (EXCLUDING `O` AND EXCLUDING WRITES ALREADY UNDONE) IS NEWER THAN `O`.
+//
+// And when it is NOT skipped, the value restored is not the one we captured — it is THE
+// NEWEST SURVIVING WRITE OLDER THAN `O`, read out of the log. That distinction matters in
+// a case a captured `before` cannot get right:
+//
+//     Alice sets colour=red    (clock 5)
+//     Bob   sets colour=blue   (clock 9)   ← Bob captured before=red
+//     Alice sets colour=green  (clock 7)   ← arrives LATE at Bob; refused, 7 < 9
+//     Bob presses Ctrl-Z.
+//
+// Bob's captured `before` is `red` — a value that no longer exists anywhere in the
+// document's history-of-record. The log says the newest surviving write below Bob's is
+// Alice's GREEN at clock 7. Restoring red would resurrect a value two writes stale.
+// Restoring green is right, and only the log knows it.
+//
+// The captured `before` is still kept, as the fallback for the case the log CANNOT answer:
+// in production a peer joins from a SNAPSHOT plus a tail, so the op that originally set a
+// register may be long compacted away. Then `before` is the only witness there is.
+//
+// ---------------------------------------------------------------------------
+// UNDO IS AN OP
+// ---------------------------------------------------------------------------
+// An undo is an edit. It must converge, it must reach the other peers, and it must itself
+// be undoable (redo). So undo does not reach into the model behind the engine's back — it
+// applies the inverse THROUGH THE MODEL, with capture LIVE, and the op that results is
+// minted by the same clock as any other local edit. It sorts after everything it has seen,
+// so it wins its registers by the ordinary LWW rule. There is no special "undo op" kind and
+// no second code path to keep in step with the first.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UndoStack = void 0;
+const op_1 = require("./op");
+/** The register an op writes: a property path, or the entity's existence. */
+function registerOf(op) {
+    return op.op === 'set'
+        ? `${op.target} ${op.id} ${op.path}`
+        : `${op.target} ${op.id}  presence`;
+}
+/**
+ * A per-actor, supersession-aware undo/redo stack.
+ *
+ * Owns no model state. It reads the LOG to decide what an undo should do, and applies the
+ * result through the diagram so that capture mints a normal op for it.
+ */
+class UndoStack {
+    constructor(log, actor, 
+    /**
+     * Apply an inverse THROUGH THE MODEL, with capture live.
+     *
+     * Supplied by the Replica rather than called directly, because the Replica knows one
+     * thing this class must not have to: a link may be in QUARANTINE, in which case it has
+     * to be put back in the document before removing it can be a real mutation that capture
+     * can mint an op from.
+     */
+    apply) {
+        this.log = log;
+        this.actor = actor;
+        this.apply = apply;
+        this.undoable = [];
+        this.redoable = [];
+        /** Ops of mine that are currently undone. Excluded when resolving what a register held. */
+        this.undone = new Set();
+        /**
+         * Ops that MY OWN undo/redo emitted. Not authored edits — machinery.
+         *
+         * They have to be excluded when resolving what a register held, and the reason is a bug
+         * that only shows up on the SECOND press of Ctrl-Z. Undoing my move emits a fresh `set`
+         * with a fresh (therefore highest) clock. Ask "what is the newest write to this register"
+         * again, to undo the move BEFORE it, and the answer is that undo op — newer than the op
+         * being undone — so the supersession rule fires and the second Ctrl-Z silently does
+         * nothing. The user is stuck one step from where they wanted to be, for no visible reason.
+         *
+         * ONLY my own. Another peer's undo op is, to me, an ordinary write by another peer — I
+         * cannot tell it was an undo and I must not treat it as one. That asymmetry is the whole
+         * point: undo is local, ops are global.
+         */
+        this.machinery = new Set();
+        /** Open transaction: ops land here instead of becoming one entry each. */
+        this.txn = null;
+        /** True while we are applying an undo/redo, so the ops it emits are not recorded anew. */
+        this.replaying = false;
+    }
+    get canUndo() {
+        return this.undoable.length > 0;
+    }
+    get canRedo() {
+        return this.redoable.length > 0;
+    }
+    /** Depth of the undo stack — one entry per user-visible step. */
+    get depth() {
+        return this.undoable.length;
+    }
+    /**
+     * Record a local edit.
+     *
+     * Ignored while replaying: the ops an undo emits are the undo, not new work to undo.
+     */
+    record(op, before) {
+        if (this.replaying)
+            return;
+        // Any NEW work invalidates the redo branch — the same rule a single-player editor has.
+        //
+        // The entries are dropped; the ops in them STAY MARKED UNDONE. Losing the ability to redo
+        // an op is not the same as the op coming back into force: its effect was reversed by an
+        // undo op that is in the log and is never going away. Clearing the marks (which is what I
+        // wrote first) makes a discarded op count as a "surviving write" again, and the next undo
+        // of that register restores ITS value — a value the user already took back. You get it by
+        // undoing a move, typing anything at all, moving again, and undoing: the node jumps to the
+        // position you undid two steps ago.
+        this.redoable.length = 0;
+        if (this.txn) {
+            this.txn.push({ op, before });
+            return;
+        }
+        this.undoable.push({ records: [{ op, before }] });
+    }
+    /**
+     * Group everything `fn` does into ONE undo step.
+     *
+     * Without this, a gesture that touches four registers costs four Ctrl-Zs — and deleting
+     * a node with three links (which the editor does as four ops) would take four. The
+     * grouping is a LOCAL, UI-level concern: it changes what one keypress undoes, never what
+     * is on the wire, and two peers may group differently without diverging.
+     */
+    transact(fn) {
+        if (this.txn)
+            return fn(); // already in one — flatten, don't nest
+        const records = [];
+        this.txn = records;
+        try {
+            return fn();
+        }
+        finally {
+            this.txn = null;
+            if (records.length > 0)
+                this.undoable.push({ records });
+        }
+    }
+    /**
+     * Undo my last step. Returns the ops it emitted — empty if every part of it was already
+     * superseded, which is a legitimate and silent outcome.
+     *
+     * `apply` runs the inverse through the model with capture LIVE, so the resulting ops are
+     * minted, logged, gated and broadcast exactly like any other local edit.
+     */
+    undo() {
+        const entry = this.undoable.pop();
+        if (!entry)
+            return [];
+        const emitted = [];
+        this.replaying = true;
+        try {
+            // In REVERSE: the last thing done is the first thing undone, or a step that wrote the
+            // same register twice restores the wrong one of them.
+            for (const rec of [...entry.records].reverse()) {
+                this.undone.add((0, op_1.opId)(rec.op)); // …so it is excluded when we resolve the register
+                const inverse = this.invert(rec);
+                rec.undoOp = undefined;
+                if (!inverse)
+                    continue;
+                const before = this.log.size;
+                this.apply(inverse);
+                rec.undoOp = this.lastLogged(before);
+                if (rec.undoOp) {
+                    this.machinery.add((0, op_1.opId)(rec.undoOp));
+                    emitted.push(rec.undoOp);
+                }
+            }
+        }
+        finally {
+            this.replaying = false;
+        }
+        this.redoable.push(entry);
+        return emitted;
+    }
+    /** Redo the step undo last took back. */
+    redo() {
+        const entry = this.redoable.pop();
+        if (!entry)
+            return [];
+        const emitted = [];
+        this.replaying = true;
+        try {
+            for (const rec of entry.records) {
+                const forward = this.reapply(rec);
+                this.undone.delete((0, op_1.opId)(rec.op));
+                if (!forward)
+                    continue;
+                const before = this.log.size;
+                this.apply(forward);
+                const op = this.lastLogged(before);
+                if (op) {
+                    this.machinery.add((0, op_1.opId)(op));
+                    emitted.push(op);
+                }
+            }
+        }
+        finally {
+            this.replaying = false;
+        }
+        this.undoable.push(entry);
+        return emitted;
+    }
+    // -------------------------------------------------------------------------
+    /**
+     * The op that reverses `rec`, or undefined if it has already been superseded.
+     *
+     * The clock and actor on the returned op are PLACEHOLDERS and are never used: applyOp
+     * ignores them, and the op that actually reaches the log and the wire is the one capture
+     * mints from the resulting model mutation, with a fresh Lamport clock. Constructing a
+     * "real" op here and applying it directly would bypass capture and give the undo a
+     * second, divergent code path.
+     */
+    invert(rec) {
+        const { op, before } = rec;
+        const survivor = this.newestOther(op);
+        // Superseded: someone wrote this register after me. My edit is already invisible;
+        // undoing it must stay invisible. THIS IS THE LINE THAT PROTECTS ALICE'S WORK.
+        if (survivor && (0, op_1.compareOps)(survivor, op) > 0)
+            return undefined;
+        const stub = { clock: 0, actor: this.actor };
+        switch (op.op) {
+            case 'add': {
+                // If an OLDER `add` survives — I replaced an earlier incarnation of this entity —
+                // then undoing mine should restore THAT one, not delete the entity outright.
+                if (survivor && survivor.op === 'add') {
+                    return Object.assign(Object.assign({}, stub), { op: 'add', target: op.target, id: op.id, data: survivor.data });
+                }
+                return Object.assign(Object.assign({}, stub), { op: 'remove', target: op.target, id: op.id });
+            }
+            case 'remove': {
+                // TWO PEOPLE DELETE THE SAME NODE, AND ONE PRESSES CTRL-Z. This is the case that made
+                // me change the rule, and it is worth the paragraph.
+                //
+                // The tempting rule is "a colleague's delete is still standing, so the node stays
+                // gone" — recompute LWW presence excluding my undone op, and both removes vote
+                // delete. It is convergent, and it is a terrible editor: each peer only knows about
+                // its OWN undos, so BOTH users press Ctrl-Z, BOTH undos decline, and the node is gone
+                // for good with two people staring at it wondering why undo is broken. To fix that
+                // properly, an undo would have to be a first-class op that TOMBSTONES the op it
+                // undoes, so peers could recompute — a much bigger machine than this card.
+                //
+                // The rule that works is the simple one, and it is already written above: an undo is
+                // skipped IFF MY OP IS SUPERSEDED. Whoever's delete is currently IN FORCE can take it
+                // back, and the node returns. The other person's undo then finds a newer `add` on the
+                // register, sees that its own delete no longer decides anything, and correctly says
+                // nothing. One rule, both users get sane behaviour, and it converges.
+                //
+                // The `if (survivor && compareOps(...) > 0)` above is therefore LOAD-BEARING HERE and
+                // nowhere else: without it, the superseded peer re-adds ITS OWN STALE SNAPSHOT over
+                // the live incarnation, and a colleague's work vanishes.
+                //
+                // Restore the entity as it was AT THE MOMENT I DELETED IT — not as it was born. The
+                // snapshot carries every property edit it had accumulated, and because the resurrect
+                // op gets a fresh (highest) clock, the presence barrier voids every older write to
+                // it: the entity comes back exactly as the snapshot says, on every peer.
+                if (before.kind !== 'entity')
+                    return undefined; // nothing to restore it from
+                return Object.assign(Object.assign({}, stub), { op: 'add', target: op.target, id: op.id, data: before.data });
+            }
+            case 'set': {
+                // The newest surviving write BELOW mine is what the register should hold. Falling
+                // back to the captured `before` covers the case the log cannot answer — a peer that
+                // joined from a snapshot has no op for a register nobody has touched since.
+                if (before.kind !== 'value')
+                    return undefined;
+                const value = survivor && survivor.op === 'set' ? (0, op_1.setValueOf)(survivor) : before.value;
+                // `undefined` means THE REGISTER WAS EMPTY, and that is a state to restore, not a
+                // failure to find one. Bail out here and you cannot undo the FIRST label you ever
+                // put on a node — the commonest undo there is — because there was nothing there
+                // before it.
+                //
+                // wave14: restoring emptiness is an EXPLICIT, TYPED CLEAR now. This used to be a
+                // `value: undefined` cast past the OpValue type — it crossed the wire only because
+                // JSON.stringify drops an undefined key and the peer read missing-as-undefined.
+                // The lie Card 4 flagged is retired: a clear says `clear: true` and carries no
+                // value key at all. (A survivor that was itself a clear resolves to undefined via
+                // setValueOf and lands here too.)
+                if (value === undefined) {
+                    return Object.assign(Object.assign({}, stub), { op: 'set', target: op.target, id: op.id, path: op.path, clear: true });
+                }
+                return Object.assign(Object.assign({}, stub), { op: 'set', target: op.target, id: op.id, path: op.path, value });
+            }
+        }
+    }
+    /** The op that re-does `rec`, or undefined if redoing it would clobber newer work. */
+    reapply(rec) {
+        // The undo did nothing (it was already superseded), so the redo does nothing. Anything
+        // else would have Ctrl-Z do nothing and Ctrl-Y assert a stale value over a colleague's
+        // newer one — the exact stale-state resurrection the undo path exists to prevent.
+        if (!rec.undoOp)
+            return undefined;
+        // Someone edited this register AFTER my undo landed. Their write is the current truth;
+        // a redo must not silently overwrite it.
+        const after = this.newestOther(rec.op, rec.undoOp);
+        if (after && (0, op_1.compareOps)(after, rec.undoOp) > 0)
+            return undefined;
+        const stub = { clock: 0, actor: this.actor };
+        const { op } = rec;
+        switch (op.op) {
+            case 'add':
+                return Object.assign(Object.assign({}, stub), { op: 'add', target: op.target, id: op.id, data: op.data });
+            case 'remove':
+                return Object.assign(Object.assign({}, stub), { op: 'remove', target: op.target, id: op.id });
+            case 'set':
+                // Re-issue the op's write as it was — a clear as an explicit clear (this also
+                // renormalises a pre-wave14 record whose value key an old JSON hop dropped).
+                return (0, op_1.setValueOf)(op) === undefined
+                    ? Object.assign(Object.assign({}, stub), { op: 'set', target: op.target, id: op.id, path: op.path, clear: true }) : Object.assign(Object.assign({}, stub), { op: 'set', target: op.target, id: op.id, path: op.path, value: op.value });
+        }
+    }
+    /**
+     * The newest op in the log that writes the same register as `op`, ignoring `op` itself,
+     * anything else currently undone, and (optionally) one more op.
+     *
+     * O(log). That is fine for a keypress and would not be for a drag frame — nothing on a
+     * hot path calls it.
+     */
+    newestOther(op, alsoIgnore) {
+        const reg = registerOf(op);
+        const self = (0, op_1.opId)(op);
+        const skip = alsoIgnore ? (0, op_1.opId)(alsoIgnore) : undefined;
+        let best;
+        for (const candidate of this.log.toArray()) {
+            const id = (0, op_1.opId)(candidate);
+            if (id === self || id === skip)
+                continue;
+            if (this.undone.has(id))
+                continue; // an undone op is not a surviving write
+            if (this.machinery.has(id))
+                continue; // …and neither is my own undo of one
+            if (registerOf(candidate) !== reg)
+                continue;
+            if (!best || (0, op_1.compareOps)(candidate, best) > 0)
+                best = candidate;
+        }
+        return best;
+    }
+    /** The op capture minted for the mutation we just made, if it made one. */
+    lastLogged(sizeBefore) {
+        const ops = this.log.toArray();
+        if (ops.length === sizeBefore)
+            return undefined; // the write was a no-op
+        // The op we just minted has the highest clock we have ever issued, so it sorts last.
+        return ops[ops.length - 1];
+    }
+}
+exports.UndoStack = UndoStack;
+//# sourceMappingURL=undo.js.map

package/src/libs/engine/src/commands/Command.d.ts

@@ -0,0 +1,66 @@
+export interface CommandContext {
+    diagram: any;
+    eventBus: any;
+    store?: any;
+    engine?: any;
+}
+export interface SerializedCommand {
+    id: string;
+    name: string;
+    timestamp: number;
+    data: any;
+}
+export declare abstract class Command {
+    readonly id: string;
+    readonly name: string;
+    readonly timestamp: number;
+    constructor(name: string);
+    /**
+     * Execute the command
+     */
+    abstract execute(context: CommandContext): void | Promise<void>;
+    /**
+     * Undo the command
+     */
+    abstract undo(context: CommandContext): void | Promise<void>;
+    /**
+     * Redo the command (default: re-execute)
+     */
+    redo(context: CommandContext): void | Promise<void>;
+    /**
+     * Check if command can be executed
+     */
+    canExecute(context: CommandContext): boolean;
+    /**
+     * Check if command can be undone
+     */
+    canUndo(context: CommandContext): boolean;
+    /**
+     * Does this command belong on the undo stack AT ALL?
+     *
+     * `canUndo(context)` is a state probe ("can I undo RIGHT NOW?") consulted at
+     * undo time — many commands answer it from live diagram state. This is the
+     * static declaration consulted at EXECUTE time: a non-mutating command
+     * (Copy) answers false and never enters history. Recording one used to
+     * poison the stack — undo() hit the entry, threw "Cannot undo command:
+     * Copy", never decremented the index, and everything behind it became
+     * permanently unreachable.
+     */
+    isUndoable(): boolean;
+    /**
+     * Check if can merge with another command
+     */
+    canMergeWith(other: Command): boolean;
+    /**
+     * Merge with another command
+     */
+    mergeWith(other: Command): Command;
+    /**
+     * Serialize command
+     */
+    abstract serialize(): SerializedCommand;
+    /**
+     * Get description for UI
+     */
+    getDescription(): string;
+}

package/src/libs/engine/src/commands/Command.js

@@ -0,0 +1,64 @@
+"use strict";
+// Command interface for undo/redo system
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Command = void 0;
+const utils_1 = require("../utils");
+class Command {
+    constructor(name) {
+        this.id = (0, utils_1.generateId)();
+        this.name = name;
+        this.timestamp = Date.now();
+    }
+    /**
+     * Redo the command (default: re-execute)
+     */
+    redo(context) {
+        return this.execute(context);
+    }
+    /**
+     * Check if command can be executed
+     */
+    canExecute(context) {
+        return true;
+    }
+    /**
+     * Check if command can be undone
+     */
+    canUndo(context) {
+        return true;
+    }
+    /**
+     * Does this command belong on the undo stack AT ALL?
+     *
+     * `canUndo(context)` is a state probe ("can I undo RIGHT NOW?") consulted at
+     * undo time — many commands answer it from live diagram state. This is the
+     * static declaration consulted at EXECUTE time: a non-mutating command
+     * (Copy) answers false and never enters history. Recording one used to
+     * poison the stack — undo() hit the entry, threw "Cannot undo command:
+     * Copy", never decremented the index, and everything behind it became
+     * permanently unreachable.
+     */
+    isUndoable() {
+        return true;
+    }
+    /**
+     * Check if can merge with another command
+     */
+    canMergeWith(other) {
+        return false;
+    }
+    /**
+     * Merge with another command
+     */
+    mergeWith(other) {
+        throw new Error('Merge not supported');
+    }
+    /**
+     * Get description for UI
+     */
+    getDescription() {
+        return this.name;
+    }
+}
+exports.Command = Command;
+//# sourceMappingURL=Command.js.map

package/src/libs/engine/src/commands/CommandManager.d.ts

@@ -0,0 +1,161 @@
+import { Command, CommandContext } from './Command';
+import { EventBus } from '../events/EventBus';
+export interface CommandHistoryEntry {
+    command: Command;
+    timestamp: number;
+    duration: number;
+    /**
+     * Wave 14: history only ever records commands that EXECUTED successfully, so
+     * this is always `true` and `error` is never set. Both fields survive purely
+     * for API compatibility — a command that throws (or fails strict validation)
+     * no longer enters history at all, because canUndo()/undo() never consulted
+     * these flags and would happily "undo" a mutation that never happened.
+     */
+    success: boolean;
+    error?: Error;
+}
+export declare class CommandManager {
+    private context;
+    private eventBus;
+    private history;
+    private currentIndex;
+    private maxHistorySize;
+    private batchMode;
+    private batchCommands;
+    private mergingEnabled;
+    private mergingWindow;
+    constructor(context: CommandContext, eventBus?: EventBus);
+    /**
+     * Wave 9 — Card 7. Is the document locked against edits?
+     *
+     * THE choke point for every command-shaped mutation. It matters far more than it
+     * looks, because these all funnel through here:
+     *   - clipboard: Paste / Cut / Duplicate commands (and `engine.paste()` etc.)
+     *   - the Wave-6 a11y keyboard layer, which is a pure COMMAND FACTORY — it
+     *     returns `Command | null` and never executes, so refusing here refuses
+     *     keyboard delete / nudge / duplicate / connect in one place
+     *   - `ext/public-api.ts`, the extension escape hatch
+     *
+     * `context.diagram` is typed `any` on CommandContext, hence the defensive probe.
+     */
+    private isReadonly;
+    /**
+     * Execute a command
+     */
+    execute(command: Command): Promise<void>;
+    /**
+     * Merge `incoming` into the previous history entry and re-execute (wave 14).
+     *
+     * Order matters: the merged command EXECUTES FIRST and only then replaces the
+     * entry's command — the old code overwrote the entry BEFORE re-executing, so
+     * a throwing merged execution left history claiming the merged command was
+     * applied.
+     *
+     * Strict validation applies here too — deliberately NOT skipped: had
+     * `incoming` not merged, the normal path would have validated this exact
+     * terminal state (mergeable commands are set-to-value, so executing the
+     * merged command lands exactly where executing `incoming` on top of
+     * `previous` would have). Merging is a history-compression detail and must
+     * not double as a validation bypass. The revert is two steps because a
+     * merged command keeps the ORIGINAL before-state (see MoveNodeCommand):
+     * merged.undo() rewinds PAST `previous`, so previous.redo() then re-applies
+     * the last valid state, leaving the history entry untouched.
+     */
+    private executeMerged;
+    /**
+     * Real-time validation of the diagram AFTER a command executed (wave 14).
+     *
+     * In strict mode an invalid diagram runs `revert` — which must undo exactly
+     * the just-executed command — and throws. It must NOT call this.undo(): the
+     * failing command is not in history (yet), so undo() would revert the
+     * PREVIOUS entry and decrement currentIndex, which is precisely the old
+     * triple corruption (previous good command reverted, then permanently erased
+     * by addToHistory's redo-truncation, failed command left as the undoable top).
+     */
+    private assertResultValid;
+    /**
+     * Undo last command
+     */
+    undo(): Promise<void>;
+    /**
+     * Redo command
+     */
+    redo(): Promise<void>;
+    /**
+     * Begin batch mode
+     */
+    beginBatch(): void;
+    /**
+     * End batch mode: commit the queued commands as ONE BatchCommand through the
+     * normal execute() path (wave 14) — one history entry, one undo step (with
+     * reverse-order undo), and the same strict-validation gate as any other
+     * command. The old code looped executeCommand() directly, so a "batch"
+     * mutated the diagram while building NO history at all.
+     *
+     * Note BatchCommand's existing gate contract: its canExecute() checks every
+     * queued command against the CURRENT (pre-batch) state, so a queue whose
+     * later commands only become executable after earlier ones ran is refused
+     * up front rather than applied halfway.
+     */
+    endBatch(name?: string): Promise<void>;
+    /**
+     * Cancel batch
+     */
+    cancelBatch(): void;
+    /**
+     * Clear history
+     */
+    clear(): void;
+    /**
+     * Can undo
+     */
+    canUndo(): boolean;
+    /**
+     * Can redo
+     */
+    canRedo(): boolean;
+    /**
+     * Get history
+     */
+    getHistory(): ReadonlyArray<CommandHistoryEntry>;
+    /**
+     * Get undo stack
+     */
+    getUndoStack(): ReadonlyArray<Command>;
+    /**
+     * Get redo stack
+     */
+    getRedoStack(): ReadonlyArray<Command>;
+    /**
+     * Set max history size
+     */
+    setMaxHistorySize(size: number): void;
+    /**
+     * Enable/disable merging
+     */
+    setMergingEnabled(enabled: boolean): void;
+    /**
+     * Set merging window
+     */
+    setMergingWindow(milliseconds: number): void;
+    /**
+     * Update command context
+     */
+    updateContext(updates: Partial<CommandContext>): void;
+    /**
+     * Execute command without adding to history
+     */
+    private executeCommand;
+    /**
+     * Add command to history
+     */
+    private addToHistory;
+    /**
+     * Trim history to max size
+     */
+    private trimHistory;
+    /**
+     * Check if can merge with previous command
+     */
+    private canMergeWithPrevious;
+}