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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ });+});