Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(editor): an undo checkpoint, so a whole agent turn reverts in one gesture

esengine5ed14fc7fce7
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index 8a7abf506..3966de58b 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -32,7 +32,7 @@ import { PerfMonitor, type PerfSnapshot, type FrameSample, type SessionCapture }
import type { SceneCommandsImpl, EditorTransaction } from './SceneCommands';
import type { SceneQueryImpl, EntityInfo } from './SceneQuery';
import type { SceneModelImpl } from './SceneModel';
-import type { EditorHistoryImpl } from './EditorHistory';
+import type { EditorHistoryImpl, HistoryMark } from './EditorHistory';
import type { ReconcilerImpl } from './Reconciler';
import type { SelectionStore } from '@/store/selectionStore';
@@ -289,6 +289,28 @@ export class EditorControlSurfaceImpl {
Renderer.setYSortLayers(mask >>> 0);
}
+ /**
+ * Take an undo checkpoint — the "before" of an agent turn, so a whole turn
+ * reverts in one gesture while each edit it made stays an ordinary undo step.
+ *
+ * Deliberately NOT in the tool catalog: the checkpoint belongs to whoever is
+ * driving the turn (the agent kernel, and the UI that offers the revert), not
+ * to the model running inside it. A model that could roll itself back could
+ * also undo the user's own work and call it a correction.
+ */
+ mark(): HistoryMark {
+ return this.s.history.mark();
+ }
+ /** Edits recorded since `mark` that are still undoable — 0 means the turn
+ * changed nothing, or its work is no longer the newest thing on the stack. */
+ stepsSince(mark: HistoryMark): number {
+ return this.s.history.stepsSince(mark);
+ }
+ /** Revert everything recorded since `mark`; returns how many steps were undone. */
+ undoToMark(mark: HistoryMark): number {
+ return this.s.history.undoToMark(mark);
+ }
+
undo(): void {
this.s.history.undo();
}
diff --git a/desktop/src/engine/EditorHistory.ts b/desktop/src/engine/EditorHistory.ts
index b4da68456..6a6c833bb 100644
--- a/desktop/src/engine/EditorHistory.ts
+++ b/desktop/src/engine/EditorHistory.ts
@@ -32,6 +32,21 @@ interface HistoryEntry {
ops: HistoryOp[];
}
+/**
+ * A point the stack can be rolled back to in one action — an agent turn's
+ * "before", so the user reverts a whole conversation turn with one gesture
+ * while each tool call it made stays its own ordinary undo step.
+ *
+ * It records the SEQUENCE COUNTER, not the head entry or a depth. Ids only ever
+ * increase, so "recorded after this mark" is exactly `id > seq` — which needs no
+ * lookup, cannot be invalidated by a purge or by scrolling past HISTORY_LIMIT,
+ * and stays correct when the stack was empty at mark time. A mark holding the
+ * head entry instead would have all three problems.
+ */
+export interface HistoryMark {
+ readonly seq: number;
+}
+
export class EditorHistoryImpl {
private readonly undoStack: HistoryEntry[] = [];
private readonly redoStack: HistoryEntry[] = [];
@@ -167,6 +182,45 @@ export class EditorHistoryImpl {
}
}
+ /** Take a checkpoint here — see {@link HistoryMark}. Records nothing. */
+ mark(): HistoryMark {
+ return { seq: this.seq };
+ }
+
+ /**
+ * Steps still on the stack that were recorded after `mark`. Zero means the
+ * turn changed nothing (or its steps were already undone), which is what the
+ * caller checks before offering a revert.
+ */
+ stepsSince(mark: HistoryMark): number {
+ let n = 0;
+ for (let i = this.undoStack.length - 1; i >= 0 && this.undoStack[i].id > mark.seq; i--) n++;
+ return n;
+ }
+
+ /**
+ * Undo every step recorded after `mark`, newest first, and return how many.
+ * They land on the redo stack as usual, so the whole turn can be brought back.
+ *
+ * The stack is linear, so this also reverts anything the USER did after the
+ * mark — there is no out-of-order undo to offer instead. The caller is
+ * expected to stop offering the revert once its own steps are no longer the
+ * newest, which {@link stepsSince} plus a version bump is enough to detect.
+ */
+ undoToMark(mark: HistoryMark): number {
+ let n = 0;
+ while (this.undoStack.length && this.undoStack[this.undoStack.length - 1].id > mark.seq) {
+ const entry = this.undoStack.pop()!;
+ EditorHistoryImpl.apply(entry, 'undo');
+ this.redoStack.push(entry);
+ n++;
+ }
+ // One notification for the whole rollback: this is a single user gesture,
+ // and bumping per entry would re-render every panel N times.
+ if (n) this.bump();
+ return n;
+ }
+
undo() {
const entry = this.undoStack.pop();
if (!entry) return;
diff --git a/desktop/tests/editor-history-checkpoint.test.ts b/desktop/tests/editor-history-checkpoint.test.ts
new file mode 100644
index 000000000..b04538ea5
--- /dev/null
+++ b/desktop/tests/editor-history-checkpoint.test.ts
@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file EditorHistory.mark / undoToMark — the agent-turn checkpoint. Each tool
+ * call stays its own undo step (the user can pick edits apart, and can
+ * edit in between), while the turn as a whole reverts in one gesture.
+ * Pure TS.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { EditorHistoryImpl } from '@/engine/EditorHistory';
+
+describe('EditorHistory checkpoints', () => {
+ let h: EditorHistoryImpl;
+ let value: number;
+ beforeEach(() => {
+ h = new EditorHistoryImpl();
+ value = 0;
+ });
+
+ const add = (n: number) => {
+ value += n;
+ h.record(`Add ${n}`, () => { value += n; }, () => { value -= n; });
+ };
+
+ it('reverts everything after the mark, and nothing before it', () => {
+ add(1);
+ const turn = h.mark();
+ add(2);
+ add(4);
+ expect(value).toBe(7);
+ expect(h.stepsSince(turn)).toBe(2);
+
+ expect(h.undoToMark(turn)).toBe(2);
+ expect(value).toBe(1); // the pre-mark edit survives
+ expect(h.stepsSince(turn)).toBe(0);
+ });
+
+ it('leaves the reverted turn on the redo stack', () => {
+ const turn = h.mark();
+ add(2);
+ add(4);
+ h.undoToMark(turn);
+ expect(value).toBe(0);
+
+ // Undo is not deletion: bringing the turn back is the ordinary redo path.
+ h.redo();
+ h.redo();
+ expect(value).toBe(6);
+ });
+
+ it('each step inside the turn is still its own undo step', () => {
+ const turn = h.mark();
+ add(2);
+ add(4);
+ h.undo();
+ expect(value).toBe(2);
+ expect(h.stepsSince(turn)).toBe(1);
+ // …and the checkpoint still reverts what is left.
+ expect(h.undoToMark(turn)).toBe(1);
+ expect(value).toBe(0);
+ });
+
+ it('a mark taken on an empty stack means "back to nothing"', () => {
+ const turn = h.mark();
+ add(1);
+ add(2);
+ expect(h.undoToMark(turn)).toBe(2);
+ expect(value).toBe(0);
+ expect(h.canUndo()).toBe(false);
+ });
+
+ it('reverting an untouched turn does nothing and reports nothing', () => {
+ add(1);
+ const turn = h.mark();
+ expect(h.stepsSince(turn)).toBe(0);
+ expect(h.undoToMark(turn)).toBe(0);
+ expect(value).toBe(1);
+ });
+
+ // A mark is a sequence number, not a reference to an entry, so the two ways a
+ // stack loses entries cannot turn it into a rollback of unrelated work.
+ it('survives a purge of the entries underneath it', () => {
+ h.record('Doc edit', () => {}, () => {}, 'doc-a');
+ const turn = h.mark();
+ add(2);
+ h.purgeDoc('doc-a'); // the pre-mark entry is gone
+ expect(h.stepsSince(turn)).toBe(1);
+ expect(h.undoToMark(turn)).toBe(1);
+ expect(value).toBe(0);
+ });
+
+ it('stops at the bottom when the marked point scrolled out of the limit', () => {
+ add(1);
+ const turn = h.mark();
+ // Overrun HISTORY_LIMIT so the pre-mark entry is shifted away.
+ for (let i = 0; i < 210; i++) add(1);
+ const before = value;
+ const undone = h.undoToMark(turn);
+ expect(undone).toBe(200); // the whole (capped) stack, all of it post-mark
+ expect(value).toBe(before - 200);
+ expect(h.canUndo()).toBe(false);
+ });
+
+ it('notifies once for the whole rollback, not once per step', () => {
+ const turn = h.mark();
+ add(1);
+ add(2);
+ add(4);
+ const v0 = h.getVersion();
+ h.undoToMark(turn);
+ expect(h.getVersion()).toBe(v0 + 1);
+ });
+});