From 32c037ec116c250975e509f478462f72aabd6e61 Mon Sep 17 00:00:00 2001
From: Paul Elliott <paul@vizworkshop.com>
Date: Tue, 18 Aug 2026 11:17:16 -0400
Subject: [PATCH] feat(shortcuts): delete selected annotations with the delete
 key

The delete key had to reach the app while a checkbox or slider held focus,
which the old dispatcher could not do: it watched vueuse magic keys, rebuilt
every watcher whenever a binding changed, and decided whether to suppress a
shortcut by asking what kind of element had focus.

Shortcuts now dispatch from one keydown listener against a table of parsed
bindings. Anything a control handles in script reports itself through
preventDefault, so arbitration only has to cover what the browser does
natively and no handler announces: typing into a field, Space or Enter
activating a focused control, and the arrow keys stepping through a group of
values.

An action can name more than one key, since the main delete key reports
Backspace on macOS. Hold actions read their state through useActionHeld
instead of each view resolving a binding itself, and a binding no keystroke
could produce is dropped from a loaded config with a warning rather than
rejecting the file.

Removing a selection says how many annotations went, because the selection
can hold annotations with no visible cue in the current view and there is no
undo.
---
 src/components/ControlsModal.vue              |   9 +-
 src/components/ControlsStripTools.vue         |  33 +-
 src/components/MeasurementsToolList.vue       |  11 +-
 src/components/tools/paint/PaintWidget2D.vue  |   8 +-
 src/components/tools/polygon/PolygonTool.vue  |   9 +-
 .../vtk/VtkCineScrubKeyManipulator.vue        |   7 +-
 .../vtk/VtkSliceViewSlicingKeyManipulator.vue |   7 +-
 .../deleteSelectedAnnotations.spec.ts         | 106 ++++++
 .../__tests__/useKeyboardShortcuts.spec.ts    | 340 +++++++++++++++++-
 src/composables/actions.ts                    |   4 +-
 src/composables/useKeyboardShortcuts.ts       | 258 ++++++++++---
 src/config.ts                                 |   7 +-
 src/constants.ts                              |  10 +
 src/io/import/__tests__/configJson.spec.ts    |  26 ++
 src/io/import/configJson.ts                   |  52 ++-
 src/io/import/processors/handleConfig.ts      |   5 +-
 src/store/messages.ts                         |   9 +
 .../__tests__/removeSelectedTools.spec.ts     | 121 +++++++
 src/store/tools/index.ts                      |  33 ++
 tests/pageobjects/volview.page.ts             |  16 +-
 tests/specs/annotationTestUtils.ts            |  54 +++
 tests/specs/cineTestUtils.ts                  |   8 +-
 tests/specs/delete-selected-annotation.e2e.ts | 147 ++++++++
 tests/specs/polygon-nested-interaction.e2e.ts |  95 +----
 24 files changed, 1162 insertions(+), 213 deletions(-)
 create mode 100644 src/composables/__tests__/deleteSelectedAnnotations.spec.ts
 create mode 100644 src/store/tools/__tests__/removeSelectedTools.spec.ts
 create mode 100644 tests/specs/annotationTestUtils.ts
 create mode 100644 tests/specs/delete-selected-annotation.e2e.ts

diff --git a/src/components/ControlsModal.vue b/src/components/ControlsModal.vue
index c73555389..c01a43d05 100644
--- a/src/components/ControlsModal.vue
+++ b/src/components/ControlsModal.vue
@@ -34,7 +34,10 @@
 
 <script setup lang="ts">
 import { computed } from 'vue';
-import { actionToKey } from '@/src/composables/useKeyboardShortcuts';
+import {
+  actionToKey,
+  readableBinding,
+} from '@/src/composables/useKeyboardShortcuts';
 import { ACTIONS } from '@/src/constants';
 import { useKeyboardShortcutsStore } from '@/src/store/keyboard-shortcuts';
 import CloseableDialog from './CloseableDialog.vue';
