keyboard: Undo stack for keyboard target (#2420)

- Fixes #2413

## Checklist

- [x] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [-] I have updated the
[docs](https://github.com/cursorless-dev/cursorless/tree/main/docs) and
[cheatsheet](https://github.com/cursorless-dev/cursorless/tree/main/cursorless-talon/src/cheatsheet)
- [-] I have not broken the cheatsheet

Author: pokey

packages/common/src/cursorlessCommandIds.ts

@@ -31,6 +31,8 @@ export const cursorlessCommandIds = [
   "cursorless.keyboard.modal.modeOff",
   "cursorless.keyboard.modal.modeOn",
   "cursorless.keyboard.modal.modeToggle",
+  "cursorless.keyboard.undoTarget",
+  "cursorless.keyboard.redoTarget",
   "cursorless.keyboard.targeted.clearTarget",
   "cursorless.keyboard.targeted.runActionOnTarget",
   "cursorless.keyboard.targeted.targetHat",
@@ -136,4 +138,10 @@ export const cursorlessCommandDescriptions: Record<
   ["cursorless.keyboard.modal.modeToggle"]: new HiddenCommand(
     "Toggle the cursorless modal mode",
   ),
+  ["cursorless.keyboard.undoTarget"]: new HiddenCommand(
+    "Undo keyboard targeting changes",
+  ),
+  ["cursorless.keyboard.redoTarget"]: new HiddenCommand(
+    "Redo keyboard targeting changes",
+  ),
 };

packages/cursorless-engine/src/core/StoredTargets.ts

@@ -1,24 +1,55 @@
-import { Notifier } from "@cursorless/common";
+import { DefaultMap, Notifier } from "@cursorless/common";
 import { Target } from "../typings/target.types";
 import { StoredTargetKey, storedTargetKeys } from "@cursorless/common";
+import { UndoStack } from "./UndoStack";
+
+const MAX_HISTORY_LENGTH = 25;
 
 /**
  * Used to store targets between commands.  This is used by marks like `that`
  * and `source`.
  */
 export class StoredTargetMap {
   private targetMap: Map<StoredTargetKey, Target[] | undefined> = new Map();
+
+  // FIXME: Keep these targets up to date as document changes
+  private targetHistory: DefaultMap<StoredTargetKey, UndoStack<Target[]>> =
+    new DefaultMap(() => new UndoStack<Target[]>(MAX_HISTORY_LENGTH));
+
   private notifier = new Notifier<[StoredTargetKey, Target[] | undefined]>();
 
-  set(key: StoredTargetKey, targets: Target[] | undefined) {
+  set(
+    key: StoredTargetKey,
+    targets: Target[] | undefined,
+    { history = false }: { history?: boolean } = {},
+  ) {
     this.targetMap.set(key, targets);
+    if (history && targets != null) {
+      this.targetHistory.get(key).push(targets);
+    }
     this.notifier.notifyListeners(key, targets);
   }
 
   get(key: StoredTargetKey) {
     return this.targetMap.get(key);
   }
 
+  undo(key: StoredTargetKey) {
+    const targets = this.targetHistory.get(key).undo();
+
+    if (targets != null) {
+      this.set(key, targets, { history: false });
+    }
+  }
+
+  redo(key: StoredTargetKey) {
+    const targets = this.targetHistory.get(key).redo();
+
+    if (targets != null) {
+      this.set(key, targets, { history: false });
+    }
+  }
+
   onStoredTargets(
     callback: (key: StoredTargetKey, targets: Target[] | undefined) => void,
   ) {

packages/cursorless-engine/src/core/UndoStack.test.ts

@@ -0,0 +1,52 @@
+import assert from "node:assert";
+import { UndoStack } from "./UndoStack";
+
+suite("UndoStack", () => {
+  test("should undo and redo", () => {
+    const undoStack = new UndoStack<string>(3);
+    undoStack.push("a");
+    undoStack.push("b");
+    undoStack.push("c");
+    assert.strictEqual(undoStack.undo(), "b");
+    assert.strictEqual(undoStack.undo(), "a");
+    assert.strictEqual(undoStack.undo(), undefined);
+    assert.strictEqual(undoStack.redo(), "b");
+    assert.strictEqual(undoStack.redo(), "c");
+    assert.strictEqual(undoStack.redo(), undefined);
+  });
+
+  test("should clobber stack if push after undo", () => {
+    const undoStack = new UndoStack<string>(3);
+    undoStack.push("a");
+    undoStack.push("b");
+    undoStack.push("c");
+    assert.strictEqual(undoStack.undo(), "b");
+    undoStack.push("d");
+    assert.strictEqual(undoStack.undo(), "b");
+    assert.strictEqual(undoStack.redo(), "d");
+    assert.strictEqual(undoStack.redo(), undefined);
+  });
+
+  test("should truncate history if max lenght exceeded", () => {
+    const undoStack = new UndoStack<string>(3);
+    undoStack.push("a");
+    undoStack.push("b");
+    undoStack.push("c");
+    undoStack.push("d");
+    assert.strictEqual(undoStack.undo(), "c");
+    assert.strictEqual(undoStack.undo(), "b");
+    assert.strictEqual(undoStack.undo(), undefined);
+  });
+
+  test("should handle empty undo and redo", () => {
+    const undoStack = new UndoStack<string>(3);
+    assert.strictEqual(undoStack.undo(), undefined);
+    assert.strictEqual(undoStack.redo(), undefined);
+  });
+
+  test("should handle redo at end of stack", () => {
+    const undoStack = new UndoStack<string>(3);
+    undoStack.push("a");
+    assert.strictEqual(undoStack.redo(), undefined);
+  });
+});

packages/cursorless-engine/src/core/UndoStack.ts

@@ -0,0 +1,63 @@
+/**
+ * Keeps track of the history of a piece of state. You can push new states onto
+ * the stack, undo to previous states, and redo to future states.
+ */
+export class UndoStack<T> {
+  private stack: T[] = [];
+  private index: number | undefined = undefined;
+
+  constructor(private maxLength: number) {}
+
+  /**
+   * Push a new state onto the stack. If {@link undo} has been called, the
+   * future states will be dropped and the new state will be pushed onto the
+   * stack.
+   *
+   * @param item The new state to push onto the stack
+   */
+  push(item: T) {
+    if (this.index != null) {
+      this.stack.splice(
+        this.index + 1,
+        this.stack.length - this.index - 1,
+        item,
+      );
+    } else {
+      this.stack.push(item);
+    }
+
+    if (this.stack.length > this.maxLength) {
+      this.stack.shift();
+    }
+
+    this.index = this.stack.length - 1;
+  }
+
+  /**
+   * Undo to the previous state.
+   *
+   * @returns The previous state, or `undefined` if there are no previous states
+   */
+  undo(): T | undefined {
+    if (this.index != null && this.index > 0) {
+      this.index--;
+      return this.stack[this.index];
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Redo to the next state.
+   *
+   * @returns The next state, or `undefined` if there are no future states
+   */
+  redo(): T | undefined {
+    if (this.index != null && this.index < this.stack.length - 1) {
+      this.index++;
+      return this.stack[this.index];
+    }
+
+    return undefined;
+  }
+}

packages/cursorless-engine/src/core/commandRunner/CommandRunnerImpl.ts

@@ -84,7 +84,7 @@ export class CommandRunnerImpl implements CommandRunner {
       constructStoredTarget(newSourceTargets, newSourceSelections),
     );
     this.storedTargets.set("instanceReference", newInstanceReferenceTargets);
-    this.storedTargets.set("keyboard", newKeyboardTargets);
+    this.storedTargets.set("keyboard", newKeyboardTargets, { history: true });
 
     return { returnValue };
   }

packages/cursorless-vscode-e2e/src/suite/keyboard/basic.vscode.test.ts

@@ -106,6 +106,27 @@ const testCases: TestCase[] = [
     keySequence: ["da", "nst", " ", "c"],
     finalContent: "aaa bbb  ddd",
   },
+  {
+    name: "keyboard undo",
+    initialContent: "aaa bbb",
+    // keyboard air
+    // keyboard bat
+    // undo keyboard
+    // clear
+    keySequence: ["da", "db", "vu", "c"],
+    finalContent: " bbb",
+  },
+  {
+    name: "keyboard redo",
+    initialContent: "aaa bbb",
+    // keyboard air
+    // keyboard bat
+    // undo keyboard
+    // redo keyboard
+    // clear
+    keySequence: ["da", "db", "vu", "vr", "c"],
+    finalContent: "aaa ",
+  },
 ];
 
 suite("Basic keyboard test", async function () {

packages/cursorless-vscode/package.json

@@ -189,6 +189,16 @@
         "command": "cursorless.keyboard.modal.modeToggle",
         "title": "Cursorless: Toggle the cursorless modal mode",
         "enablement": "false"
+      },
+      {
+        "command": "cursorless.keyboard.undoTarget",
+        "title": "Cursorless: Undo keyboard targeting changes",
+        "enablement": "false"
+      },
+      {
+        "command": "cursorless.keyboard.redoTarget",
+        "title": "Cursorless: Redo keyboard targeting changes",
+        "enablement": "false"
       }
     ],
     "colors": [

packages/cursorless-vscode/src/extension.ts

@@ -146,6 +146,7 @@ export async function activate(
     scopeVisualizer,
     keyboardCommands,
     hats,
+    storedTargets,
   );
 
   new ReleaseNotes(vscodeApi, context, normalizedIde.messages).maybeShow();

packages/cursorless-vscode/src/keyboard/keyboard-config.fixture.json

@@ -83,7 +83,9 @@
       "keepChangedSelection": true,
       "exitCursorlessMode": true
     },
-    " ": "cursorless.repeatPreviousCommand"
+    " ": "cursorless.repeatPreviousCommand",
+    "vu": "cursorless.keyboard.undoTarget",
+    "vr": "cursorless.keyboard.redoTarget"
   },
   "cursorless.experimental.keyboard.modal.keybindings.pairedDelimiter": {
     "wl": "angleBrackets",

packages/cursorless-vscode/src/registerCommands.ts

@@ -6,6 +6,7 @@ import {
 } from "@cursorless/common";
 import {
   CommandApi,
+  StoredTargetMap,
   TestCaseRecorder,
   analyzeCommandHistory,
   showCheatsheet,
@@ -30,6 +31,7 @@ export function registerCommands(
   scopeVisualizer: ScopeVisualizer,
   keyboardCommands: KeyboardCommands,
   hats: VscodeHats,
+  storedTargets: StoredTargetMap,
 ): void {
   const runCommandWrapper = async (run: () => Promise<unknown>) => {
     try {
@@ -114,6 +116,9 @@ export function registerCommands(
     ["cursorless.keyboard.modal.modeOn"]: keyboardCommands.modal.modeOn,
     ["cursorless.keyboard.modal.modeOff"]: keyboardCommands.modal.modeOff,
     ["cursorless.keyboard.modal.modeToggle"]: keyboardCommands.modal.modeToggle,
+
+    ["cursorless.keyboard.undoTarget"]: () => storedTargets.undo("keyboard"),
+    ["cursorless.keyboard.redoTarget"]: () => storedTargets.redo("keyboard"),
   };
 
   extensionContext.subscriptions.push(