@plannotator/ui 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.27.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"
@@ -57,6 +58,7 @@
     "@codemirror/lang-yaml": "^6.1.3",
     "@codemirror/language": "^6.12.3",
     "@codemirror/legacy-modes": "^6.5.3",
+    "@codemirror/merge": "^6.12.2",
     "@codemirror/search": "^6.7.0",
     "@codemirror/state": "^6.6.0",
     "@codemirror/view": "^6.43.0",
@@ -64,10 +66,10 @@
     "@fontsource-variable/inter": "^5.2.8",
     "@lezer/common": "^1.5.2",
     "@lezer/highlight": "^1.2.3",
-    "@pierre/diffs": "1.2.8",
-    "@plannotator/atomic-editor": "^0.7.0",
-    "@plannotator/core": "0.22.0",
-    "@plannotator/markdown-editor": "^0.3.2",
+    "@pierre/diffs": "1.3.2",
+    "@plannotator/atomic-editor": "^0.8.0",
+    "@plannotator/core": "0.23.0",
+    "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",
     "@viz-js/viz": "^3.25.0",
@@ -75,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);