@@ -43,9 +46,9 @@ import { getEntries } from '../utils';
 const keyboardStore = useKeyboardShortcutsStore();
 
 const bindings = computed(() =>
-  getEntries(actionToKey.value).map(([action, key]) => [
+  getEntries(actionToKey.value).map(([action, binding]) => [
     ACTIONS[action].readable,
-    key,
+    readableBinding(binding),
   ])
 );
 </script>
diff --git a/src/components/ControlsStripTools.vue b/src/components/ControlsStripTools.vue
index 2287ccbe1..97265d719 100644
--- a/src/components/ControlsStripTools.vue
+++ b/src/components/ControlsStripTools.vue
@@ -135,7 +135,7 @@
 
 <script lang="ts">
 import { computed, defineComponent, ref, watch } from 'vue';
-import { onKeyDown, useMagicKeys } from '@vueuse/core';
+import { onKeyDown } from '@vueuse/core';
 import { Tools } from '@/src/store/tools/types';
 import ControlButton from '@/src/components/ControlButton.vue';
 import ItemGroup from '@/src/components/ItemGroup.vue';
@@ -150,7 +150,11 @@ import RulerControls from '@/src/components/RulerControls.vue';
 import RectangleControls from '@/src/components/RectangleControls.vue';
 import PolygonControls from '@/src/components/PolygonControls.vue';
 import WindowLevelControls from '@/src/components/tools/windowing/WindowLevelControls.vue';
-import { actionToKey } from '@/src/composables/useKeyboardShortcuts';
+import {
+  actionToKey,
+  readableBinding,
+  useActionHeld,
+} from '@/src/composables/useKeyboardShortcuts';
 import { useCurrentImage } from '@/src/composables/useCurrentImage';
 import { useViewStore } from '@/src/store/views';
 
@@ -199,10 +203,7 @@ export default defineComponent({
       windowingMenu.value = false;
     });
 
-    const keys = useMagicKeys();
-    const enableTempCrosshairs = computed(
-      () => keys[actionToKey.value.temporaryCrosshairs].value
-    );
+    const enableTempCrosshairs = useActionHeld('temporaryCrosshairs');
     watch(enableTempCrosshairs, (enable) => {
       if (enable) toolStore.activateTemporaryCrosshairs();
       else toolStore.deactivateTemporaryCrosshairs();
@@ -212,16 +213,16 @@ export default defineComponent({
     const nameToShortcut = computed(() => {
       const keyMap = actionToKey.value;
       return {
-        'Window & Level': keyMap.windowLevel,
-        Pan: keyMap.pan,
-        Zoom: keyMap.zoom,
-        Crosshairs: keyMap.crosshairs,
-        Select: keyMap.select,
-        Paint: keyMap.paint,
-        Rectangle: keyMap.rectangle,
-        Polygon: keyMap.polygon,
-        Ruler: keyMap.ruler,
-        Crop: keyMap.crop,
+        'Window & Level': readableBinding(keyMap.windowLevel),
+        Pan: readableBinding(keyMap.pan),
+        Zoom: readableBinding(keyMap.zoom),
+        Crosshairs: readableBinding(keyMap.crosshairs),
+        Select: readableBinding(keyMap.select),
+        Paint: readableBinding(keyMap.paint),
+        Rectangle: readableBinding(keyMap.rectangle),
+        Polygon: readableBinding(keyMap.polygon),
+        Ruler: readableBinding(keyMap.ruler),
+        Crop: readableBinding(keyMap.crop),
       };
     });
 
diff --git a/src/components/MeasurementsToolList.vue b/src/components/MeasurementsToolList.vue
index 6f793b241..794071cfa 100644
--- a/src/components/MeasurementsToolList.vue
+++ b/src/components/MeasurementsToolList.vue
@@ -4,7 +4,7 @@ import { useCurrentImage } from '@/src/composables/useCurrentImage';
 import { frameOfReferenceToImageSliceAndAxis } from '@/src/utils/frameOfReference';
 import { nonNullable } from '@/src/utils/index';
 import { AnnotationToolType } from '@/src/store/tools/types';
-import { useAnnotationToolStore } from '@/src/store/tools';
+import { removeSelectedTools, useAnnotationToolStore } from '@/src/store/tools';
 import {
   useMultipleToolSelection,
   MultipleSelectionState,
@@ -89,13 +89,6 @@ const toggleSelectAll = (shouldSelectAll: Maybe<boolean>) => {
   }
 };
 
-function removeAll() {
-  selectionStore.selection.forEach((sel) => {
-    const store = useAnnotationToolStore(sel.type);
-    store.removeTool(sel.id);
-  });
-}
-
 // If all selected tools are already hidden, it should be "show".
 // If at least one selected tool is visible, it should be "hide".
 const allHidden = computed(() => {
@@ -156,7 +149,7 @@ function toggleGlobalHidden() {
         icon
         variant="text"
         :disabled="selectionState === MultipleSelectionState.None"
-        @click.stop="removeAll"
+        @click.stop="removeSelectedTools"
       >
         <v-icon>mdi-delete</v-icon>
         <v-tooltip
diff --git a/src/components/tools/paint/PaintWidget2D.vue b/src/components/tools/paint/PaintWidget2D.vue
index 0d94d08b7..b870dfed1 100644
--- a/src/components/tools/paint/PaintWidget2D.vue
+++ b/src/components/tools/paint/PaintWidget2D.vue
@@ -9,7 +9,6 @@ import {
   watchEffect,
   inject,
 } from 'vue';
-import { useMagicKeys } from '@vueuse/core';
 import vtkPlaneManipulator from '@kitware/vtk.js/Widgets/Manipulators/PlaneManipulator';
 import { vec3 } from 'gl-matrix';
 import { getLPSAxisFromDir } from '@/src/utils/lps';
@@ -24,7 +23,7 @@ import { onVTKEvent } from '@/src/composables/onVTKEvent';
 import { useSliceInfo } from '@/src/composables/useSliceInfo';
 import { VtkViewContext } from '@/src/components/vtk/context';
 import { Maybe } from '@/src/types';
-import { actionToKey } from '@/src/composables/useKeyboardShortcuts';
+import { useActionHeld } from '@/src/composables/useKeyboardShortcuts';
 
 export default defineComponent({
   name: 'PaintWidget2D',
@@ -172,10 +171,7 @@ export default defineComponent({
     });
 
     // Brush size scroll wheel control with customizable modifier key
-    const keys = useMagicKeys();
-    const enableBrushSizeAdjustment = computed(
-      () => keys[actionToKey.value.brushSizeModifier].value
-    );
+    const enableBrushSizeAdjustment = useActionHeld('brushSizeModifier');
 
     const handleWheelEvent = (event: WheelEvent) => {
       if (!enableBrushSizeAdjustment.value) return;
diff --git a/src/components/tools/polygon/PolygonTool.vue b/src/components/tools/polygon/PolygonTool.vue
index 2f5cd61cb..89c19634a 100644
--- a/src/components/tools/polygon/PolygonTool.vue
+++ b/src/components/tools/polygon/PolygonTool.vue
@@ -101,11 +101,11 @@ import {
 } from '@/src/composables/annotationTool';
 import AnnotationContextMenu from '@/src/components/tools/AnnotationContextMenu.vue';
 import AnnotationInfo from '@/src/components/tools/AnnotationInfo.vue';
-import { actionToKey } from '@/src/composables/useKeyboardShortcuts';
+import { useActionHeld } from '@/src/composables/useKeyboardShortcuts';
 import { Maybe } from '@/src/types';
 import { useViewLocator } from '@/src/composables/useViewLocator';
 import { locatorPatch } from '@/src/core/annotations/locator';
-import { useMagicKeys, watchImmediate } from '@vueuse/core';
+import { watchImmediate } from '@vueuse/core';
 import { fillPoly } from '@thi.ng/rasterize';
 import type { IGrid2D } from '@thi.ng/api';
 import vtkImageData from '@kitware/vtk.js/Common/DataModel/ImageData';
@@ -211,10 +211,7 @@ export default defineComponent({
       placingTool.remove();
     });
 
-    const keys = useMagicKeys();
-    const mergeKey = computed(
-      () => keys[actionToKey.value.mergeNewPolygon].value
-    );
+    const mergeKey = useActionHeld('mergeNewPolygon');
 
     const onToolPlaced = () => {
       if (imageId.value) {
diff --git a/src/components/vtk/VtkCineScrubKeyManipulator.vue b/src/components/vtk/VtkCineScrubKeyManipulator.vue
index abca10eb7..c94e1d260 100644
--- a/src/components/vtk/VtkCineScrubKeyManipulator.vue
+++ b/src/components/vtk/VtkCineScrubKeyManipulator.vue
@@ -7,10 +7,10 @@ import { Maybe } from '@/src/types';
 import vtkGatedMouseRangeManipulator from '@/src/vtk/GatedMouseRangeManipulator';
 import { IMouseRangeManipulatorInitialValues } from '@kitware/vtk.js/Interaction/Manipulators/MouseRangeManipulator';
 import vtkInteractorStyleManipulator from '@kitware/vtk.js/Interaction/Style/InteractorStyleManipulator';
-import { syncRef, useMagicKeys } from '@vueuse/core';
+import { syncRef } from '@vueuse/core';
 import { inject, toRefs, unref, watch, computed } from 'vue';
 import { useViewStore } from '@/src/store/views';
-import { actionToKey } from '@/src/composables/useKeyboardShortcuts';
+import { useActionHeld } from '@/src/composables/useKeyboardShortcuts';
 
 type Props = {
   viewId: string;
@@ -45,8 +45,7 @@ const { instance: rangeManipulator } = useVtkInteractionManipulator(
 
 rangeManipulator.value.setupMouseMove(view.interactor);
 
-const keys = useMagicKeys();
-const enableGrabSlice = computed(() => keys[actionToKey.value.grabSlice].value);
+const enableGrabSlice = useActionHeld('grabSlice');
 watch(
   enableGrabSlice,
   (value) => {
diff --git a/src/components/vtk/VtkSliceViewSlicingKeyManipulator.vue b/src/components/vtk/VtkSliceViewSlicingKeyManipulator.vue
index 87c916cad..32e7a8e75 100644
--- a/src/components/vtk/VtkSliceViewSlicingKeyManipulator.vue
+++ b/src/components/vtk/VtkSliceViewSlicingKeyManipulator.vue
@@ -8,10 +8,10 @@ import { LPSAxisDir } from '@/src/types/lps';
 import vtkGatedMouseRangeManipulator from '@/src/vtk/GatedMouseRangeManipulator';
 import { IMouseRangeManipulatorInitialValues } from '@kitware/vtk.js/Interaction/Manipulators/MouseRangeManipulator';
 import vtkInteractorStyleManipulator from '@kitware/vtk.js/Interaction/Style/InteractorStyleManipulator';
-import { syncRef, useMagicKeys } from '@vueuse/core';
+import { syncRef } from '@vueuse/core';
 import { inject, toRefs, unref, watch, computed } from 'vue';
 import { useViewStore } from '@/src/store/views';
-import { actionToKey } from '@/src/composables/useKeyboardShortcuts';
+import { useActionHeld } from '@/src/composables/useKeyboardShortcuts';
 
 type Props = {
   viewId: string;
@@ -49,8 +49,7 @@ const { instance: rangeManipulator } = useVtkInteractionManipulator(
 
 rangeManipulator.value.setupMouseMove(view.interactor);
 
-const keys = useMagicKeys();
-const enableGrabSlice = computed(() => keys[actionToKey.value.grabSlice].value);
+const enableGrabSlice = useActionHeld('grabSlice');
 watch(
   enableGrabSlice,
   (value) => {
diff --git a/src/composables/__tests__/deleteSelectedAnnotations.spec.ts b/src/composables/__tests__/deleteSelectedAnnotations.spec.ts
new file mode 100644
index 000000000..bc4bab3a9
--- /dev/null
+++ b/src/composables/__tests__/deleteSelectedAnnotations.spec.ts
@@ -0,0 +1,106 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { setActivePinia, createPinia } from 'pinia';
+import { effectScope, nextTick } from 'vue';
+import vtkImageData from '@kitware/vtk.js/Common/DataModel/ImageData';
+
+import { useImageCacheStore } from '@/src/store/image-cache';
+import { AnnotationToolType } from '@/src/store/tools/types';
+import { useToolSelectionStore } from '@/src/store/tools/toolSelection';
+import { useRulerStore } from '@/src/store/tools/rulers';
+import { useKeyboardShortcuts } from '@/src/composables/useKeyboardShortcuts';
+
+const IMAGE_ID = 'img-1';
+
+/** Presses delete under a live listener, then tears it down. */
+const pressDelete = async () => {
+  const scope = effectScope();
+  scope.run(() => useKeyboardShortcuts());
+
+  // a real keystroke starts at the focused element and bubbles to window
+  document.activeElement?.dispatchEvent(
+    new KeyboardEvent('keydown', {
+      key: 'Delete',
+      bubbles: true,
+      cancelable: true,
+    })
+  );
+  await nextTick();
+
+  scope.stop();
+};
+
+const addSelectedRuler = () => {
+  const id = useRulerStore().addTool({
+    imageID: IMAGE_ID,
+    placing: false,
+    firstPoint: [1, 1, 1],
+    secondPoint: [2, 2, 2],
+  });
+  useToolSelectionStore().addSelection(id, AnnotationToolType.Ruler);
+  return id;
+};
+
+describe('delete key removes selected annotations', () => {
+  beforeEach(async () => {
+    setActivePinia(createPinia());
+    useImageCacheStore().addVTKImageData(vtkImageData.newInstance(), 'CT', {
+      id: IMAGE_ID,
+    });
+    await nextTick();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('removes the selected annotation when delete is pressed', async () => {
+    const ruler = addSelectedRuler();
+
+    await pressDelete();
+
+    expect(useRulerStore().toolByID).not.toHaveProperty(ruler);
+    expect(useToolSelectionStore().selection).toEqual([]);
+  });
+
+  it('keeps unselected annotations when delete is pressed', async () => {
+    const rulerStore = useRulerStore();
+    const kept = rulerStore.addTool({
+      imageID: IMAGE_ID,
+      placing: false,
+      firstPoint: [3, 3, 3],
+      secondPoint: [4, 4, 4],
+    });
+    const selected = addSelectedRuler();
+
+    await pressDelete();
+
+    expect(rulerStore.toolByID).not.toHaveProperty(selected);
+    expect(rulerStore.toolByID).toHaveProperty(kept);
+  });
+
+  it('ignores the delete key while typing in a text field', async () => {
+    const ruler = addSelectedRuler();
+
+    const input = document.createElement('input');
+    document.body.appendChild(input);
+    input.focus();
+
+    await pressDelete();
+
+    expect(useRulerStore().toolByID).toHaveProperty(ruler);
+  });
+
+  // Checking a row in the annotations panel leaves focus on its checkbox
+  it('removes the annotation while a checkbox holds focus', async () => {
+    const ruler = addSelectedRuler();
+
+    const checkbox = document.createElement('input');
+    checkbox.type = 'checkbox';
+    document.body.appendChild(checkbox);
+    checkbox.focus();
+
+    await pressDelete();
+
+    expect(useRulerStore().toolByID).not.toHaveProperty(ruler);
+  });
+});
diff --git a/src/composables/__tests__/useKeyboardShortcuts.spec.ts b/src/composables/__tests__/useKeyboardShortcuts.spec.ts
index f8607e455..f7655c5f2 100644
--- a/src/composables/__tests__/useKeyboardShortcuts.spec.ts
+++ b/src/composables/__tests__/useKeyboardShortcuts.spec.ts
@@ -1,25 +1,335 @@
-import { describe, expect, it } from 'vitest';
-import { shouldIgnoreKeyboardShortcuts } from '../useKeyboardShortcuts';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { effectScope, nextTick } from 'vue';
+import {
+  actionToKey,
+  shouldIgnoreKeyboardShortcuts,
+  splitChord,
+  useKeyboardShortcuts,
+} from '../useKeyboardShortcuts';
+import { ACTIONS, type Action } from '@/src/constants';
+import { getEntries } from '@/src/utils';
+
+// The dispatcher's job is choosing an action, so the test supplies a map that
+// records the choice instead of the real actions, which would drag in the
+// stores and views each one drives.
+const firedActions: Action[] = [];
+const recordAction = Object.fromEntries(
+  getEntries(ACTIONS).map(([action]) => [
+    action,
+    () => {
+      firedActions.push(action);
+    },
+  ])
+) as Record<Action, () => void>;
+
+const input = (type?: string) => {
+  const element = document.createElement('input');
+  if (type) element.type = type;
+  return element;
+};
+
+const contentEditable = () => {
+  const element = document.createElement('div');
+  element.contentEditable = 'true';
+  return element;
+};
+
+const withRole = (role: string) => {
+  const element = document.createElement('div');
+  element.setAttribute('role', role);
+  return element;
+};
+
+const insideTextbox = () => {
+  const child = document.createElement('span');
+  withRole('textbox').appendChild(child);
+  return child;
+};
 
 describe('shouldIgnoreKeyboardShortcuts', () => {
-  it('ignores shortcuts while an input is focused', () => {
-    const input = document.createElement('input');
-    expect(shouldIgnoreKeyboardShortcuts(input)).toBe(true);
+  describe('text entry keeps the keys it types with', () => {
+    it.each(['m', 'delete', 'backspace', 'arrowdown', 'home', '?'])(
+      'yields %s to a text input',
+      (binding) => {
+        expect(shouldIgnoreKeyboardShortcuts(binding, input('text'))).toBe(
+          true
+        );
+      }
+    );
+
+    it('yields to a text input with no explicit type', () => {
+      expect(shouldIgnoreKeyboardShortcuts('m', input())).toBe(true);
+    });
+
+    it('yields to a textarea', () => {
+      expect(
+        shouldIgnoreKeyboardShortcuts('m', document.createElement('textarea'))
+      ).toBe(true);
+    });
+
+    it('yields to a contenteditable element', () => {
+      expect(shouldIgnoreKeyboardShortcuts('m', contentEditable())).toBe(true);
+    });
+
+    it('yields to a role=textbox element', () => {
+      expect(shouldIgnoreKeyboardShortcuts('m', withRole('textbox'))).toBe(
+        true
+      );
+    });
+
+    it('yields for an element nested inside a textbox control', () => {
+      expect(shouldIgnoreKeyboardShortcuts('m', insideTextbox())).toBe(true);
+    });
+
+    it('yields enter to a textarea, which takes it as a newline', () => {
+      expect(
+        shouldIgnoreKeyboardShortcuts(
+          'enter',
+          document.createElement('textarea')
+        )
+      ).toBe(true);
+    });
+
+    it.each([
+      ['down', 'arrowdown'],
+      ['up', 'arrowup'],
+      ['left', 'arrowleft'],
+      ['right', 'arrowright'],
+    ])('yields %s, the alias vueuse fires as %s', (binding) => {
+      expect(shouldIgnoreKeyboardShortcuts(binding, input('text'))).toBe(true);
+    });
+
+    it('yields the arrow keys to a number input, which steps with them', () => {
+      expect(shouldIgnoreKeyboardShortcuts('arrowup', input('number'))).toBe(
+        true
+      );
+    });
+
+    it('treats a hyphen chord as a shift combination, not a bare key', () => {
+      expect(shouldIgnoreKeyboardShortcuts('shift-c', input('text'))).toBe(
+        true
+      );
+    });
+  });
+
+  describe('modifier chords are judged by their final key', () => {
+    it.each(['ctrl+.', 'ctrl+/', 'meta+k'])(
+      'yields %s to a text input',
+      (binding) => {
+        expect(shouldIgnoreKeyboardShortcuts(binding, input('text'))).toBe(
+          true
+        );
+      }
+    );
+
+    it.each(['ctrl+.', 'ctrl+/', 'meta+k'])(
+      'runs %s while a checkbox holds focus',
+      (binding) => {
+        expect(shouldIgnoreKeyboardShortcuts(binding, input('checkbox'))).toBe(
+          false
+        );
+      }
+    );
+  });
+
+  describe('checkboxes and buttons only answer to space and enter', () => {
+    it.each(['delete', 'm', 'arrowdown', '?'])(
+      'runs %s while a checkbox holds focus',
+      (binding) => {
+        expect(shouldIgnoreKeyboardShortcuts(binding, input('checkbox'))).toBe(
+          false
+        );
+      }
+    );
+
+    it.each(['space', 'enter'])('yields %s to a checkbox', (binding) => {
+      expect(shouldIgnoreKeyboardShortcuts(binding, input('checkbox'))).toBe(
+        true
+      );
+    });
+
+    it('runs a shortcut while a button holds focus', () => {
+      expect(
+        shouldIgnoreKeyboardShortcuts(
+          'delete',
+          document.createElement('button')
+        )
+      ).toBe(false);
+    });
+  });
+
+  describe('controls that step through values keep the arrow keys', () => {
+    it('yields arrowdown to a radio input', () => {
+      expect(shouldIgnoreKeyboardShortcuts('arrowdown', input('radio'))).toBe(
+        true
+      );
+    });
+
+    it('runs a letter shortcut over a radio input', () => {
+      expect(shouldIgnoreKeyboardShortcuts('m', input('radio'))).toBe(false);
+    });
+
+    it('yields arrowup to a range input', () => {
+      expect(shouldIgnoreKeyboardShortcuts('arrowup', input('range'))).toBe(
+        true
+      );
+    });
+
+    it('runs a letter shortcut over a range input', () => {
+      expect(shouldIgnoreKeyboardShortcuts('m', input('range'))).toBe(false);
+    });
+
+    // v-slider claims the arrow keys by calling preventDefault, so the
+    // dispatcher yields to it on the event rather than on the element; see
+    // 'stands aside when the control already handled the key' below
+    it('runs a letter shortcut over a slider thumb', () => {
+      expect(shouldIgnoreKeyboardShortcuts('m', withRole('slider'))).toBe(
+        false
+      );
+    });
+
+    it('runs delete over a slider thumb', () => {
+      expect(shouldIgnoreKeyboardShortcuts('delete', withRole('slider'))).toBe(
+        false
+      );
+    });
+  });
+
+  it('runs shortcuts when nothing is focused', () => {
+    expect(shouldIgnoreKeyboardShortcuts('m', null)).toBe(false);
+  });
+});
+
+describe('splitChord', () => {
+  it.each([
+    ['ctrl+.', ['ctrl', '.']],
+    ['shift-c', ['shift', 'c']],
+    ['ctrl_alt+k', ['ctrl', 'alt', 'k']],
+    ['delete', ['delete']],
+  ])('splits %s on any separator vueuse accepts', (binding, keys) => {
+    expect(splitChord(binding)).toEqual(keys);
+  });
+
+  it.each(['-', '+', '_'])(
+    'reads a lone %s as a key, not a separator',
+    (key) => {
+      expect(splitChord(key)).toEqual([key]);
+    }
+  );
+
+  it('keeps the case of the binding', () => {
+    expect(splitChord('Shift')).toEqual(['Shift']);
+  });
+});
+
+describe('the dispatcher', () => {
+  // a real keystroke starts at the focused element, bubbles, and is cancelable
+  const press = (
+    init: KeyboardEventInit,
+    target: EventTarget = document.body
+  ) => {
+    const event = new KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      ...init,
+    });
+    target.dispatchEvent(event);
+    return event;
+  };
+
+  const withShortcuts = async (typeKeys: () => void) => {
+    const scope = effectScope();
+    scope.run(() => useKeyboardShortcuts(recordAction));
+    typeKeys();
+    await nextTick();
+    scope.stop();
+  };
+
+  const baseline = { ...actionToKey.value };
+
+  beforeEach(() => {
+    firedActions.length = 0;
+    actionToKey.value = { ...baseline };
+    document.body.innerHTML = '';
+  });
+
+  it('runs the action bound to a bare key', async () => {
+    await withShortcuts(() => press({ key: 'm' }));
+    expect(firedActions).toContain('ruler');
+  });
+
+  it('runs a modifier chord', async () => {
+    await withShortcuts(() => press({ key: '.', ctrlKey: true }));
+    expect(firedActions).toContain('deleteCurrentImage');
   });
 
-  it('ignores shortcuts while a textarea is focused', () => {
-    const textarea = document.createElement('textarea');
-    expect(shouldIgnoreKeyboardShortcuts(textarea)).toBe(true);
+  it('runs a chord whose character already carries the shift', async () => {
+    await withShortcuts(() => press({ key: '?', shiftKey: true }));
+    expect(firedActions).toContain('showKeyboardShortcuts');
   });
 
-  it('ignores shortcuts while a contenteditable element is focused', () => {
-    const editable = document.createElement('div');
-    editable.contentEditable = 'true';
-    expect(shouldIgnoreKeyboardShortcuts(editable)).toBe(true);
+  it('answers every binding in a list', async () => {
+    actionToKey.value = { ...baseline, polygon: ['g', 'F9'] };
+    await withShortcuts(() => press({ key: 'F9' }));
+    expect(firedActions).toContain('polygon');
   });
 
-  it('does not ignore shortcuts for non-editable controls', () => {
-    const button = document.createElement('button');
-    expect(shouldIgnoreKeyboardShortcuts(button)).toBe(false);
+  // the main delete key reports Backspace on macOS
+  it('deletes on backspace as well as delete', async () => {
+    await withShortcuts(() => press({ key: 'Backspace' }));
+    expect(firedActions).toContain('deleteSelectedAnnotations');
+  });
+
+  it('runs a shift chord bound with a lowercase key', async () => {
+    actionToKey.value = { ...baseline, polygon: 'shift-g' };
+    await withShortcuts(() => press({ key: 'G', shiftKey: true }));
+    expect(firedActions).toContain('polygon');
+  });
+
+  it('leaves a bare-letter binding alone while shift is held', async () => {
+    await withShortcuts(() => press({ key: 'G', shiftKey: true }));
+    expect(firedActions).not.toContain('polygon');
+  });
+
+  it('leaves a chord alone when an extra modifier is held', async () => {
+    await withShortcuts(() => press({ key: '.', ctrlKey: true, altKey: true }));
+    expect(firedActions).not.toContain('deleteCurrentImage');
+  });
+
+  // the hold behaviors read their key as state in the views, so their action is
+  // a no-op here; the dispatcher matching them changes nothing
+  it('leaves a modifier-only binding to the views that read it', async () => {
+    await withShortcuts(() => press({ key: 'Shift', shiftKey: true }));
+    expect(firedActions).not.toContain('mergeNewPolygon');
+  });
+
+  it('stands aside when the control already handled the key', async () => {
+    const thumb = withRole('slider');
+    document.body.appendChild(thumb);
+    thumb.addEventListener('keydown', (event) => event.preventDefault());
+
+    await withShortcuts(() => press({ key: 'm' }, thumb));
+    expect(firedActions).not.toContain('ruler');
+  });
+
+  it('suppresses the control default once a shortcut runs', async () => {
+    let event: KeyboardEvent | undefined;
+    await withShortcuts(() => {
+      event = press({ key: 'm' });
+    });
+    expect(firedActions).toContain('ruler');
+    expect(event!.defaultPrevented).toBe(true);
+  });
+
+  // Vuetify moves focus inside its own keydown handlers, so the element that
+  // received the key is the one to arbitrate against
+  it('arbitrates on the element the key reached, not on later focus', async () => {
+    const field = input('text');
+    const elsewhere = document.createElement('button');
+    document.body.append(field, elsewhere);
+    field.addEventListener('keydown', () => elsewhere.focus());
+
+    await withShortcuts(() => press({ key: 'm' }, field));
+    expect(firedActions).not.toContain('ruler');
   });
 });
diff --git a/src/composables/actions.ts b/src/composables/actions.ts
index 1836a072c..1da140678 100644
--- a/src/composables/actions.ts
+++ b/src/composables/actions.ts
@@ -1,4 +1,4 @@
-import { useToolStore } from '../store/tools';
+import { removeSelectedTools, useToolStore } from '../store/tools';
 import { Tools } from '../store/tools/types';
 import { useRectangleStore } from '../store/tools/rectangles';
 import { useRulerStore } from '../store/tools/rulers';
@@ -112,6 +112,8 @@ export const ACTION_TO_FUNC = {
   decrementLabel: applyLabelOffset(-1),
   incrementLabel: applyLabelOffset(1),
 
+  deleteSelectedAnnotations: removeSelectedTools,
+
   deleteCurrentImage: deleteCurrentImage(),
   clearScene: clearScene(),
 
diff --git a/src/composables/useKeyboardShortcuts.ts b/src/composables/useKeyboardShortcuts.ts
index 04d653369..85a312e39 100644
--- a/src/composables/useKeyboardShortcuts.ts
+++ b/src/composables/useKeyboardShortcuts.ts
@@ -1,63 +1,231 @@
-import { ref, watch } from 'vue';
-import { useMagicKeys, whenever } from '@vueuse/core';
+import { computed, ref, watch } from 'vue';
+import {
+  DefaultMagicKeysAliasMap,
+  onKeyStroke,
+  useMagicKeys,
+} from '@vueuse/core';
 
-import { getEntries } from '../utils';
+import { getEntries, wrapInArray } from '../utils';
 import { ACTION_TO_KEY } from '../config';
+import type { Action, Binding } from '../constants';
 import { ACTION_TO_FUNC } from './actions';
 
-export const actionToKey = ref(ACTION_TO_KEY);
+export const actionToKey = ref<Record<Action, Binding>>(ACTION_TO_KEY);
 
-export function shouldIgnoreKeyboardShortcuts(
-  activeElement: Element | null = document.activeElement
-) {
+/**
+ * The bindings an action answers to. A binding may be written as a list when a
+ * key reaches the action under more than one name, as the main delete key does
+ * on macOS, where it reports Backspace.
+ */
+export const bindingsOf = (binding: Binding) => wrapInArray(binding);
+
+/** How a binding reads in the UI, naming every key that reaches the action. */
+export const readableBinding = (binding: Binding) =>
+  bindingsOf(binding).join(' or ');
+
+/**
+ * Splits a binding into its keys. vueuse resolves any of + _ - as a chord
+ * separator, so a binding that is itself one of those characters is a lone key.
+ */
+export const splitChord = (binding: string) =>
+  binding.length === 1 ? [binding] : binding.split(/[+_-]/);
+
+/**
+ * True when a binding can ever fire. A chord separator in key position, as in
+ * 'ctrl+-', splits into an empty key that no keystroke produces.
+ */
+export const isDispatchable = (binding: string) =>
+  splitChord(binding).every((part) => part.length > 0);
+
+/**
+ * Tracks whether an action's key is currently held. Hold actions are read as
+ * state by the views rather than dispatched, so they answer to any of their
+ * bindings being down.
+ */
+export const useActionHeld = (action: Action) => {
+  const keys = useMagicKeys();
+  return computed(() =>
+    bindingsOf(actionToKey.value[action]).some((binding) => keys[binding].value)
+  );
+};
+
+/**
+ * Resolves the aliases vueuse accepts in a binding, so a shortcut bound to
+ * 'down' is recognized as the arrow key it fires on.
+ */
+const resolveAlias = (key: string) => DefaultMagicKeysAliasMap[key] ?? key;
+
+// KeyboardEvent reports the space bar as a literal space; vueuse's alias map
+// covers the rest of the shorthands a binding may use.
+const resolveEventKey = (key: string) =>
+  key === 'space' ? ' ' : resolveAlias(key);
+
+/**
+ * A binding split into the modifiers it requires and the key that completes it.
+ * Modifiers are normalized to the names KeyboardEvent reports. The final key
+ * keeps its case, which is what separates a 'g' binding from a shifted 'G'.
+ */
+const parseBinding = (binding: string) => {
+  const chord = splitChord(binding);
+  const finalKey = chord[chord.length - 1];
+  const aliased = resolveEventKey(finalKey.toLowerCase());
+
+  return {
+    modifiers: new Set(
+      chord.slice(0, -1).map((key) => resolveAlias(key.toLowerCase()))
+    ),
+    // an alias only ever names a non-printable key, so a key that resolves to
+    // itself is the one whose case still matters
+    key: aliased === finalKey.toLowerCase() ? finalKey : aliased,
+  };
+};
+
+const modifiersOf = (event: KeyboardEvent) =>
+  new Set(
+    [
+      event.ctrlKey && 'control',
+      event.shiftKey && 'shift',
+      event.altKey && 'alt',
+      event.metaKey && 'meta',
+    ].filter((modifier): modifier is string => !!modifier)
+  );
+
+const sameKeys = (a: Set<string>, b: Set<string>) =>
+  a.size === b.size && [...a].every((key) => b.has(key));
+
+/**
+ * True when a keystroke completes this binding. Shift is the subtle case: it
+ * both produces a different character and changes a letter's case, so the two
+ * branches below judge it differently.
+ */
+const matchesBinding = (
+  { modifiers, key }: ReturnType<typeof parseBinding>,
+  event: KeyboardEvent
+) => {
+  const printable = key.length === 1;
+  const needsShift = modifiers.has('shift');
+  const pressed = modifiersOf(event);
+
+  // Shift is already baked into a printable character, since Shift+/ arrives
+  // as '?', so a binding that does not name shift must not be judged on it.
+  if (printable && !needsShift) {
+    pressed.delete('shift');
+    return sameKeys(modifiers, pressed) && key === event.key;
+  }
+
+  // Shift is also what changes a letter's case, so a binding that names it
+  // matches regardless of the case the character arrives in.
+  return (
+    sameKeys(modifiers, pressed) &&
+    key.toLowerCase() === event.key.toLowerCase()
+  );
+};
+
+// Anything a control handles in script reports itself through preventDefault,
+// so the arbitration below only has to cover what the browser does natively and
+// no handler announces: typing into a field, Space or Enter activating a
+// focused control, and the arrow keys stepping through a group of values.
+
+// input carries both kinds: everything not listed here takes typed characters.
+const NON_TEXT_INPUT_TYPES = new Set(
+  'button checkbox color file image radio range reset submit'.split(' ')
+);
+const TEXT_ENTRY_SELECTOR = 'input, textarea, [role="textbox"]';
+
+const ARROW_KEYS = ['up', 'down', 'left', 'right'].map(
+  (direction) => `arrow${direction}`
+);
+
+// The keys a control acts on natively, paired with the controls that claim them.
+const NATIVE_KEY_CLAIMS = [
+  { keys: ['enter', ' '], selector: 'input, select, button, [role="button"]' },
+  {
+    keys: ARROW_KEYS,
+    selector: 'input[type="radio"], input[type="range"], select',
+  },
+].map(({ keys, selector }) => ({ keys: new Set(keys), selector }));
+
+const isTextEntry = (element: HTMLElement) => {
+  if (element.isContentEditable) return true;
+
+  const control = element.closest(TEXT_ENTRY_SELECTOR);
+  if (!control) return false;
+  return !(
+    control instanceof HTMLInputElement &&
+    NON_TEXT_INPUT_TYPES.has(control.type)
+  );
+};
+
+/**
+ * True when the focused control would act on this key itself, so the shortcut
+ * must stand aside. Takes the key a keystroke reports, not a binding.
+ */
+const keyClaimedByFocus = (key: string, activeElement: Element | null) => {
   if (!(activeElement instanceof HTMLElement)) {
     return false;
   }
+  if (isTextEntry(activeElement)) {
+    return true;
+  }
 
-  return (
-    activeElement.isContentEditable ||
-    activeElement.closest('input, textarea, select, [role="textbox"]') !== null
+  const pressed = key.toLowerCase();
+  return NATIVE_KEY_CLAIMS.some(
+    ({ keys, selector }) =>
+      keys.has(pressed) && activeElement.closest(selector) !== null
   );
-}
+};
 
-export function useKeyboardShortcuts() {
-  const keys = useMagicKeys();
-  let unwatchFuncs = [] as Array<ReturnType<typeof whenever>>;
+/**
+ * Whether a binding must stand aside for the focused control. A chord is judged
+ * by its final key, so ctrl+. yields to a text field but runs over a checkbox.
+ */
+export const shouldIgnoreKeyboardShortcuts = (
+  binding: string,
+  activeElement: Element | null = document.activeElement
+) => keyClaimedByFocus(parseBinding(binding).key, activeElement);
+
+const parseBindings = (actionMap: Record<Action, Binding>) =>
+  getEntries(actionMap).flatMap(([action, configured]) =>
+    bindingsOf(configured).map((binding) => ({
+      action,
+      ...parseBinding(binding),
+    }))
+  );
+
+/**
+ * Runs the action a keystroke is bound to. Takes the action map so a caller can
+ * watch which action a key chose without standing in for the real ones.
+ */
+export function useKeyboardShortcuts(
+  actions: Record<Action, () => void> = ACTION_TO_FUNC
+) {
+  let bindings = parseBindings(actionToKey.value);
 
   watch(
     actionToKey,
     (actionMap) => {
-      unwatchFuncs.forEach((unwatch) => unwatch());
-
-      unwatchFuncs = getEntries(actionMap).map(([action, key]) => {
-        const individualKeys = key.split('+');
-        const lastKey = individualKeys[individualKeys.length - 1];
-
-        return whenever(keys[key], () => {
-          if (shouldIgnoreKeyboardShortcuts()) {
-            return;
-          }
-
-          const shiftPressed = keys.current.has('shift');
-          const lastPressedKey = Array.from(keys.current).pop();
-          const currentKeyWithCase = shiftPressed
-            ? (lastPressedKey?.toUpperCase() ?? lastPressedKey)
-            : lastPressedKey;
-
-          // keyCountMatches checks for exact modifier match
-          const keyCountMatches = keys.current.size === individualKeys.length;
-          const lastKeyMatches = lastKey === currentKeyWithCase;
-          const shiftCaseMatches =
-            shiftPressed &&
-            keys.current.size - 1 === individualKeys.length &&
-            lastKeyMatches;
-
-          if ((keyCountMatches && lastKeyMatches) || shiftCaseMatches) {
-            ACTION_TO_FUNC[action]();
-          }
-        });
-      });
+      bindings = parseBindings(actionMap);
+    },
+    { deep: true }
+  );
+
+  onKeyStroke(
+    (event) => {
+      // the focused control handled this key itself
+      if (event.defaultPrevented) return;
+
+      const hit = bindings.find((parsed) => matchesBinding(parsed, event));
+      if (!hit) return;
+
+      // arbitrate against the element the key was delivered to, not against
+      // wherever focus has moved by the time this runs
+      const target = event.target instanceof HTMLElement ? event.target : null;
+      if (keyClaimedByFocus(hit.key, target)) return;
+
+      event.preventDefault();
+      actions[hit.action]();
     },
-    { immediate: true, deep: true }
+    // a held key repeats; the shortcut already ran on the first press
+    { dedupe: true }
   );
 }
diff --git a/src/config.ts b/src/config.ts
index 7bfbfabf9..830ceee3c 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -8,7 +8,7 @@ import { SegmentMask } from '@/src/types/segment';
 import type { LayoutConfig } from './utils/layoutParsing';
 import type { ViewInfoInit } from './types/views';
 import { SampleDataset } from './types';
-import { Action } from './constants';
+import { Action, Binding } from './constants';
 
 /**
  * These are the initial view IDs.
@@ -222,11 +222,14 @@ export const ACTION_TO_KEY = {
   decrementLabel: 'q',
   incrementLabel: 'w',
 
+  // the main delete key reports Backspace on macOS
+  deleteSelectedAnnotations: ['delete', 'backspace'],
+
   deleteCurrentImage: 'ctrl+.',
   clearScene: 'ctrl+/',
 
   showKeyboardShortcuts: '?',
-} satisfies Record<Action, string>;
+} satisfies Record<Action, Binding>;
 
 export const DEFAULT_SEGMENT_MASKS: SegmentMask[] = [
   {
diff --git a/src/constants.ts b/src/constants.ts
index 6752cc03c..bc67f44c2 100644
--- a/src/constants.ts
+++ b/src/constants.ts
@@ -91,6 +91,10 @@ export const ACTIONS = {
     readable: 'Activate next label',
   },
 
+  deleteSelectedAnnotations: {
+    readable: 'Delete selected annotations',
+  },
+
   deleteCurrentImage: {
     readable: 'Remove current active image',
   },
@@ -111,6 +115,12 @@ export const ACTIONS = {
 
 export type Action = keyof typeof ACTIONS;
 
+/**
+ * What an action is bound to: one key chord, or several when the same action
+ * is reached by more than one key.
+ */
+export type Binding = string | string[];
+
 export const WLAutoRanges = {
   FullRange: 0,
   LowContrast: 1.0,
diff --git a/src/io/import/__tests__/configJson.spec.ts b/src/io/import/__tests__/configJson.spec.ts
index 5fc90a620..ac2ec03c8 100644
--- a/src/io/import/__tests__/configJson.spec.ts
+++ b/src/io/import/__tests__/configJson.spec.ts
@@ -28,6 +28,32 @@ describe('config schema', () => {
       expect(result.success).to.be.false;
     });
 
+    it('should accept a list of keys for one action', () => {
+      const result = config.safeParse({
+        shortcuts: {
+          deleteSelectedAnnotations: ['delete', 'backspace'],
+        },
+      });
+
+      expect(result.success).to.be.true;
+      expect(result.data?.shortcuts?.deleteSelectedAnnotations).to.deep.equal([
+        'delete',
+        'backspace',
+      ]);
+    });
+
+    // + - and _ separate the keys of a chord, so a binding with one in key
+    // position can never fire. It is dropped on apply, not rejected here,
+    // so the rest of the config still loads.
+    it.each(['ctrl+-', '-', 'shift+_'])(
+      'should still parse a config carrying the unbindable %s',
+      (binding) => {
+        const result = config.safeParse({ shortcuts: { polygon: binding } });
+
+        expect(result.success).to.be.true;
+      }
+    );
+
     it('should accept empty shortcuts', () => {
       const result = config.safeParse({
         shortcuts: {},
diff --git a/src/io/import/configJson.ts b/src/io/import/configJson.ts
index cd25c9650..e24bc0023 100644
--- a/src/io/import/configJson.ts
+++ b/src/io/import/configJson.ts
@@ -1,13 +1,25 @@
 import { z } from 'zod';
-import { isRecord, zodEnumFromObjKeys } from '@/src/utils';
+import {
+  getEntries,
+  isRecord,
+  partition,
+  plural,
+  zodEnumFromObjKeys,
+} from '@/src/utils';
 import { ACTIONS } from '@/src/constants';
+import type { Action, Binding } from '@/src/constants';
 
 import { useRectangleStore } from '@/src/store/tools/rectangles';
 import { useRulerStore } from '@/src/store/tools/rulers';
 import { usePolygonStore } from '@/src/store/tools/polygons';
 import { useViewStore } from '@/src/store/views';
 import { useWindowingStore } from '@/src/store/view-configs/windowing';
-import { actionToKey } from '@/src/composables/useKeyboardShortcuts';
+import {
+  actionToKey,
+  bindingsOf,
+  isDispatchable,
+} from '@/src/composables/useKeyboardShortcuts';
+import { surfaceWarning } from '@/src/store/messages';
 import { useSegmentGroupStore } from '@/src/store/segmentGroups';
 import { AnnotationToolStore } from '@/src/store/tools/useAnnotationTool';
 import useLoadDataStore from '@/src/store/load-data';
@@ -21,8 +33,10 @@ const layouts = z.record(z.string(), layoutConfig).optional();
 // --------------------------------------------------------------------------
 // Keyboard shortcuts
 
+const bindingSchema = z.union([z.string(), z.array(z.string())]);
+
 const shortcuts = z
-  .partialRecord(zodEnumFromObjKeys(ACTIONS), z.string())
+  .partialRecord(zodEnumFromObjKeys(ACTIONS), bindingSchema)
   .optional();
 
 // --------------------------------------------------------------------------
@@ -213,12 +227,42 @@ const applyLayout = (manifest: Config) => {
   viewStore.switchToNamedLayout(firstLayoutName);
 };
 
+/**
+ * Drops the bindings that could never fire, keeping the rest of the config.
+ * A shortcut that does nothing is worth a warning, not a rejected file.
+ */
+const dispatchableShortcuts = (
+  configured: NonNullable<Config['shortcuts']>
+) => {
+  const perAction = getEntries(configured).flatMap(([action, binding]) =>
+    binding
+      ? [[action, partition(isDispatchable, bindingsOf(binding))] as const]
+      : []
+  );
+
+  const undispatchable = perAction.flatMap(([, [, rejected]]) => rejected);
+  if (undispatchable.length) {
+    const noun = plural(undispatchable.length, 'shortcut');
+    surfaceWarning(
+      'Unbindable shortcut',
+      `Ignored unbindable ${noun}: ${undispatchable.join(', ')}. ` +
+        'The characters + - and _ separate the keys of a chord.'
+    );
+  }
+
+  return Object.fromEntries(
+    perAction
+      .filter(([, [usable]]) => usable.length)
+      .map(([action, [usable]]) => [action, usable])
+  ) as Partial<Record<Action, Binding>>;
+};
+
 const applyShortcuts = (manifest: Config) => {
   if (!manifest.shortcuts) return;
 
   actionToKey.value = {
     ...actionToKey.value,
-    ...manifest.shortcuts,
+    ...dispatchableShortcuts(manifest.shortcuts),
   };
 };
 
diff --git a/src/io/import/processors/handleConfig.ts b/src/io/import/processors/handleConfig.ts
index 5c8b1535d..79ec4bca7 100644
--- a/src/io/import/processors/handleConfig.ts
+++ b/src/io/import/processors/handleConfig.ts
@@ -2,7 +2,7 @@ import { ImportHandler, asConfigResult } from '@/src/io/import/common';
 import { ensureError, plural } from '@/src/utils';
 import { recognizeConfigFile } from '@/src/io/import/configJson';
 import { Skip } from '@/src/utils/evaluateChain';
-import { useMessageStore } from '@/src/store/messages';
+import { surfaceWarning } from '@/src/store/messages';
 
 // Forward-compat: a config that carries unknown top-level keys (e.g. a newer
 // config opened on an older client) still applies its known sections; the
@@ -13,8 +13,7 @@ const surfaceIgnoredConfigKeys = (ignoredKeys: string[]) => {
   const message = `Ignored unrecognized config ${label}: ${ignoredKeys.join(
     ', '
   )}.`;
-  console.warn(message);
-  useMessageStore().addWarning('Unrecognized configuration', message);
+  surfaceWarning('Unrecognized configuration', message);
 };
 
 /**
diff --git a/src/store/messages.ts b/src/store/messages.ts
index d97293ab6..de6ce86cb 100644
--- a/src/store/messages.ts
+++ b/src/store/messages.ts
@@ -139,3 +139,12 @@ export const useMessageStore = defineStore('message', {
     },
   },
 });
+
+/**
+ * Reports a warning both to the console and to the user. addWarning does not
+ * log on its own, unlike addError, so the two go together.
+ */
+export const surfaceWarning = (title: string, message: string) => {
+  console.warn(message);
+  useMessageStore().addWarning(title, message);
+};
diff --git a/src/store/tools/__tests__/removeSelectedTools.spec.ts b/src/store/tools/__tests__/removeSelectedTools.spec.ts
new file mode 100644
index 000000000..e455706c2
--- /dev/null
+++ b/src/store/tools/__tests__/removeSelectedTools.spec.ts
@@ -0,0 +1,121 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { useMessageStore } from '@/src/store/messages';
+import { setActivePinia, createPinia } from 'pinia';
+import { nextTick } from 'vue';
+import vtkImageData from '@kitware/vtk.js/Common/DataModel/ImageData';
+
+import { useImageCacheStore } from '@/src/store/image-cache';
+import { removeSelectedTools } from '@/src/store/tools';
+import { AnnotationToolType } from '@/src/store/tools/types';
+import { useToolSelectionStore } from '@/src/store/tools/toolSelection';
+import { useRulerStore } from '@/src/store/tools/rulers';
+import { useRectangleStore } from '@/src/store/tools/rectangles';
+import { usePolygonStore } from '@/src/store/tools/polygons';
+
+const IMAGE_ID = 'img-1';
+
+const seatImage = () =>
+  useImageCacheStore().addVTKImageData(vtkImageData.newInstance(), 'CT', {
+    id: IMAGE_ID,
+  });
+
+const addRuler = () =>
+  useRulerStore().addTool({
+    imageID: IMAGE_ID,
+    placing: false,
+    firstPoint: [1, 1, 1],
+    secondPoint: [2, 2, 2],
+  });
+
+const addRectangle = () =>
+  useRectangleStore().addTool({ imageID: IMAGE_ID, placing: false });
+
+const addPolygon = () =>
+  usePolygonStore().addTool({ imageID: IMAGE_ID, placing: false });
+
+describe('removeSelectedTools', () => {
+  beforeEach(async () => {
+    setActivePinia(createPinia());
+    seatImage();
+    await nextTick();
+  });
+
+  it('removes selected annotations from every tool store', () => {
+    const ruler = addRuler();
+    const rectangle = addRectangle();
+    const polygon = addPolygon();
+
+    const selectionStore = useToolSelectionStore();
+    selectionStore.addSelection(ruler, AnnotationToolType.Ruler);
+    selectionStore.addSelection(rectangle, AnnotationToolType.Rectangle);
+    selectionStore.addSelection(polygon, AnnotationToolType.Polygon);
+
+    removeSelectedTools();
+
+    expect(useRulerStore().toolByID).not.toHaveProperty(ruler);
+    expect(useRectangleStore().toolByID).not.toHaveProperty(rectangle);
+    expect(usePolygonStore().toolByID).not.toHaveProperty(polygon);
+  });
+
+  it('leaves unselected annotations in place', () => {
+    const doomed = addRuler();
+    const kept = addRuler();
+    const keptRectangle = addRectangle();
+
+    useToolSelectionStore().addSelection(doomed, AnnotationToolType.Ruler);
+
+    removeSelectedTools();
+
+    expect(useRulerStore().toolByID).not.toHaveProperty(doomed);
+    expect(useRulerStore().toolByID).toHaveProperty(kept);
+    expect(useRectangleStore().toolByID).toHaveProperty(keptRectangle);
+  });
+
+  it('empties the selection', () => {
+    const ruler = addRuler();
+    const selectionStore = useToolSelectionStore();
+    selectionStore.addSelection(ruler, AnnotationToolType.Ruler);
+
+    removeSelectedTools();
+
+    expect(selectionStore.selection).toEqual([]);
+    expect(selectionStore.isSelected(ruler)).toBe(false);
+  });
+
+  it('does nothing when nothing is selected', () => {
+    const ruler = addRuler();
+
+    removeSelectedTools();
+
+    expect(useRulerStore().toolByID).toHaveProperty(ruler);
+  });
+
+  // the selection can hold annotations with no visible cue in the current view
+  // (hidden, other slices, other axes) and there is no undo
+  it('reports how many annotations were deleted', () => {
+    const selectionStore = useToolSelectionStore();
+    selectionStore.addSelection(addRuler(), AnnotationToolType.Ruler);
+    selectionStore.addSelection(addRectangle(), AnnotationToolType.Rectangle);
+
+    removeSelectedTools();
+
+    const messages = useMessageStore().messages;
+    expect(messages.at(-1)?.title).toBe('Deleted 2 annotations');
+  });
+
+  it('uses the singular for a single deleted annotation', () => {
+    useToolSelectionStore().addSelection(addRuler(), AnnotationToolType.Ruler);
+
+    removeSelectedTools();
+
+    expect(useMessageStore().messages.at(-1)?.title).toBe(
+      'Deleted 1 annotation'
+    );
+  });
+
+  it('says nothing when nothing was deleted', () => {
+    removeSelectedTools();
+
+    expect(useMessageStore().messages).toHaveLength(0);
+  });
+});
diff --git a/src/store/tools/index.ts b/src/store/tools/index.ts
index daf7071bc..5f0bacdf8 100644
--- a/src/store/tools/index.ts
+++ b/src/store/tools/index.ts
@@ -8,8 +8,11 @@ import { useCrosshairsToolStore } from './crosshairs';
 import { usePaintToolStore } from './paint';
 import { useRulerStore } from './rulers';
 import { useRectangleStore } from './rectangles';
+import { useMessageStore } from '@/src/store/messages';
+import { plural } from '@/src/utils';
 import { AnnotationToolType, IToolStore, Tools } from './types';
 import { usePolygonStore } from './polygons';
+import { useToolSelectionStore } from './toolSelection';
 import { useViewStore } from '@/src/store/views';
 import {
   EffectiveView,
@@ -62,6 +65,36 @@ export function useAnnotationToolStore(
   return useStore();
 }
 
+/**
+ * Deletes every currently selected annotation, across all annotation types.
+ *
+ * removeTool() drops the tool from the selection as it goes, so iterate over a
+ * snapshot rather than the live selection.
+ */
+export function removeSelectedTools() {
+  const selectionStore = useToolSelectionStore();
+
+  // count what was actually removed: a selection entry can outlive its tool,
+  // and removeTool is a no-op for one that is already gone
+  const removed = [...selectionStore.selection].filter(({ id, type }) => {
+    const store = useAnnotationToolStore(type);
+    if (!(id in store.toolByID)) return false;
+    store.removeTool(id);
+    return true;
+  }).length;
+
+  // the selection can hold annotations with no visible cue in the current view
+  // (hidden, other slices, other axes) and there is no undo, so say what went
+  if (removed > 0) {
+    useMessageStore().addInfo(
+      `Deleted ${removed} ${plural(removed, 'annotation')}`
+    );
+  }
+
+  // clears any entry whose tool was already gone
+  selectionStore.clearSelection();
+}
+
 /**
  * Returns true if the tool is ready to be
  * activated. By default, a tool without a
diff --git a/tests/pageobjects/volview.page.ts b/tests/pageobjects/volview.page.ts
index 9cffa3be6..98af0144d 100644
--- a/tests/pageobjects/volview.page.ts
+++ b/tests/pageobjects/volview.page.ts
@@ -96,22 +96,18 @@ class VolViewPage extends Page {
     );
   }
 
-  get rectangleButton() {
-    return $('button span i[class~=mdi-vector-square]');
-  }
-
-  async activateRectangle() {
-    const button = this.rectangleButton;
+  async selectTool(icon: string) {
+    const button = $(`button span i[class~=${icon}]`);
+    await button.waitForClickable();
     await button.click();
   }
 
-  get paintButton() {
-    return $('button span i[class~=mdi-brush]');
+  async activateRectangle() {
+    await this.selectTool('mdi-vector-square');
   }
 
   async activatePaint() {
-    const button = this.paintButton;
-    await button.click();
+    await this.selectTool('mdi-brush');
   }
 
   // Paint "Process" mode and the Fill Holes process workflow.
diff --git a/tests/specs/annotationTestUtils.ts b/tests/specs/annotationTestUtils.ts
new file mode 100644
index 000000000..457f7a100
--- /dev/null
+++ b/tests/specs/annotationTestUtils.ts
@@ -0,0 +1,54 @@
+import { type ChainablePromiseElement } from 'webdriverio';
+import AppPage from '../pageobjects/volview.page';
+import { MINIMAL_DICOM } from './configTestUtils';
+import { openUrls } from './utils';
+
+const pointerAt = (x: number, y: number) =>
+  browser.action('pointer').move({ x: Math.round(x), y: Math.round(y) });
+
+export const moveTo = (x: number, y: number) => pointerAt(x, y).perform();
+
+export const clickAt = (x: number, y: number) =>
+  pointerAt(x, y).down().up().perform();
+
+export const rightClickAt = (x: number, y: number) =>
+  pointerAt(x, y).down({ button: 2 }).up({ button: 2 }).perform();
+
+/**
+ * Loads the minimal DICOM and returns the axial view with the center of its
+ * canvas in page coordinates.
+ */
+export const setupTest = async () => {
+  await openUrls([MINIMAL_DICOM]);
+
+  const views2D = await AppPage.getViews2D();
+  const axialView = views2D[0];
+  const canvas = await axialView.$('canvas');
+  const [location, size] = await Promise.all([
+    canvas.getLocation(),
+    canvas.getSize(),
+  ]);
+
+  return {
+    axialView,
+    centerX: location.x + size.width / 2,
+    centerY: location.y + size.height / 2,
+  };
+};
+
+// Handles of placed annotations
+export const getCircleCount = async (axialView: ChainablePromiseElement) => {
+  const circles = await axialView.$$('svg circle');
+  return circles.length;
+};
+
+export const waitForCircleCount = async (
+  axialView: ChainablePromiseElement,
+  expected: number,
+  timeoutMsg: string
+) => {
+  await browser.waitUntil(
+    async () => (await getCircleCount(axialView)) === expected,
+    { timeout: 5000, timeoutMsg }
+  );
+};
diff --git a/tests/specs/cineTestUtils.ts b/tests/specs/cineTestUtils.ts
index 8f25786f6..5648beea2 100644
--- a/tests/specs/cineTestUtils.ts
+++ b/tests/specs/cineTestUtils.ts
@@ -47,10 +47,4 @@ export const getCineCanvasCenter = async () => {
   };
 };
 
-export const clickAt = (x: number, y: number) =>
-  browser
-    .action('pointer')
-    .move({ x: Math.round(x), y: Math.round(y) })
-    .down()
-    .up()
-    .perform();
+export { clickAt } from './annotationTestUtils';
diff --git a/tests/specs/delete-selected-annotation.e2e.ts b/tests/specs/delete-selected-annotation.e2e.ts
new file mode 100644
index 000000000..8049dff73
--- /dev/null
+++ b/tests/specs/delete-selected-annotation.e2e.ts
@@ -0,0 +1,147 @@
+import { type ChainablePromiseElement } from 'webdriverio';
+import AppPage from '../pageobjects/volview.page';
+import {
+  clickAt,
+  moveTo,
+  setupTest,
+  waitForCircleCount,
+} from './annotationTestUtils';
+
+// BoundingRectangle.vue draws this around the selected annotation
+const getSelectionRectCount = async (axialView: ChainablePromiseElement) => {
+  const rects = await axialView.$$('svg rect[stroke="lightgray"]');
+  return rects.length;
+};
+
+const clickToSelect = async (
+  axialView: ChainablePromiseElement,
+  x: number,
+  y: number
+) => {
+  await AppPage.selectTool('mdi-cursor-default');
+  // The widget manager resolves what is under the cursor from a render pass
+  // driven by mouse move, so hover first and retry until the click picks it up.
+  await moveTo(x, y);
+  await browser.waitUntil(
+    async () => {
+      await clickAt(x, y);
+      return (await getSelectionRectCount(axialView)) === 1;
+    },
+    {
+      timeout: 10000,
+      interval: 500,
+      timeoutMsg: 'Clicking the annotation should draw a selection rectangle',
+    }
+  );
+};
+
+const pressDelete = () => browser.keys(['Delete']);
+
+const placeRectangle = async (cx: number, cy: number, halfSize: number) => {
+  await AppPage.selectTool('mdi-vector-square');
+  await clickAt(cx - halfSize, cy - halfSize);
+  await clickAt(cx + halfSize, cy + halfSize);
+};
+
+const TOOL_CASES = [
+  {
+    tool: 'ruler',
+    icon: 'mdi-ruler',
+    points: [
+      [-60, -60],
+      [60, 60],
+    ],
+    handles: 2,
+  },
+  {
+    tool: 'rectangle',
+    icon: 'mdi-vector-square',
+    points: [
+      [-80, -80],
+      [80, 80],
+    ],
+    handles: 2,
+  },
+  {
+    tool: 'polygon',
+    icon: 'mdi-pentagon-outline',
+    points: [
+      [-80, -80],
+      [80, -80],
+      [80, 80],
+      [-80, -80], // close
+    ],
+    handles: 3,
+  },
+];
+
+describe('Delete key on a selected annotation', () => {
+  TOOL_CASES.forEach(({ tool, icon, points, handles }) => {
+    it(`deletes a selected ${tool}`, async () => {
+      const { axialView, centerX, centerY } = await setupTest();
+
+      await AppPage.selectTool(icon);
+      for (const [dx, dy] of points) {
+        await clickAt(centerX + dx, centerY + dy);
+      }
+      await waitForCircleCount(
+        axialView,
+        handles,
+        `${tool} should have ${handles} handles`
+      );
+
+      const [firstX, firstY] = points[0];
+      await clickToSelect(axialView, centerX + firstX, centerY + firstY);
+      await pressDelete();
+
+      await waitForCircleCount(
+        axialView,
+        0,
+        `Delete should remove the ${tool}`
+      );
+      expect(await getSelectionRectCount(axialView)).toBe(0);
+    });
+  });
+
+  // Checking a row in the annotations panel leaves focus on its checkbox, which
+  // must not swallow the delete key
+  it('deletes an annotation selected from the annotations panel', async () => {
+    const { axialView, centerX, centerY } = await setupTest();
+
+    await placeRectangle(centerX, centerY, 80);
+    await waitForCircleCount(axialView, 2, 'Rectangle should have two handles');
+
+    const annotationsTab = await AppPage.annotationsModuleTab;
+    await annotationsTab.waitForClickable();
+    await annotationsTab.click();
+
+    const rowCheckbox = await $('.v-list-item .v-selection-control__input');
+    await rowCheckbox.waitForClickable();
+    await rowCheckbox.click();
+
+    await pressDelete();
+
+    await waitForCircleCount(
+      axialView,
+      0,
+      'Delete should work while the panel checkbox holds focus'
+    );
+  });
+
+  it('keeps unselected annotations', async () => {
+    const { axialView, centerX, centerY } = await setupTest();
+
+    await placeRectangle(centerX - 80, centerY - 80, 40);
+    await placeRectangle(centerX + 80, centerY + 80, 40);
+    await waitForCircleCount(axialView, 4, 'Two rectangles should be placed');
+
+    await clickToSelect(axialView, centerX - 120, centerY - 120);
+    await pressDelete();
+
+    await waitForCircleCount(
+      axialView,
+      2,
+      'Delete should remove only the selected rectangle'
+    );
+  });
+});
diff --git a/tests/specs/polygon-nested-interaction.e2e.ts b/tests/specs/polygon-nested-interaction.e2e.ts
index 0e7fb9706..5a81dc93a 100644
--- a/tests/specs/polygon-nested-interaction.e2e.ts
+++ b/tests/specs/polygon-nested-interaction.e2e.ts
@@ -1,61 +1,16 @@
 import { type ChainablePromiseElement } from 'webdriverio';
 import AppPage from '../pageobjects/volview.page';
-import { MINIMAL_DICOM } from './configTestUtils';
-
-// Low-level mouse helpers
-const clickAt = async (x: number, y: number) => {
-  await browser
-    .action('pointer')
-    .move({ x: Math.round(x), y: Math.round(y) })
-    .down()
-    .up()
-    .perform();
-};
-
-const rightClickAt = async (x: number, y: number) => {
-  await browser
-    .action('pointer')
-    .move({ x: Math.round(x), y: Math.round(y) })
-    .down({ button: 2 })
-    .up({ button: 2 })
-    .perform();
-};
-
-const moveTo = async (x: number, y: number) => {
-  await browser
-    .action('pointer')
-    .move({ x: Math.round(x), y: Math.round(y) })
-    .perform();
-};
-
-// Test setup
-const setupTest = async () => {
-  await AppPage.open(`?urls=${MINIMAL_DICOM.url}&names=${MINIMAL_DICOM.name}`);
-  await AppPage.waitForViews();
-
-  const views2D = await AppPage.getViews2D();
-  const axialView = views2D[0];
-  const canvas = await axialView.$('canvas');
-  const location = await canvas.getLocation();
-  const size = await canvas.getSize();
-
-  return {
-    axialView,
-    centerX: location.x + size.width / 2,
-    centerY: location.y + size.height / 2,
-  };
-};
-
-// Tool selection
-const selectPolygonTool = async () => {
-  const btn = await $('button span i[class~=mdi-pentagon-outline]');
-  await btn.click();
-};
-
-const selectRectangleTool = async () => {
-  const btn = await $('button span i[class~=mdi-vector-square]');
-  await btn.click();
-};
+import {
+  clickAt,
+  getCircleCount,
+  moveTo,
+  rightClickAt,
+  setupTest,
+  waitForCircleCount,
+} from './annotationTestUtils';
+
+const selectPolygonTool = () => AppPage.selectTool('mdi-pentagon-outline');
+const selectRectangleTool = () => AppPage.selectTool('mdi-vector-square');
 
 // High-level shape creation
 const createSquarePolygon = async (
@@ -102,22 +57,6 @@ const createRectangle = async (
 };
 
 // Assertions
-const getCircleCount = async (axialView: ChainablePromiseElement) => {
-  const circles = await axialView.$$('svg circle');
-  return circles.length;
-};
-
-const waitForPointRemoved = async (
-  axialView: ChainablePromiseElement,
-  countBefore: number,
-  msg: string
-) => {
-  await browser.waitUntil(
-    async () => (await getCircleCount(axialView)) === countBefore - 1,
-    { timeout: 5000, timeoutMsg: msg }
-  );
-};
-
 const getVisibleCircleCount = async (axialView: ChainablePromiseElement) => {
   const circles = await axialView.$$('svg circle');
   let count = 0;
@@ -169,9 +108,9 @@ describe('Polygon tool nested interaction', () => {
 
     const countBefore = await getCircleCount(axialView);
     await rightClickAt(centerX + 40, centerY + 40);
-    await waitForPointRemoved(
+    await waitForCircleCount(
       axialView,
-      countBefore,
+      countBefore - 1,
       'Right-click should remove one point from the third polygon'
     );
   });
@@ -189,9 +128,9 @@ describe('Polygon tool nested interaction', () => {
 
     const countBefore = await getCircleCount(axialView);
     await rightClickAt(centerX, centerY);
-    await waitForPointRemoved(
+    await waitForCircleCount(
       axialView,
-      countBefore,
+      countBefore - 1,
       'Right-click should remove exactly one point from the placing polygon'
     );
   });
@@ -211,9 +150,9 @@ describe('Polygon tool nested interaction', () => {
 
     const countBefore = await getCircleCount(axialView);
     await rightClickAt(centerX, centerY);
-    await waitForPointRemoved(
+    await waitForCircleCount(
       axialView,
-      countBefore,
+      countBefore - 1,
       'Right-click should remove one point from the polygon when placing inside a rectangle'
     );
   });