@plannotator/ui 0.28.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -18,6 +18,7 @@
     "./shortcuts": "./shortcuts/index.ts",
     "./config": "./config/index.ts",
     "./configure": "./configure.ts",
+    "./theme-modes": "./components/themeModes.tsx",
     "./types": "./types.ts",
     "./theme": "./theme.css",
     "./styles.css": "./styles.css"
@@ -65,9 +66,9 @@
     "@fontsource-variable/inter": "^5.2.8",
     "@lezer/common": "^1.5.2",
     "@lezer/highlight": "^1.2.3",
-    "@pierre/diffs": "1.2.8",
+    "@pierre/diffs": "1.3.2",
     "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.22.0",
+    "@plannotator/core": "0.23.0",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
@@ -76,7 +77,6 @@
     "clsx": "^2.1.1",
     "diff": "^8.0.4",
     "dompurify": "^3.3.3",
-    "highlight.js": "^11.11.1",
     "katex": "^0.16.47",
     "lucide-react": "^1.14.0",
     "marked": "^17.0.6",

package/print.css

@@ -4,7 +4,8 @@
  *   1. @media print — standard print styles
  *   2. .plannotator-print — class added via JS beforeprint/afterprint events
  *      to guarantee overrides that @media print alone cannot achieve
- *      (e.g. beating Tailwind layers + hljs github-dark theme).
+ *      (e.g. beating Tailwind layers, and the syntax theme's per-token inline
+ *      colours — inline styles only lose to an !important author rule).
  */
 
 /* ============================================================
@@ -12,7 +13,7 @@
  * These use .plannotator-print on <html> for maximum specificity.
  * ============================================================ */
 
-/* Code blocks: override github-dark.css .hljs{background:#0d1117} */
+/* Code blocks: flatten the syntax theme's dark block background to paper */
 .plannotator-print pre,
 .plannotator-print pre[class] {
   background: #f5f5f5 !important;
@@ -23,18 +24,19 @@
 }
 
 .plannotator-print pre code,
