cursedbelt 5.78.0 → 5.79.0

package/src/react/media-gallery/MediaMetaEditor.tsx

@@ -6,6 +6,7 @@ import { FieldLabel } from '../components/FieldLabel.js';
 import { InfoHint } from '../components/InfoHint.js';
 import { Modal } from '../components/Modal.js';
 import { TagsInput } from '../components/TagsInput.js';
+import { Kbd } from '../palette/Kbd.js';
 import {
   type MediaMetaChange,
   cleanTags,
@@ -156,7 +157,7 @@ export function MediaMetaEditor({
                   <>
                     Tags are how this file is found again: each one becomes a chip above the
                     grid that filters the album down to the things wearing it. Type and press{' '}
-                    <kbd>Enter</kbd>, or pick one already in use.
+                    <Kbd>Enter</Kbd>, or pick one already in use.
                   </>
                 }
               >

package/src/react/nav/CommandBar.tsx

@@ -2,6 +2,7 @@ import { Plus, Search } from 'lucide-react';
 import type { ReactNode } from 'react';
 import { Button } from '../components/Button.js';
 import { cn } from '../lib/cn.js';
+import { Kbd } from '../palette/Kbd.js';
 
 export interface CommandBarProps {
   /**
@@ -93,9 +94,7 @@ export function CommandBar({
             {commandPlaceholder}
           </span>
           {commandHint != null && !compact && (
-            <kbd className='hidden shrink-0 items-center rounded border border-border bg-background px-1.5 py-0.5 font-sans text-xs text-muted-foreground sm:inline-flex'>
-              {commandHint}
-            </kbd>
+            <Kbd className='hidden shrink-0 items-center sm:inline-flex'>{commandHint}</Kbd>
           )}
         </Button>
       )}

package/src/react/palette/CommandPalette.spec.tsx

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, mock, test } from 'bun:test';
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
 import type { GateFn, NavGate, NavigationModel } from 'cursedbelt-core/navigation';
+import { formatHotkey, isApplePlatform } from 'cursedbelt-core/palette/hotkeys';
 import { shortcutRegistry } from 'cursedbelt-core/palette/shortcut-registry';
 import type { SearchResultGroup } from '../nav/SearchResults.js';
 import { CommandPalette } from './CommandPalette.js';
@@ -451,3 +452,75 @@ describe('contributed sources — recent items first (OVL-8)', () => {
     localStorage.removeItem(PALETTE_RECENT_STORAGE_KEY);
   });
 });
+
+describe('a row chord and the hint footer (the vault omnibar, forge task 3031)', () => {
+  const mod = { metaKey: isApplePlatform(), ctrlKey: !isApplePlatform() };
+  const setup = (overrides: { hints?: { keys: string; label: string; onSelect?: () => void }[] } = {}) => {
+    const copied: string[] = [];
+    const onOpenChange = mock((_open: boolean) => {});
+    const sources = [
+      {
+        group: 'Entries',
+        items: [
+          { id: 'a', label: 'Alpha', onSelect: () => {}, actions: [{ keys: '$mod+c', label: 'Copy secret', run: () => copied.push('a') }] },
+          { id: 'b', label: 'Beta', onSelect: () => {} },
+          { id: 'c', label: 'Gamma', onSelect: () => {}, actions: [{ keys: '$mod+c', label: 'Copy secret', run: () => copied.push('c') }] },
+        ],
+      },
+    ];
+    render(
+      <CommandPalette
+        model={model}
+        onNavigate={() => {}}
+        shortcuts={[]}
+        sources={sources}
+        open
+        onOpenChange={onOpenChange}
+        hints={'hints' in overrides ? overrides.hints : []}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    return { copied, onOpenChange, input };
+  };
+  const footerActions = () =>
+    Array.from(document.querySelectorAll('[data-cb-palette-action]')).map((el) => el.textContent);
+
+  test('the chord runs on the HIGHLIGHTED row only, and closes the palette', () => {
+    localStorage.removeItem(PALETTE_RECENT_STORAGE_KEY);
+    const { copied, onOpenChange, input } = setup();
+    // Alpha is highlighted first: the footer names its chord.
+    expect(footerActions()).toEqual([`${formatHotkey('$mod+c')}Copy secret`]);
+    fireEvent.keyDown(input, { key: 'ArrowDown' });
+    // Beta has no chord: the footer drops it, and the chord does nothing.
+    expect(footerActions()).toEqual([]);
+    fireEvent.keyDown(input, { key: 'c', ...mod });
+    expect(copied).toEqual([]);
+    expect(onOpenChange).not.toHaveBeenCalled();
+    fireEvent.keyDown(input, { key: 'ArrowDown' });
+    fireEvent.keyDown(input, { key: 'c', ...mod });
+    expect(copied).toEqual(['c']);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+    localStorage.removeItem(PALETTE_RECENT_STORAGE_KEY);
+  });
+
+  test('⌘C over SELECTED query text is the input’s copy, never the row’s', () => {
+    const { copied, input } = setup();
+    fireEvent.change(input, { target: { value: 'al' } });
+    (input as HTMLInputElement).setSelectionRange(0, 2);
+    fireEvent.keyDown(input, { key: 'c', ...mod });
+    expect(copied).toEqual([]);
+  });
+
+  test('a hint with onSelect is a button that closes the palette and runs', () => {
+    const opened: string[] = [];
+    const { onOpenChange } = setup({ hints: [{ keys: '?', label: 'Shortcuts', onSelect: () => opened.push('sheet') }] });
+    fireEvent.click(screen.getByRole('button', { name: /Shortcuts/ }));
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+    expect(opened).toEqual(['sheet']);
+  });
+
+  test('no hints, no footer — the default every other palette keeps', () => {
+    setup({ hints: undefined });
+    expect(document.querySelector('[data-cb-palette-hints]')).toBeNull();
+  });
+});

package/src/react/palette/CommandPalette.tsx

@@ -13,7 +13,7 @@
 
 import * as Dialog from '@radix-ui/react-dialog';
 import { Pin, Plus } from 'lucide-react';
-import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { type KeyboardEvent, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import {
   allowAllGate,
   deriveSearchCatalogue,
@@ -24,7 +24,7 @@ import {
   type SearchCatalogueEntry,
 } from 'cursedbelt-core/navigation';
 import { fuzzyRankItems } from 'cursedbelt-core/palette/fuzzy-rank';
-import { formatHotkey } from 'cursedbelt-core/palette/hotkeys';
+import { matchHotkey } from 'cursedbelt-core/palette/hotkeys';
 import type { ShortcutEntry } from 'cursedbelt-core/palette/shortcut-registry';
 import { Button } from '../components/Button.js';
 import { ScrollArea } from '../components/ScrollArea.js';
@@ -43,7 +43,14 @@ import {
   CommandItem,
   CommandList,
 } from './Command.js';
-import { type CommandSource, type CommandSourceItem, recentFirst, rememberCommandItem } from './commandSources.js';
+import {
+  type CommandItemAction,
+  type CommandSource,
+  type CommandSourceItem,
+  recentFirst,
+  rememberCommandItem,
+} from './commandSources.js';
+import { Kbd } from './Kbd.js';
 import { useShortcutRegistry } from './useShortcutRegistry.js';
 import { TAP_TARGET_HEIGHT } from '../lib/tapTarget.js';
 
@@ -106,6 +113,13 @@ export interface CommandPaletteProps {
    */
   sources?: readonly CommandSource[];
 
+  /**
+   * A key-hint row along the palette's foot: ↑↓ Navigate · ↵ Open, the highlighted row's own
+   * chords (its `actions` — "⌘C Copy secret"), then these. A hint with `onSelect` is a button
+   * (the vault's "? Shortcuts" opens its sheet). Omit for no footer, the default.
+   */
+  hints?: readonly CommandPaletteHint[];
+
   /** Resolve model icon *names* to nodes (the app wires its icon set, e.g. lucide). */
   resolveIcon?: IconResolver;
   /** Max fuzzy page results. Default 30. */
@@ -116,6 +130,24 @@ export interface CommandPaletteProps {
   className?: string;
 }
 
+/** One entry in the palette's foot (see {@link CommandPaletteProps.hints}). */
+export interface CommandPaletteHint {
+  /** A binding (`'?'`, `'$mod+/'`), drawn as a key cap. */
+  keys: string;
+  label: string;
+  /** Makes the hint a button. The palette closes first. */
+  onSelect?: () => void;
+}
+
+/** The row a chord acts on: its actions, and what to remember it as when one runs. */
+interface RowActions {
+  group: string;
+  id: string;
+  actions: readonly CommandItemAction[];
+}
+
+const NO_ROW: RowActions | undefined = undefined;
+
 /** A page hit grouped under its owning domain, preserving uFuzzy rank order. */
 interface PageGroup {
   id: string;
@@ -152,6 +184,7 @@ export function CommandPalette({
   searchDebounceMs = 300,
   places = false,
   sources,
+  hints,
   resolveIcon,
   pagesLimit = 30,
   placeholder = 'Search pages, run a command…',
@@ -178,10 +211,17 @@ export function CommandPalette({
     onQueryChangeRef.current?.(debouncedQuery);
   }, [debouncedQuery]);
 
+  // The highlighted row's cmdk value — controlled, so a row's chords (`actions`) and the footer's
+  // hints can follow the highlight.
+  const [selected, setSelected] = useState('');
+
   // Reset the query each time the palette closes so it reopens cold (the Radix Dialog
   // unmounts its content, but this component stays mounted and holds the state).
   useEffect(() => {
-    if (!open) setQuery('');
+    if (!open) {
+      setQuery('');
+      setSelected('');
+    }
   }, [open]);
 
   // ── Derivations off the registry ──────────────────────────────────────────
@@ -274,6 +314,36 @@ export function CommandPalette({
       .filter((group) => group.items.length > 0);
   }, [sources, isCold, trimmed, open]);
 
+  /** Every contributed row with chords, by its cmdk value (see `SourceGroups`). */
+  const rowActions = useMemo(() => {
+    const map = new Map<string, RowActions>();
+    for (const group of sourceGroups) {
+      for (const item of group.items) {
+        if (item.actions?.length) {
+          map.set(sourceValue(group.key, item.id), { group: group.label, id: item.id, actions: item.actions });
+        }
+      }
+    }
+    return map;
+  }, [sourceGroups]);
+  const selectedRow = rowActions.get(selected) ?? NO_ROW;
+
+  /**
+   * A highlighted row's chord runs its action and closes the palette. 🔴 A chord the input itself
+   * answers stays the input's: ⌘C over SELECTED query text copies that text, never the row.
+   */
+  const onPaletteKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (!selectedRow || event.defaultPrevented) return;
+    const action = selectedRow.actions.find((a) => matchHotkey(event.nativeEvent, a.keys));
+    if (!action) return;
+    const field = event.target as Partial<HTMLInputElement>;
+    if (typeof field.selectionStart === 'number' && field.selectionStart !== field.selectionEnd) return;
+    event.preventDefault();
+    rememberCommandItem(selectedRow.group, selectedRow.id);
+    action.run();
+    onOpenChange(false);
+  };
+
   // ── Actions ───────────────────────────────────────────────────────────────
   const runSource = (group: string, item: CommandSourceItem) => {
     rememberCommandItem(group, item.id);
@@ -325,6 +395,9 @@ export function CommandPalette({
           <Command
             shouldFilter={false}
             loop
+            value={selected}
+            onValueChange={setSelected}
+            onKeyDown={onPaletteKeyDown}
             label='Command palette'
             className='rounded-xl border border-border shadow-[var(--shadow-overlay)]'
           >
@@ -337,9 +410,7 @@ export function CommandPalette({
               trailing={
                 <>
                   {showSpinner && <Spinner size='sm' />}
-                  <kbd className='hidden rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-caption font-medium text-muted-foreground sm:inline-block'>
-                    {formatHotkey(TOGGLE_BINDING)}
-                  </kbd>
+                  <Kbd keys={TOGGLE_BINDING} className='hidden sm:inline-block' />
                 </>
               }
             />
@@ -440,6 +511,16 @@ export function CommandPalette({
                 </>
               )}
             </CommandList>
+            {hints && (
+              <PaletteHints
+                actions={selectedRow?.actions}
+                hints={hints}
+                onHint={(hint) => {
+                  onOpenChange(false);
+                  hint.onSelect?.();
+                }}
+              />
+            )}
           </Command>
         </Dialog.Content>
       </Dialog.Portal>
@@ -541,7 +622,7 @@ function SourceGroups({
       {groups.map((group) => (
         <CommandGroup key={`source-${group.key}`} heading={group.label}>
           {group.items.map((item) => (
-            <CommandItem key={`${group.key}:${item.id}`} value={`source:${group.key}:${item.id}`} onSelect={() => onRun(group.label, item)}>
+            <CommandItem key={`${group.key}:${item.id}`} value={sourceValue(group.key, item.id)} onSelect={() => onRun(group.label, item)}>
               <ItemBody
                 icon={item.icon}
                 label={item.label}
@@ -556,6 +637,69 @@ function SourceGroups({
   );
 }
 
+/** A contributed row's cmdk value — the key its chords are found by. */
+const sourceValue = (groupKey: string, id: string) => `source:${groupKey}:${id}`;
+
+/**
+ * The foot: how to move and open, the highlighted row's chords, then the app's hints. Keys are a
+ * pointer's business, so a phone does not get the row (the ⌘K badge above hides the same way).
+ */
+function PaletteHints({
+  actions,
+  hints,
+  onHint,
+}: {
+  actions: readonly CommandItemAction[] | undefined;
+  hints: readonly CommandPaletteHint[];
+  onHint: (hint: CommandPaletteHint) => void;
+}) {
+  return (
+    <div
+      data-cb-palette-hints=''
+      className='hidden w-full shrink-0 items-center gap-4 border-t border-border px-3 py-2 text-caption text-muted-foreground sm:inline-flex'
+    >
+      <span className='flex items-center gap-1.5'>
+        <Kbd>↑↓</Kbd>
+        Navigate
+      </span>
+      <span className='flex items-center gap-1.5'>
+        <Kbd>↵</Kbd>
+        Open
+      </span>
+      {actions?.map((action) => (
+        <span key={action.keys} data-cb-palette-action='' className='flex items-center gap-1.5'>
+          <Kbd keys={action.keys} />
+          {action.label}
+        </span>
+      ))}
+      {hints.length > 0 && (
+        <span className='ml-auto flex items-center gap-2'>
+          {hints.map((hint) =>
+            hint.onSelect ? (
+              <Button
+                key={hint.keys}
+                variant='ghost'
+                size='sm'
+                tooltip={hint.label}
+                onClick={() => onHint(hint)}
+                className='h-7 gap-1.5 px-1.5 text-caption font-normal text-muted-foreground'
+              >
+                <Kbd keys={hint.keys} />
+                {hint.label}
+              </Button>
+            ) : (
+              <span key={hint.keys} className='flex items-center gap-1.5'>
+                <Kbd keys={hint.keys} />
+                {hint.label}
+              </span>
+            ),
+          )}
+        </span>
+      )}
+    </div>
+  );
+}
+
 /** Shared row layout: optional leading icon, a label + sub stack, optional trailing node. */
 function ItemBody({
   icon,
@@ -591,11 +735,7 @@ function ItemBody({
 
 /** A keyboard-shortcut hint, formatted for the current platform (⌘K / Ctrl K). */
 function KeyHint({ keys }: { keys: string }) {
-  return (
-    <kbd className='rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-caption font-medium text-muted-foreground'>
-      {formatHotkey(keys)}
-    </kbd>
-  );
+  return <Kbd keys={keys} />;
 }
 
 /**

package/src/react/palette/Kbd.tsx

@@ -0,0 +1,46 @@
+// A key cap — the one drawing of a keyboard key in the kit. The palette's ⌘K badge, its rows'
+// shortcut hints, its footer and the `ShortcutSheet` all use it, so a key reads the same
+// everywhere. Pass `keys` for a binding (`'$mod+k'` → ⌘K on a Mac, Ctrl K elsewhere) or
+// children for a literal (`↑↓`). `platform` pins the notation when the reader chose one (family's
+// Mac / Windows keys setting) instead of the browser's guess; 'both' draws the Mac cap with the
+// Windows one beside it, in parentheses, where the two differ.
+
+import type { ReactNode } from 'react';
+import { formatHotkey } from 'cursedbelt-core/palette/hotkeys';
+import { cn } from '../lib/cn.js';
+
+/** Whose notation a binding is drawn in: ⌘⌥⇧ glyphs, or Ctrl / Alt / Shift words. */
+export type KbdPlatform = 'mac' | 'windows';
+
+export interface KbdProps {
+  /** A binding in the `useHotkeys` format, formatted for this platform. */
+  keys?: string;
+  /** Draw `keys` in this platform's notation; omitted, the browser's own. */
+  platform?: KbdPlatform | 'both';
+  /** A literal cap, when there is no binding to format. */
+  children?: ReactNode;
+  className?: string;
+}
+
+const CAP =
+  'rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-caption font-medium text-muted-foreground';
+
+/** One key cap, in the platform's notation. */
+export function Kbd({ keys, platform, children, className }: KbdProps) {
+  if (keys !== undefined && platform === 'both') {
+    const mac = formatHotkey(keys, true);
+    const windows = formatHotkey(keys, false);
+    if (mac !== windows) {
+      return (
+        <span className={cn('inline-flex items-center gap-1', className)}>
+          <kbd className={CAP}>{mac}</kbd>
+          <span className='text-caption text-muted-foreground'>
+            (<kbd className={CAP}>{windows}</kbd>)
+          </span>
+        </span>
+      );
+    }
+  }
+  const apple = platform === 'mac' ? true : platform === 'windows' ? false : undefined;
+  return <kbd className={cn(CAP, className)}>{keys !== undefined ? formatHotkey(keys, apple) : children}</kbd>;
+}

package/src/react/palette/ShortcutSheet.spec.tsx

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { formatHotkey } from 'cursedbelt-core/palette/hotkeys';
+import { ShortcutSheet } from './ShortcutSheet.js';
+
+afterEach(cleanup);
+
+describe('ShortcutSheet', () => {
+  test('draws each group, each action, and every binding that reaches it in the platform notation', () => {
+    render(
+      <ShortcutSheet
+        open
+        onClose={() => {}}
+        groups={[
+          { heading: 'Anywhere', items: [{ label: 'Search', keys: ['/', '$mod+k'] }] },
+          { heading: 'An open entry', items: [{ label: 'Tags', keys: 'shift+t', where: 'in an open entry' }] },
+        ]}
+      />,
+    );
+    expect(screen.getByRole('region', { name: 'Anywhere' })).toBeTruthy();
+    const rows = Array.from(document.querySelectorAll('[data-cb-shortcut]'));
+    expect(rows).toHaveLength(2);
+    const caps = (row: Element) => Array.from(row.querySelectorAll('kbd')).map((k) => k.textContent);
+    expect(caps(rows[0]!)).toEqual(['/', formatHotkey('$mod+k')]);
+    expect(rows[0]!.textContent).toContain('or');
+    expect(caps(rows[1]!)).toEqual([formatHotkey('shift+t')]);
+    expect(rows[1]!.textContent).toContain('in an open entry');
+  });
+
+  test('platform pins the notation: mac, windows, or both — the Windows chord in parentheses only where it differs', () => {
+    const groups = [{ heading: 'Keys', items: [{ label: 'Find', keys: '$mod+k' }, { label: 'Center', keys: 'c' }] }];
+    const caps = () =>
+      Array.from(document.querySelectorAll('[data-cb-shortcut]')).map((row) =>
+        Array.from(row.querySelectorAll('kbd')).map((k) => k.textContent),
+      );
+    const { rerender } = render(<ShortcutSheet open onClose={() => {}} groups={groups} platform='mac' />);
+    expect(caps()).toEqual([['⌘K'], ['C']]);
+    rerender(<ShortcutSheet open onClose={() => {}} groups={groups} platform='windows' />);
+    expect(caps()).toEqual([['Ctrl K'], ['C']]);
+    rerender(<ShortcutSheet open onClose={() => {}} groups={groups} platform='both' />);
+    expect(caps()).toEqual([['⌘K', 'Ctrl K'], ['C']]);
+    expect(document.querySelector('[data-cb-shortcut]')!.textContent).toContain('(Ctrl K)');
+  });
+
+  test('literal caps draw as written, for a key the grammar cannot spell', () => {
+    render(
+      <ShortcutSheet open onClose={() => {}} groups={[{ heading: 'Move', items: [{ label: 'Up and down', caps: ['↑', '↓'] }] }]} />,
+    );
+    expect(Array.from(document.querySelectorAll('[data-cb-shortcut] kbd')).map((k) => k.textContent)).toEqual(['↑', '↓']);
+  });
+
+  test('Done closes it', () => {
+    const onClose = mock(() => {});
+    render(<ShortcutSheet open onClose={onClose} groups={[]} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Done' }));
+    expect(onClose).toHaveBeenCalled();
+  });
+});

package/src/react/palette/ShortcutSheet.tsx

@@ -0,0 +1,110 @@
+// The `?` sheet — every key an app answers, on one dialog (Linear's and GitHub's `?`). A key that
+// is not written down is a key nobody finds, so an app lists its map here once and the sheet
+// draws it: grouped, the action on the left, its caps on the right in the platform's notation.
+//
+// `platform` is for an app that lets its reader choose the notation (family's Mac / Windows / both
+// setting) — `Kbd`'s own, so 'both' draws the Mac caps with the Windows chord beside them, in
+// parentheses, where the two differ. A key the binding grammar cannot spell ("↑ ↓", "Space (hold)") is `caps`.
+//
+// The app owns `open` and binds `?` itself (outside a field), because only the app knows what
+// counts as typing on its screens. The list is data, so a test can hold it to the handlers.
+
+import type { ReactNode } from 'react';
+import { ActionBar } from '../components/ActionBar.js';
+import { Button } from '../components/Button.js';
+import { Modal } from '../components/Modal.js';
+import { Kbd, type KbdProps } from './Kbd.js';
+
+export interface ShortcutSheetItem {
+  /** What the key does ("Copy the secret"). */
+  label: string;
+  /** One binding (`'$mod+c'`), or several that do the same thing (`['/', '$mod+k']`). */
+  keys?: string | readonly string[];
+  /** Literal caps, drawn as written, for a key the binding grammar cannot spell (`['↑', '↓']`).
+   *  Wins over `keys`. */
+  caps?: readonly string[];
+  /** Where it works, when that is narrower than its group ("in an open entry"). */
+  where?: string;
+}
+
+export interface ShortcutSheetGroup {
+  heading: string;
+  items: readonly ShortcutSheetItem[];
+}
+
+export interface ShortcutSheetProps {
+  open: boolean;
+  onClose: () => void;
+  groups: readonly ShortcutSheetGroup[];
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  /** The notation every binding is drawn in; omitted, the browser's own. 'both' adds the
+   *  Windows chord in parentheses wherever it differs from the Mac's. */
+  platform?: KbdProps['platform'];
+}
+
+/** The keyboard map as a dialog. */
+export function ShortcutSheet({
+  open,
+  onClose,
+  groups,
+  title = 'Keyboard shortcuts',
+  subtitle = 'Keys work anywhere outside a text field.',
+  platform,
+}: ShortcutSheetProps) {
+  return (
+    <Modal
+      open={open}
+      onClose={onClose}
+      size='md'
+      title={title}
+      subtitle={subtitle}
+      footer={
+        <ActionBar
+          primary={
+            <Button variant='primary' tooltip='Close the shortcut list (Esc)' onClick={onClose}>
+              Done
+            </Button>
+          }
+        />
+      }
+    >
+      <div data-cb-shortcut-sheet='' className='flex flex-col gap-6'>
+        {groups.map((group) => (
+          <section key={group.heading} aria-label={group.heading} className='flex flex-col gap-1'>
+            <h3 className='m-0 text-xs font-semibold uppercase tracking-wide text-muted-foreground'>
+              {group.heading}
+            </h3>
+            <ul className='m-0 flex flex-col p-0'>
+              {group.items.map((item) => {
+                const bindings = item.keys === undefined ? [] : typeof item.keys === 'string' ? [item.keys] : item.keys;
+                return (
+                  <li
+                    key={item.label}
+                    data-cb-shortcut=''
+                    className='flex items-center justify-between gap-4 border-b border-border py-2 last:border-b-0'
+                  >
+                    <span className='min-w-0 text-sm'>
+                      {item.label}
+                      {item.where && <span className='text-muted-foreground'> · {item.where}</span>}
+                    </span>
+                    <span className='flex shrink-0 items-center gap-1.5 text-caption text-muted-foreground'>
+                      {item.caps
+                        ? item.caps.map((cap) => <Kbd key={cap}>{cap}</Kbd>)
+                        : bindings.map((binding, index) => (
+                            <span key={binding} className='flex items-center gap-1.5'>
+                              {index > 0 && <span>or</span>}
+                              <Kbd keys={binding} platform={platform} />
+                            </span>
+                          ))}
+                    </span>
+                  </li>
+                );
+              })}
+            </ul>
+          </section>
+        ))}
+      </div>
+    </Modal>
+  );
+}

package/src/react/palette/commandSources.tsx

@@ -21,6 +21,19 @@ import {
 } from 'react';
 import { devWarnOnce } from '../lib/devWarn.js';
 
+/**
+ * A second verb on a row, run by a chord while the row is highlighted — the vault's ⌘C copies an
+ * entry's secret without opening it. The palette closes after it runs, and its footer names the
+ * highlighted row's actions so the chord is discoverable where it works.
+ */
+export interface CommandItemAction {
+  /** The chord, in the `useHotkeys` format (`'$mod+c'`). */
+  keys: string;
+  /** What it does, in the footer ("Copy secret"). */
+  label: string;
+  run: () => void;
+}
+
 export interface CommandSourceItem {
   /** Stable within its source. */
   id: string;
@@ -36,6 +49,8 @@ export interface CommandSourceItem {
   onSelect?: () => void;
   /** Or go somewhere — handed to the palette's `onNavigate`. */
   path?: string;
+  /** Chords that act on this row without selecting it (see {@link CommandItemAction}). */
+  actions?: readonly CommandItemAction[];
 }
 
 export interface CommandSource {
@@ -97,7 +112,13 @@ export function useCommandSources(): CommandSource[] {
 
 /** What a row SHOWS — an entry is replaced only when this changes. */
 const signature = (source: CommandSource): string =>
-  [source.group, ...source.items.map((i) => `${i.id}\u0001${i.label}\u0001${i.sub ?? ''}\u0001${i.path ?? ''}`)].join(
+  [
+    source.group,
+    ...source.items.map(
+      (i) =>
+        `${i.id}\u0001${i.label}\u0001${i.sub ?? ''}\u0001${i.path ?? ''}\u0001${(i.actions ?? []).map((a) => `${a.keys}:${a.label}`).join(',')}`,
+    ),
+  ].join(
     '\u0002',
   );
 
@@ -135,6 +156,14 @@ export function useCommandSource(source: CommandSource): void {
         onSelect: item.onSelect
           ? () => latest.current.items.find((i) => i.id === item.id)?.onSelect?.()
           : undefined,
+        actions: item.actions?.map((action) => ({
+          ...action,
+          run: () =>
+            latest.current.items
+              .find((i) => i.id === item.id)
+              ?.actions?.find((a) => a.keys === action.keys)
+              ?.run(),
+        })),
       })),
     });
   }, [store, key, sig]);