-.plannotator-print code.hljs,
-.plannotator-print pre code.hljs,
-.plannotator-print .hljs {
+.plannotator-print code.pn-code,
+.plannotator-print pre code.pn-code,
+.plannotator-print .code-snippet-preview {
   background: transparent !important;
   background-color: transparent !important;
   color: #1a1a1a !important;
 }
 
+/* The syntax theme colours every token with an inline `style`, so these
+   !important rules are what flattens code to black on paper. */
 .plannotator-print pre span,
 .plannotator-print pre code span,
-.plannotator-print .hljs span,
-.plannotator-print [class*="hljs-"] {
+.plannotator-print .code-snippet-preview span {
   color: #1a1a1a !important;
   background: transparent !important;
   background-color: transparent !important;
@@ -284,9 +286,8 @@
 
   pre code,
   pre code[class],
-  pre code.hljs,
-  code.hljs,
-  code[data-highlighted] {
+  pre code.pn-code,
+  code.pn-code {
     font-size: 9pt !important;
     background: transparent !important;
     background-color: transparent !important;
@@ -298,14 +299,14 @@
     word-wrap: break-word !important;
   }
 
-  .hljs {
+  .code-snippet-preview {
     background: transparent !important;
     background-color: transparent !important;
     color: #1a1a1a !important;
   }
 
-  pre span, pre code span, .hljs span, code span,
-  [class*="hljs-"] {
+  pre span, pre code span, code span,
+  .code-snippet-preview span {
     color: #1a1a1a !important;
     background: transparent !important;
     background-color: transparent !important;

package/shortcuts/core.ts

@@ -46,12 +46,6 @@ const NAMED_TOKENS = new Set([
   'Enter',
   'Escape',
   'Tab',
-  // TODO(migration): `matchesKeyToken` does not currently match `Space` —
-  // pressing Spacebar produces `event.key === ' '` (length 1), which the
-  // matcher uppercases to `' '` and then compares to the literal `'Space'`,
-  // always failing. Add a special case in `matchesKeyToken` (e.g.
-  // `if (token === 'Space') return event.key === ' ' || event.code === 'Space'`)
-  // before any scope binds Space.
   'Space',
   'Backspace',
   'Delete',
@@ -68,8 +62,13 @@ const NAMED_TOKENS = new Set([
   // whitelist explicitly so typos like `Cmd` instead of `Mod` keep failing
   // validation.
   '.',
+  '/',
   '[',
   ']',
+  '{',
+  '}',
+  '?',
+  '$',
 ]);
 
 for (let n = 1; n <= 12; n += 1) {
@@ -77,6 +76,11 @@ for (let n = 1; n <= 12; n += 1) {
 }
 
 const MODIFIER_TOKENS = new Set(['Mod', 'Shift', 'Alt']);
+const SHIFTED_LITERAL_TOKENS = new Set(['{', '}', '?', '$']);
+type ShortcutKeyEvent = Pick<
+  KeyboardEvent,
+  'key' | 'code' | 'metaKey' | 'ctrlKey' | 'shiftKey' | 'altKey'
+>;
 
 export function defineShortcutScope<TAction extends string>(scope: ShortcutScopeDefinition<TAction>): ShortcutScopeDefinition<TAction> {
   return scope;
@@ -115,7 +119,7 @@ export function parseDoubleTapBinding(binding: string): string | null {
  * Check if a KeyboardEvent matches a named key token (for sequential/stateful matching).
  * Unlike `matchesShortcutBinding`, this matches a single key identity without modifier checks.
  */
-export function matchesKeyName(event: KeyboardEvent, keyName: string): boolean {
+export function matchesKeyName(event: ShortcutKeyEvent, keyName: string): boolean {
   if (keyName === 'Alt') return event.key === 'Alt';
   if (keyName === 'Shift') return event.key === 'Shift';
   if (keyName === 'Mod') return event.key === 'Meta' || event.key === 'Control';
@@ -333,13 +337,13 @@ export function formatShortcutBindingsText(
   return bindings.map(binding => formatShortcutBindingText(binding, platform)).join(' or ');
 }
 
-function getDigitCode(event: KeyboardEvent): string | null {
+function getDigitCode(event: ShortcutKeyEvent): string | null {
   const code = typeof event.code === 'string' ? event.code : '';
   const match = code.match(/^Digit([0-9])$/);
   return match ? match[1] : null;
 }
 
-export function getShortcutDigit(event: KeyboardEvent): number | null {
+export function getShortcutDigit(event: ShortcutKeyEvent): number | null {
   const parsed = Number.parseInt(event.key, 10);
   if (!Number.isNaN(parsed)) return parsed;
 
@@ -347,10 +351,14 @@ export function getShortcutDigit(event: KeyboardEvent): number | null {
   return digitCode === null ? null : Number.parseInt(digitCode, 10);
 }
 
-function matchesKeyToken(event: KeyboardEvent, token: string): boolean {
+function matchesKeyToken(event: ShortcutKeyEvent, token: string): boolean {
   const key = event.key.length === 1 ? event.key.toUpperCase() : event.key;
   const shortcutDigit = getShortcutDigit(event);
 
+  if (token === 'Space') {
+    return event.key === ' ' || event.key === 'Spacebar' || event.code === 'Space';
+  }
+
   if (token === 'A-Z') {
     return /^[A-Z]$/.test(key);
   }
@@ -370,7 +378,13 @@ function matchesKeyToken(event: KeyboardEvent, token: string): boolean {
   return key === token;
 }
 
-export function matchesShortcutBinding(event: KeyboardEvent, binding: string): boolean {
+/**
+ * Match a keyboard event against one normalized, single-press binding.
+ *
+ * Sequential and hold bindings deliberately return false; their timing
+ * semantics are handled by the shortcut runtime's dedicated paths.
+ */
+export function matchesShortcutBinding(event: ShortcutKeyEvent, binding: string): boolean {
   if (binding.includes(' ') || binding.includes('hold')) {
     return false;
   }
@@ -385,7 +399,9 @@ export function matchesShortcutBinding(event: KeyboardEvent, binding: string): b
   if (keyTokens.length !== 1) return false;
 
   const keyToken = keyTokens[0];
-  const shiftMatches = requiresShift === event.shiftKey || (!requiresShift && keyToken === 'A-Z' && event.shiftKey);
+  const shiftMatches = requiresShift === event.shiftKey
+    || (!requiresShift && keyToken === 'A-Z' && event.shiftKey)
+    || (!requiresShift && SHIFTED_LITERAL_TOKENS.has(keyToken) && event.key === keyToken);
 
   if (requiresMod !== (event.metaKey || event.ctrlKey)) return false;
   if (!shiftMatches) return false;
@@ -394,6 +410,15 @@ export function matchesShortcutBinding(event: KeyboardEvent, binding: string): b
   return matchesKeyToken(event, keyToken);
 }
 
-export function getMatchingShortcutBindingIndex(event: KeyboardEvent, bindings: string[]): number {
+/**
+ * Match one key group from a sequential binding such as `G G`.
+ *
+ * The group uses the same normalized syntax as an ordinary one-press binding.
+ */
+export function matchesShortcutBindingGroup(event: ShortcutKeyEvent, group: string): boolean {
+  return matchesShortcutBinding(event, group);
+}
+
+export function getMatchingShortcutBindingIndex(event: ShortcutKeyEvent, bindings: string[]): number {
   return bindings.findIndex(binding => matchesShortcutBinding(event, binding));
 }

package/shortcuts/index.ts

@@ -8,6 +8,16 @@ export { commentPopoverShortcuts } from './plan-review/commentPopover.shortcuts'
 export { imageAnnotatorShortcuts, useImageAnnotatorShortcuts } from './plan-review/imageAnnotator.shortcuts';
 export { inputMethodShortcuts } from './plan-review/inputMethod.shortcuts';
 export { viewerShortcuts, useViewerShortcuts } from './plan-review/viewer.shortcuts';
+export {
+  describeVimSelectionAction,
+  isVimSelectionActionId,
+  vimSelectionShortcuts,
+  useVimSelectionShortcuts,
+} from './plan-review/vimSelection.shortcuts';
+export type {
+  VimSelectionActionId,
+  VimSelectionHudContext,
+} from './plan-review/vimSelection.shortcuts';
 export { goalSetupShortcuts, useGoalSetupShortcuts } from './plan-review/goalSetup.shortcuts';
 export { annotateSidebarShortcuts, useAnnotateSidebarShortcuts } from './plan-review/sidebar.shortcuts';
 

package/shortcuts/plan-review/commentPopover.shortcuts.ts

@@ -17,5 +17,12 @@ export const commentPopoverShortcuts = defineShortcutScope({
       hint: 'Available while the comment editor is open.',
       displayOrder: 40,
     },
+    skillMenuOpen: {
+      description: 'Reference an agent skill (opens the skill menu)',
+      bindings: ['/', '$'],
+      section: 'Annotations',
+      hint: 'Type / or $ at the start of a word in the comment editor to open the skill menu; keep typing to filter. Nothing is preselected: Enter stays a newline until you pick a row with the arrow keys (or click one), then Enter or Tab inserts it. Escape dismisses the menu.',
+      displayOrder: 50,
+    },
   },
 });

package/shortcuts/plan-review/vimSelection.shortcuts.ts

@@ -0,0 +1,251 @@
+import { defineShortcutScope } from '../core';
+import { createShortcutScopeHook } from '../runtime';
+
+/**
+ * Modal document-navigation commands shared by plan review and annotate mode.
+ *
+ * The bindings are active only while the opted-in document focus surface owns
+ * focus; native controls and annotation composers remain outside this scope.
+ */
+export const vimSelectionShortcuts = defineShortcutScope({
+  id: 'vim-selection',
+  title: 'Vim selection',
+  shortcuts: {
+    moveDown: {
+      description: 'Next block or semantic sibling',
+      bindings: ['J'],
+      section: 'Vim Document Navigation',
+      displayOrder: 10,
+    },
+    moveUp: {
+      description: 'Previous block or semantic sibling',
+      bindings: ['K'],
+      section: 'Vim Document Navigation',
+      displayOrder: 20,
+    },
+    documentStart: {
+      description: 'Start of document',
+      bindings: ['G G'],
+      section: 'Vim Document Navigation',
+      displayOrder: 30,
+      preventDefault: true,
+    },
+    documentEnd: {
+      description: 'End of document',
+      bindings: ['Shift+G'],
+      section: 'Vim Document Navigation',
+      displayOrder: 40,
+    },
+    moveOut: {
+      description: 'Move to containing target',
+      bindings: ['H'],
+      section: 'Vim Document Navigation',
+      displayOrder: 50,
+    },
+    refine: {
+      description: 'Refine into child or text',
+      bindings: ['L'],
+      section: 'Vim Document Navigation',
+      displayOrder: 60,
+    },
+    visual: {
+      description: 'Toggle precise Visual selection',
+      bindings: ['V'],
+      section: 'Vim Document Navigation',
+      displayOrder: 70,
+    },
+    visualBlock: {
+      description: 'Toggle whole-block Visual selection',
+      bindings: ['Shift+V'],
+      section: 'Vim Document Navigation',
+      hint: 'Use j / k to extend by whole blocks.',
+      displayOrder: 80,
+    },
+    wordForward: {
+      description: 'Move to next word',
+      bindings: ['W'],
+      section: 'Vim Text Navigation',
+      displayOrder: 90,
+    },
+    wordBackward: {
+      description: 'Move to previous word',
+      bindings: ['B'],
+      section: 'Vim Text Navigation',
+      displayOrder: 100,
+    },
+    wordEnd: {
+      description: 'Move to end of word',
+      bindings: ['E'],
+      section: 'Vim Text Navigation',
+      displayOrder: 110,
+    },
+    lineStart: {
+      description: 'Move to start of line',
+      bindings: ['0'],
+      section: 'Vim Text Navigation',
+      displayOrder: 120,
+    },
+    lineEnd: {
+      description: 'Move to end of line',
+      bindings: ['$'],
+      section: 'Vim Text Navigation',
+      displayOrder: 130,
+    },
+    previousTextBlock: {
+      description: 'Move to previous text block',
+      bindings: ['{'],
+      section: 'Vim Text Navigation',
+      displayOrder: 140,
+    },
+    nextTextBlock: {
+      description: 'Move to next text block',
+      bindings: ['}'],
+      section: 'Vim Text Navigation',
+      displayOrder: 150,
+    },
+    swapSelectionEnds: {
+      description: 'Swap selection ends',
+      bindings: ['O'],
+      section: 'Vim Text Navigation',
+      displayOrder: 160,
+    },
+    activeAnnotation: {
+      description: 'Use active annotation mode',
+      bindings: ['Enter'],
+      section: 'Vim Annotation Actions',
+      displayOrder: 170,
+    },
+    annotationMenu: {
+      description: 'Open annotation actions',
+      bindings: ['Space'],
+      section: 'Vim Annotation Actions',
+      displayOrder: 180,
+    },
+    comment: {
+      description: 'Comment selection or target',
+      bindings: ['C'],
+      section: 'Vim Annotation Actions',
+      displayOrder: 190,
+    },
+    redline: {
+      description: 'Redline selection or target',
+      bindings: ['D'],
+      section: 'Vim Annotation Actions',
+      displayOrder: 200,
+    },
+    markup: {
+      description: 'Markup selection or target',
+      bindings: ['M'],
+      section: 'Vim Annotation Actions',
+      displayOrder: 210,
+    },
+    label: {
+      description: 'Label selection or target',
+      bindings: ['T'],
+      section: 'Vim Annotation Actions',
+      displayOrder: 220,
+    },
+    copy: {
+      description: 'Copy selection or target',
+      bindings: ['Y'],
+      section: 'Vim Annotation Actions',
+      displayOrder: 230,
+    },
+    cancel: {
+      description: 'Cancel current Vim state',
+      bindings: ['Escape'],
+      section: 'Vim Annotation Actions',
+      displayOrder: 240,
+    },
+    help: {
+      description: 'Toggle key map',
+      bindings: ['?'],
+      section: 'Vim Annotation Actions',
+      displayOrder: 250,
+    },
+  },
+});
+
+/** Stable action identifiers emitted by the Vim selection shortcut scope. */
+export type VimSelectionActionId = keyof typeof vimSelectionShortcuts.shortcuts;
+
+/** Vim navigation state used to make HUD command descriptions contextual. */
+export type VimSelectionHudContext =
+  | 'inactive'
+  | 'block'
+  | 'inline'
+  | 'text'
+  | 'visual'
+  | 'visual-block'
+  | 'action';
+
+/**
+ * Return the user-facing HUD description for a handled Vim action.
+ *
+ * Contextual movement keys keep one registered shortcut while accurately
+ * describing whether they moved by document structure, line, or character.
+ */
+export function describeVimSelectionAction(
+  actionId: VimSelectionActionId,
+  context: VimSelectionHudContext,
+): string {
+  switch (actionId) {
+    case 'moveDown':
+      if (context === 'inline') return 'Next semantic sibling';
+      if (context === 'text' || context === 'visual') return 'Next line';
+      if (context === 'visual-block') return 'Extend to next block';
+      return 'Next block';
+    case 'moveUp':
+      if (context === 'inline') return 'Previous semantic sibling';
+      if (context === 'text' || context === 'visual') return 'Previous line';
+      if (context === 'visual-block') return 'Extend to previous block';
+      return 'Previous block';
+    case 'moveOut':
+      return context === 'text' || context === 'visual'
+        ? 'Move left one character'
+        : 'Move to containing target';
+    case 'refine':
+      return context === 'text' || context === 'visual'
+        ? 'Move right one character'
+        : 'Refine into child or text';
+    case 'visual':
+      return context === 'visual'
+        ? 'Return to Normal mode'
+        : 'Start Visual selection';
+    case 'visualBlock':
+      return context === 'visual-block'
+        ? 'Return to block navigation'
+        : 'Select the whole block';
+    case 'documentStart':
+    case 'documentEnd':
+    case 'wordForward':
+    case 'wordBackward':
+    case 'wordEnd':
+    case 'lineStart':
+    case 'lineEnd':
+    case 'previousTextBlock':
+    case 'nextTextBlock':
+    case 'swapSelectionEnds':
+    case 'activeAnnotation':
+    case 'annotationMenu':
+    case 'comment':
+    case 'redline':
+    case 'markup':
+    case 'label':
+    case 'copy':
+    case 'cancel':
+    case 'help':
+      return vimSelectionShortcuts.shortcuts[actionId].description;
+  }
+}
+
+/** Parse an unknown bridge value into a registered Vim action identifier. */
+export function isVimSelectionActionId(
+  value: unknown,
+): value is VimSelectionActionId {
+  return typeof value === 'string'
+    && Object.prototype.hasOwnProperty.call(vimSelectionShortcuts.shortcuts, value);
+}
+
+/** Bind Vim selection handlers to the opted-in document focus surface. */
+export const useVimSelectionShortcuts = createShortcutScopeHook(vimSelectionShortcuts);

package/shortcuts/runtime.ts

@@ -1,6 +1,11 @@
 import { useEffect, useRef } from 'react';
 import type { ShortcutDefinition, ShortcutScopeDefinition } from './core';
-import { matchesKeyName, matchesShortcutBinding, parseDoubleTapBinding } from './core';
+import {
+  matchesKeyName,
+  matchesShortcutBinding,
+  matchesShortcutBindingGroup,
+  parseDoubleTapBinding,
+} from './core';
 
 type ShortcutActionId<TScope extends ShortcutScopeDefinition<any>> = keyof TScope['shortcuts'] & string;
 
@@ -24,6 +29,19 @@ export interface UseShortcutScopeOptions<TScope extends ShortcutScopeDefinition<
   stopOnMatch?: boolean;
 }
 
+interface ShortcutSequenceCandidate {
+  readonly actionId: string;
+  readonly groups: readonly string[];
+  readonly nextIndex: number;
+}
+
+interface ShortcutSequenceState {
+  readonly candidates: readonly ShortcutSequenceCandidate[];
+  readonly expiresAt: number;
+}
+
+const SHORTCUT_SEQUENCE_WINDOW_MS = 500;
+
 function normalizeShortcutHandler(handler: ShortcutHandler): ShortcutHandlerConfig {
   if (typeof handler === 'function') {
     return { handle: handler };
@@ -32,6 +50,17 @@ function normalizeShortcutHandler(handler: ShortcutHandler): ShortcutHandlerConf
   return handler;
 }
 
+function getShortcutEntries<TScope extends ShortcutScopeDefinition<any>>(
+  scope: TScope,
+): Array<[ShortcutActionId<TScope>, ShortcutDefinition]> {
+  // SAFETY: ShortcutScopeDefinition constrains every own value in `shortcuts`
+  // to ShortcutDefinition; Object.entries preserves those own keys and values.
+  return Object.entries(scope.shortcuts) as Array<[
+    ShortcutActionId<TScope>,
+    ShortcutDefinition,
+  ]>;
+}
+
 // TODO(migration): no cross-scope arbitration. When two scopes bind the
 // same key (e.g. `Escape` in both an outer editor scope and an inner
 // dialog scope), both `useShortcutScope` listeners fire on a single
@@ -48,10 +77,7 @@ export function dispatchShortcutEvent<TScope extends ShortcutScopeDefinition<any
   const stopOnMatch = options?.stopOnMatch ?? true;
   let handled = false;
 
-  for (const [actionId, shortcut] of Object.entries(scope.shortcuts) as Array<[
-    ShortcutActionId<TScope>,
-    ShortcutDefinition,
-  ]>) {
+  for (const [actionId, shortcut] of getShortcutEntries(scope)) {
     const handler = handlers[actionId];
     if (!handler) continue;
     if (!shortcut.bindings.some(binding => matchesShortcutBinding(event, binding))) continue;
@@ -84,6 +110,14 @@ function getEventTarget(target: ShortcutEventTarget): EventTarget | null {
   return target;
 }
 
+/**
+ * Attach a registry scope to a keyboard event target.
+ *
+ * Ordinary bindings dispatch immediately. Non-modifier sequential bindings
+ * advance within a 500 ms window, suppress their prefix keystrokes, and reset
+ * after a match, timeout, or unrelated key. Handlers are read through a ref so
+ * listener lifetime follows only the scope, target, and dispatch options.
+ */
 export function useShortcutScope<TScope extends ShortcutScopeDefinition<any>>({
   scope,
   handlers,
@@ -91,6 +125,7 @@ export function useShortcutScope<TScope extends ShortcutScopeDefinition<any>>({
   stopOnMatch = true,
 }: UseShortcutScopeOptions<TScope>) {
   const handlersRef = useRef(handlers);
+  const sequenceRef = useRef<ShortcutSequenceState | null>(null);
 
   useEffect(() => {
     handlersRef.current = handlers;
@@ -101,12 +136,79 @@ export function useShortcutScope<TScope extends ShortcutScopeDefinition<any>>({
     if (!eventTarget || !('addEventListener' in eventTarget)) return;
 
     const handleKeyDown = (event: Event) => {
-      dispatchShortcutEvent(scope, handlersRef.current, event as KeyboardEvent, { stopOnMatch });
+      if (!(event instanceof KeyboardEvent)) return;
+      const keyboardEvent = event;
+      if (dispatchShortcutEvent(scope, handlersRef.current, keyboardEvent, { stopOnMatch })) {
+        sequenceRef.current = null;
+        return;
+      }
+
+      const now = Date.now();
+      const active = sequenceRef.current && sequenceRef.current.expiresAt >= now
+        ? sequenceRef.current.candidates
+        : [];
+      const advanced: ShortcutSequenceCandidate[] = [];
+
+      for (const candidate of active) {
+        const group = candidate.groups[candidate.nextIndex];
+        if (!group || !matchesShortcutBindingGroup(keyboardEvent, group)) continue;
+        if (candidate.nextIndex === candidate.groups.length - 1) {
+          const shortcut = scope.shortcuts[candidate.actionId];
+          const handler = handlersRef.current[candidate.actionId];
+          if (!shortcut || !handler) continue;
+          const { when, handle } = normalizeShortcutHandler(handler);
+          if (when && !when(keyboardEvent)) continue;
+          if (shortcut.preventDefault) keyboardEvent.preventDefault();
+          handle(keyboardEvent);
+          sequenceRef.current = null;
+          return;
+        }
+        advanced.push({ ...candidate, nextIndex: candidate.nextIndex + 1 });
+      }
+
+      if (advanced.length > 0) {
+        sequenceRef.current = {
+          candidates: advanced,
+          expiresAt: now + SHORTCUT_SEQUENCE_WINDOW_MS,
+        };
+        keyboardEvent.preventDefault();
+        return;
+      }
+
+      const started: ShortcutSequenceCandidate[] = [];
+      for (const [actionId, shortcut] of getShortcutEntries(scope)) {
+        const handler = handlersRef.current[actionId];
+        if (!handler) continue;
+        const { when } = normalizeShortcutHandler(handler);
+        if (when && !when(keyboardEvent)) continue;
+
+        for (const binding of shortcut.bindings) {
+          const groups = binding.trim().split(/\s+/).filter(Boolean);
+          const doubleTapKey = parseDoubleTapBinding(binding);
+          if (
+            groups.length < 2
+            || groups.includes('hold')
+            || (doubleTapKey !== null && ['Alt', 'Shift', 'Mod'].includes(doubleTapKey))
+            || !matchesShortcutBindingGroup(keyboardEvent, groups[0] ?? '')
+          ) {
+            continue;
+          }
+          started.push({ actionId, groups, nextIndex: 1 });
+        }
+      }
+
+      sequenceRef.current = started.length > 0
+        ? {
+            candidates: started,
+            expiresAt: now + SHORTCUT_SEQUENCE_WINDOW_MS,
+          }
+        : null;
+      if (started.length > 0) keyboardEvent.preventDefault();
     };
 
-    eventTarget.addEventListener('keydown', handleKeyDown as EventListener);
+    eventTarget.addEventListener('keydown', handleKeyDown);
     return () => {
-      eventTarget.removeEventListener('keydown', handleKeyDown as EventListener);
+      eventTarget.removeEventListener('keydown', handleKeyDown);
     };
   }, [scope, stopOnMatch, target]);
 }
@@ -165,10 +267,7 @@ export function useDoubleTapShortcuts<TScope extends ShortcutScopeDefinition<any
   useEffect(() => {
     // Pre-parse which actions have double-tap bindings
     const doubleTapActions: Array<{ actionId: ShortcutActionId<TScope>; keyName: string; preventDefault: boolean }> = [];
-    for (const [actionId, shortcut] of Object.entries(scope.shortcuts) as Array<[
-      ShortcutActionId<TScope>,
-      ShortcutDefinition,
-    ]>) {
+    for (const [actionId, shortcut] of getShortcutEntries(scope)) {
       for (const binding of shortcut.bindings) {
         const keyName = parseDoubleTapBinding(binding);
         if (keyName) {