Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
/**
* The Keyboard Shortcuts settings section: one dense row per registry command, with its live
* chips, a per-chip ×, and hover-revealed Record / Add / Disable / Reset icon controls, under a
* filter rail (a local query + a status pill carrying live counts).
*
* **The rail's filtering is LOCAL and additive to the global settings search.** A row is on
* screen only when all three agree: the settings search (`SearchableRow`, unchanged), the rail's
* query (`matchesShortcutQuery` — which also searches the CHORDS, something the global search
* cannot see) and the status filter. The rail's counts deliberately ignore the status filter, so
* they describe the buckets rather than the current selection. Groups get one wrapper each,
* because the shell's body is `divide-y [&>*]:py-5` and a row per direct child made 21 dividers.
*
* **The pre-save gate is `commitCandidate`, and it is where the refusal messages are decided.**
* Design D3 is "same detector, different surfacing": `sanitizeKeybindingOverrides` applies what
* survives on LOAD, while this section refuses a bad candidate BEFORE anything is written, so the
* user learns which chord was refused and why instead of watching a saved shortcut disappear on
* the next launch. The checks run in this order, and the order is the whole dedupe:
* 1. `normalizeBindingForCommand` — already inside `ShortcutRecorderButton`, so an invalid chord
* never reaches `onCommit` (its own hint is shown in the recorder button itself).
* 2. `findKeybindingConflicts` over the candidate map — a same-bucket collision.
* 3. `findMainInterceptShadowing` — a CROSS-bucket hit the conflict check cannot see.
* 4. REVERSE shadowing — the same collision seen from the non-intercepted side.
* 5. The two DICTATION overlap gates — the one overlap `conflictBuckets` deliberately does not
* report, refused here in both directions, but only for `app`/`canvas`-scope commands: the
* keyed gesture has a focus gate, so a terminal- or scm-scope command never competes with it
* (see the block itself for why).
* (2) returns early, so a candidate that trips both detectors (a main-intercepted command taking
* a chord another GLOBAL command already holds — `node.close` ← `Cmd+K`) produces exactly ONE
* message. The shadow message is reserved for what only it can see: `node.close` ← `Cmd+F`, where
* the two commands live in different buckets and nothing collides, yet main swallows the key
* before the terminal surface is ever offered it.
*
* Writes go through `setKeybindingOverride` (the single write path — it also mirrors
* `speech.dictation` into the legacy `settings.speech.shortcut` field for one release).
*/
import { useMemo, useState } from 'react'
import { IconClose } from '../../icons'
import {
bindingIdentity,
COMMANDS_BY_ID,
COMMAND_DEFINITIONS,
findKeybindingConflicts,
findMainInterceptShadowing,
MAIN_INTERCEPTED_COMMAND_IDS,
normalizeTerminalShortcutPolicy,
type CommandDefinition,
type CommandGroup,
type CommandId,
type KeybindingOverrides,
type TerminalShortcutPolicy
} from '@shared/keybindings'
import { formatShortcut } from '@shared/shortcut'
import { isMacPlatform, keyLabel } from '@shared/platform-utils'
import {
activeKeybindingOverrides,
commandKeysFor,
effectiveBindings,
setKeybindingOverride
} from '../../../lib/keybindingOverrides'
import { useSettings } from '../../../state/settings'
import { SettingsSection } from '../SettingsSection'
import { SearchableRow } from '../SearchableRow'
import { FieldRow } from '../FieldRow'
import { ShortcutRecorderButton } from '../ShortcutRecorderButton'
import { IconDisableSlash, IconPlusSmall, IconResetArrow } from '../ShortcutRowIcons'
import { Tooltip } from '../../Tooltip'
import { Input } from '@renderer/ui/Input'
import { SegmentedPill } from '@renderer/ui/SegmentedPill'
import { useSettingsSearch } from '../context'
import { matchesQuery, type SettingsSearchEntry } from '../search'
import {
matchesShortcutQuery,
rowPassesStatus,
shortcutRowStatus,
type ShortcutRowStatus,
type ShortcutStatusFilter
} from '../shortcutFilter'
/** Per-command help text. Only commands whose BEHAVIOR needs explaining get one — a row that
* merely repeats its own title is noise in a 20-row list. */
const NOTES: Partial<Record<CommandId, string>> = {
// Reused verbatim from the old SpeechSection row: the mode is derived from the chord's SHAPE,
// which is not guessable from a chip.
'speech.dictation':
'With a key = toggle (press to start, press again to stop and insert); modifiers only = hold to talk (hold to record, release to stop and insert). The Dock mic uses the same shortcut. A keyed dictation chord is claimed before any other shortcut while the canvas has focus.',
'canvas.deleteSelection': 'Bare keys are allowed here; the typing guard keeps Backspace safe.',
'terminal.copySelection': 'Applies to a selection xterm owns — a tmux drag copies through OSC 52.'
}
/** The policy row is NOT a registry command, so it carries its own search entry and its own
* `SearchableRow` — putting it inside a group Fragment would make `groupVisible` (which only
* knows about commands) decide whether a *setting* is on screen. */
const POLICY_LABEL = 'While a terminal has focus'
const POLICY_DESCRIPTION =
"App shortcuts first (the default): shared shortcuts like ⌘K keep working over a focused terminal, and the first time one is captured that way the terminal says so — once per chord, ever. Terminal first: every chord but the terminal's own reaches the shell or TUI, including Close (⌘W / Ctrl+W), Minimize (⌘M / Ctrl+M), actual size (⌘0), the kanban board (⌘⇧B), Settings (⌘,) and the ⌘1–9 project jumps — the matching application-menu entries grey out while a terminal is focused, so those chords can reach it. Reload (⌘R / ⌘⇧R) is the one exception and always stays with the app, so a stuck window can still be recovered."
const POLICY_ROW: SettingsSearchEntry = {
title: POLICY_LABEL,
description: POLICY_DESCRIPTION,
keywords: ['shortcut', 'terminal', 'tui', 'shell', 'policy', 'first', 'capture', 'minimize']
}
function rowEntry(def: CommandDefinition): SettingsSearchEntry {
return {
title: def.title,
description: NOTES[def.id],
keywords: ['shortcut', 'keybinding', 'hotkey', 'key', def.group, def.id]
}
}
/**
* Everything the LOCAL matcher searches, derived from the entry the GLOBAL settings search
* already gets — so the two can never disagree about which rows exist.
*
* They are not the same shape: `rowEntry` puts the per-command NOTE in `description` (never in
* `keywords`), `matchesQuery` searches title + description + keywords, and
* `matchesShortcutQuery` has no description slot at all. Passing `entry.keywords` alone would
* therefore lose the note: 'tmux' finds Copy terminal selection in the sidebar search and
* NOTHING in the rail, on the same screen. The note rides along as one more keyword instead.
*/
function rowKeywords(entry: SettingsSearchEntry): string[] {
const keywords = entry.keywords ?? []
return entry.description ? [...keywords, entry.description] : keywords
}
/** The rail is not a registry command, so — like the policy row — it carries its own search
* entry: a query for 'unassigned' must keep the control that offers that filter. */
const RAIL_ROW: SettingsSearchEntry = {
title: 'Filter shortcuts',
keywords: ['filter', 'search', 'modified', 'unassigned', 'disabled']
}
/** The row's per-command controls: 16px glyph in a 24px hit target, color from the parent.
* The repo ships no Tailwind preflight, so `border-0 bg-transparent p-0` must be explicit —
* without them the browser's native button chrome (border + fill + padding) renders. */
const ICON_BUTTON =
'flex size-6 cursor-pointer items-center justify-center rounded-md border-0 bg-transparent p-0 text-muted hover:bg-fill-weak hover:text-text focus-visible:text-text'
/** Shared pill geometry — the accent/neutral fill is appended per badge. */
const BADGE = 'rounded-full px-2 py-0.5 text-[11px] font-medium'
/** Commands whose consumers read the FIRST effective binding only, so a second chord would be
* dead on arrival. `speech.dictation` is the case: every dictation surface (the hold listener,
* the keyed gesture, the Dock mic, SpeechSection's note) goes through `dictationBinding()`, which
* is `effectiveBindings('speech.dictation')[0]`. Their rows get no Add and show one chip. */
const SINGLE_BINDING_COMMANDS: ReadonlySet<CommandId> = new Set<CommandId>(['speech.dictation'])
function groupEntry(group: CommandGroup, defs: CommandDefinition[]): SettingsSearchEntry {
// The header must survive any query that keeps one of its rows, so its keywords are the union
// of what those rows match on — otherwise a filtered list shows rows under the wrong heading.
return {
title: group,
keywords: ['shortcut', 'keybinding', 'hotkey', ...defs.flatMap((d) => [d.title, d.id])]
}
}
/** Does this group have anything to show under the current query? It decides BOTH the heading and
* the group's presence, which is why the heading is not a `SearchableRow` of its own: a row can
* match on its per-command note (`NOTES`) — query "tmux" hits Copy terminal selection — and a
* heading filtered independently would then leave that row standing under no heading at all. */
function groupVisible(query: string, group: CommandGroup, defs: CommandDefinition[]): boolean {
if (query.trim() === '') return true
return (
matchesQuery(query, groupEntry(group, defs)) || defs.some((d) => matchesQuery(query, rowEntry(d)))
)
}
/**
* The testable core the row controls delegate to: gate a candidate binding, then write it.
* `mode` is `'replace'` (the recorder's primary action) or `'add'` (a second chord for the same
* command). Re-adding a chord the command already holds is idempotent rather than a
* self-conflict — it is filtered out of the list before being appended.
*
* Assumes `combo` is already canonical: `ShortcutRecorderButton` runs
* `normalizeBindingForCommand` and never emits an invalid chord.
*/
export function commitCandidate(
id: CommandId,
combo: string,
mode: 'replace' | 'add'
): { ok: true } | { ok: false; error: string } {
const isMac = isMacPlatform()
const current = activeKeybindingOverrides()
const existing = effectiveBindings(id)
const nextList = mode === 'add' ? [...existing.filter((b) => b !== combo), combo] : [combo]
const chord = formatShortcut(combo, isMac)
// The candidate's platform identity, computed ONCE: the reverse-shadow block and both dictation
// gates all ask the same question of it, and three copies of one call is three chances to drift.
const identity = bindingIdentity(combo, isMac)
const conflicts = findKeybindingConflicts({ ...current, [id]: nextList }, isMac).filter((c) =>
c.commandIds.includes(id)
)
if (conflicts.length) {
const titles = [
...new Set(
conflicts
.flatMap((c) => c.commandIds)
.filter((cid) => cid !== id)
.map((cid) => COMMANDS_BY_ID.get(cid)?.title ?? cid)
)
]
return { ok: false, error: `${chord} is already used by ${titles.join(', ')}.` }
}
const shadowed = findMainInterceptShadowing(id, combo, current, isMac)
if (shadowed.length) {
const titles = shadowed.map((cid) => COMMANDS_BY_ID.get(cid)?.title ?? cid).join(', ')
return { ok: false, error: `${chord} would be swallowed app-wide before ${titles} could see it.` }
}
// REVERSE shadowing — the same collision seen from the other side, and neither gate above can
// see it. `findMainInterceptShadowing` answers only for an INTERCEPTED id, and a bucket conflict
// needs both commands in one bucket; binding `terminal.find` to `Cmd+W` is neither, so it passed
// every check and produced a permanently dead shortcut with no warning — main swallows the chord
// in `before-input-event` and the terminal surface is never offered it.
if (!MAIN_INTERCEPTED_COMMAND_IDS.includes(id)) {
for (const cid of MAIN_INTERCEPTED_COMMAND_IDS) {
const hit = effectiveBindings(cid).some((b) => bindingIdentity(b, isMac) === identity)
if (!hit) continue
const title = COMMANDS_BY_ID.get(cid)?.title ?? cid
const own = COMMANDS_BY_ID.get(id)?.title ?? id
return {
ok: false,
error: `${chord} is intercepted app-wide for ${title}; it would never reach ${own}.`
}
}
}
// DICTATION OVERLAP, both directions. `speech.dictation` is its own conflict bucket (see
// `conflictBuckets` in @shared/keybindings), so gate (2) above is silent about it BY DESIGN —
// dictation never competes at dispatch, it PRE-EMPTS: the resolver skips it and its own keyed
// listener claims the chord first while the canvas has focus. That is precedence, not ambiguity,
// which is why the LOAD path permits an overlap (legacy files contain them, and dropping a user's
// chord is the failure that bucket closes) while a chord a user picks HERE is refused instead:
// an interactive pick deserves to be told about the precedence, not to discover it later.
//
// Both gates are keyed-only WITHOUT an explicit hold guard: `bindingIdentity` renders a
// modifier-only chord as `…:(hold)`, which no keyed identity can ever equal — so the default
// `Cmd+Alt` hold chord blocks nothing, and a hold candidate trips nothing.
//
// Both are also SCOPED to `app`/`canvas`, because the gesture has a FOCUS GATE: the keyed
// dictation listener runs only in plain app focus (`dispatchGlobalKeydown` in
// `renderer/lib/globalKeybindings.ts` — `!ctx.typing && !ctx.terminal && !ctx.kanbanOpen`). A
// `terminal`- or `scm`-scope command dispatches ONLY where that gate is already shut, so it
// never competes with dictation for its chord; refusing the overlap would forbid a binding that
// was legal before this branch and still works at dispatch (⌘⌥D on Find in terminal, say).
const dictationId: CommandId = 'speech.dictation'
const dictationTitle = COMMANDS_BY_ID.get(dictationId)?.title ?? dictationId
const candidateScope = COMMANDS_BY_ID.get(id)?.scope
if (id !== dictationId && (candidateScope === 'app' || candidateScope === 'canvas')) {
// "rarely", not "never": dictation's keyed listener only claims the chord where it listens.
// An app-scope command flagged `allowInTerminal` still fires in terminal focus under
// app-first — the message must not overclaim a chord that is merely usually lost.
const taken = effectiveBindings(dictationId).some((b) => bindingIdentity(b, isMac) === identity)
if (taken) {
const own = COMMANDS_BY_ID.get(id)?.title ?? id
return {
ok: false,
error: `${chord} is used by ${dictationTitle}, which claims it first; it would rarely reach ${own}.`
}
}
} else if (id === dictationId) {
for (const def of COMMAND_DEFINITIONS) {
if (def.id === dictationId) continue
// The same focus gate, read from the other side: a focused-surface command cannot be hidden
// by a gesture that is never offered on that surface.
if (def.scope === 'terminal' || def.scope === 'scm') continue
const hit = effectiveBindings(def.id).some((b) => bindingIdentity(b, isMac) === identity)
if (!hit) continue
return {
ok: false,
error: `${chord} is already used by ${def.title}; ${dictationTitle} would claim it first and hide it.`
}
}
}
setKeybindingOverride(id, nextList)
return { ok: true }
}
/**
* The row's chords, as keycap chips.
*
* `limit` exists for `speech.dictation`: its consumers read `dictationBinding()` — the FIRST
* effective binding — so showing a second chip would promise a chord that can never fire.
*
* `onRemove` is what turns each chip group into a removable one (the trailing ×). It is
* `undefined` unless the caller decided removal is offered at all, so a chip that is the
* command's ONLY chord never grows an × — that would be a Disable in disguise, and Disable is
* its own control with its own meaning (`[]`, not "no override").
*/
function Chips({
chords,
limit,
title,
onRemove
}: {
chords: readonly (readonly string[])[]
limit?: number
title: string
onRemove?: (index: number) => void
}): React.JSX.Element {
const isMac = isMacPlatform()
const keys = limit === undefined ? chords : chords.slice(0, limit)
if (keys.length === 0) return <></>
return (
<span className="flex items-center gap-2">
{keys.map((parts, i) => (
<span key={i} className="flex items-center gap-1">
{i > 0 ? <span className="text-[11px] text-muted">or</span> : null}
{parts.map((p, j) => (
<kbd key={j} className="kbd">
{keyLabel(p)}
</kbd>
))}
{onRemove ? (
<button
type="button"
// The chord is named in the label because a row can hold several: "Remove" alone
// would leave a screen reader with N identical buttons.
aria-label={`Remove ${isMac ? parts.join('') : parts.join('+')} from ${title}`}
title="Remove this shortcut"
onClick={() => onRemove(i)}
className="cursor-pointer border-0 bg-transparent px-0.5 text-[12px] leading-none text-muted opacity-0 group-hover/row:opacity-60 hover:!opacity-100 focus-visible:opacity-100"
>
<IconClose />
</button>
) : null}
</span>
))}
</span>
)
}
/** One row's precomputed facts: its search entry, its chords (read ONCE — the counts and the
* rendered list must not take two different reads of the override map) and its status. */
interface RowModel {
def: CommandDefinition
entry: SettingsSearchEntry
keywords: string[]
chords: string[][]
status: ShortcutRowStatus
}
export function ShortcutsSection({ isActive }: { isActive: boolean }): React.JSX.Element {
// Any remap re-renders every row: chips, and the Add/Disable/Reset visibility, are all derived
// from the override map.
const overrides = useSettings((s) => s.settings.keybindings)
// Read through the normalizer, never as the raw field: settings.json is hand-editable, so the
// compile-time type is not a runtime guarantee and an unknown value must render as `app-first`
// — the same degrade `terminalShortcutPolicy()` applies at dispatch, so the pill cannot show a
// policy the dispatcher is not using.
const policy = normalizeTerminalShortcutPolicy(
useSettings((s) => s.settings.terminalShortcutPolicy)
)
const update = useSettings((s) => s.update)
const query = useSettingsSearch()
const [errors, setErrors] = useState<Partial<Record<CommandId, string>>>({})
// The rail's two controls. Local to the section on purpose: they are a way of LOOKING at the
// list, not a setting — nothing about them belongs in settings.json.
const [filterQuery, setFilterQuery] = useState('')
const [statusFilter, setStatusFilter] = useState<ShortcutStatusFilter>('all')
const groups = useMemo(() => {
const byGroup = new Map<CommandGroup, CommandDefinition[]>()
for (const def of COMMAND_DEFINITIONS) {
byGroup.set(def.group, [...(byGroup.get(def.group) ?? []), def])
}
return [...byGroup.entries()]
}, [])
const entries = useMemo(
() => [
POLICY_ROW,
RAIL_ROW,
...groups.map(([group, defs]) => groupEntry(group, defs)),
...COMMAND_DEFINITIONS.map(rowEntry)
],
[groups]
)
/**
* The RAW `settings.keybindings`, narrowed to the entries whose value is actually a list.
*
* **`shortcutRowStatus` reads `override.length`, and the raw map is not typed at runtime.**
* `settings.keybindings` is hand-editable JSON and `mergeSettings` passes it through with no
* per-value validation, so `{"canvas.undo": null}` arrives here verbatim — inside a memo that
* runs on every render, with no error boundary above Settings, which means a `TypeError` here
* blanks the whole renderer and takes away the page the user would have opened to repair the
* value. The pre-redesign row carried this guard inline
* (`Array.isArray(override) && override.length === 0`); this is that guard, at the one call
* site that still needs it. `shortcutFilter.ts` is pure and stays as shipped: a malformed
* value is this section's to keep out, not that module's to tolerate.
*
* A non-array entry reads as **absent** — the row shows its default, offers no Reset and is
* not counted as Modified. That is the truth rather than a degrade: the sanitized read path
* (`sanitizeKeybindingOverrides`, which already ignores it) is what the chips and every gate
* are showing, so there is no override for a Reset to undo.
*/
const listOverrides = useMemo<KeybindingOverrides>(() => {
const out: KeybindingOverrides = {}
for (const def of COMMAND_DEFINITIONS) {
const value = overrides?.[def.id]
if (Array.isArray(value)) out[def.id] = value
}
return out
}, [overrides])
// One read of the override map per render pass, shared by the counts and by the rendered rows.
// Two reads would be two chances to disagree — the pill saying `Modified 2` over one row.
const models = useMemo<RowModel[]>(
() =>
COMMAND_DEFINITIONS.map((def) => {
const entry = rowEntry(def)
const chords = commandKeysFor(def.id)
return {
def,
entry,
keywords: rowKeywords(entry),
chords,
status: shortcutRowStatus(def.id, listOverrides, chords.length)
}
}),
[listOverrides]
)
const modelById = useMemo(() => new Map(models.map((m) => [m.def.id, m])), [models])
// Counts are taken over EVERY command that passes the local query, before the status filter is
// applied — they say how big each bucket is inside what the user is looking at, which is the
// only reading that lets the pill be used to navigate. (A count that also honored the status
// filter would read `Modified 2` beside two rows and `0` beside every other option.)
const counts = useMemo(() => {
const c = { all: 0, modified: 0, unassigned: 0, disabled: 0 }
for (const m of models) {
if (!matchesShortcutQuery(m.def, m.keywords, m.chords, filterQuery)) continue
c.all += 1
if (m.status.modified) c.modified += 1
if (m.status.unassigned) c.unassigned += 1
if (m.status.disabled) c.disabled += 1
}
return c
}, [models, filterQuery])
const apply = (id: CommandId, combo: string, mode: 'replace' | 'add'): void => {
const r = commitCandidate(id, combo, mode)
setErrors((prev) => ({ ...prev, [id]: r.ok ? undefined : r.error }))
}
const write = (id: CommandId, bindings: readonly string[] | null): void => {
setKeybindingOverride(id, bindings)
setErrors((prev) => ({ ...prev, [id]: undefined }))
}
/** Per-chip ×. A plain list write through `write`, deliberately NOT through `commitCandidate`:
* taking a chord away cannot CREATE a conflict, so there is no candidate to gate — and routing
* it through the gate would let an unrelated pre-existing refusal block a removal that is
* always safe. The index is into `effectiveBindings`, which is the same order `commandKeysFor`
* renders the chips in. */
const removeBinding = (id: CommandId, index: number): void => {
write(
id,
effectiveBindings(id).filter((_, i) => i !== index)
)
}
// What is on screen, decided before render because the group wrappers need the answer: a group
// renders only when the GLOBAL query keeps it (`groupVisible` — a heading must never outlive
// its rows) AND at least one of its rows survives the local query, the status filter and that
// same global query. An empty wrapper is not invisible here: the shell's body is
// `divide-y [&>*]:py-5`, so it draws a padded strip with a divider over nothing.
const localVisible = (m: RowModel): boolean =>
matchesShortcutQuery(m.def, m.keywords, m.chords, filterQuery) &&
rowPassesStatus(m.status, statusFilter)
const visibleGroups = groups.flatMap(([group, defs]) => {
if (!groupVisible(query, group, defs)) return []
const rows = defs.map((d) => modelById.get(d.id)!).filter(localVisible)
// The global leg is asked here only to COUNT; `SearchableRow` below is what actually mounts
// or drops the row (and with it its recorder — see ShortcutRecorderButton's release note).
if (!rows.some((m) => matchesQuery(query, m.entry))) return []
return [{ group, rows }]
})
const renderRow = (m: RowModel): React.JSX.Element => {
const { def, chords, status } = m
const single = SINGLE_BINDING_COMMANDS.has(def.id)
const bound = chords.length > 0
const note = NOTES[def.id]
const error = errors[def.id]
return (
<SearchableRow key={def.id} {...m.entry}>
<div
data-command={def.id}
className="group/row -mx-2 flex items-start justify-between gap-4 rounded-lg px-2 py-2 transition-colors hover:bg-fill-weak/60"
>
<div className="min-w-0">
<div className="flex flex-wrap items-center gap-2">
<span className="text-sm font-medium text-text">{def.title}</span>
{status.modified ? (
<span
data-badge="modified"
className={`${BADGE} bg-[color:var(--accent)]/15 text-[color:var(--accent)]`}
>
Modified
</span>
) : null}
{def.scope === 'terminal' ? (
<span data-badge="terminal" className={`${BADGE} bg-fill-weak text-muted`}>
Terminal
</span>
) : null}
</div>
{note ? <p className="mt-1 text-[12px] leading-relaxed text-muted">{note}</p> : null}
{error ? (
<p className="mt-1 text-[12px] leading-relaxed text-[color:var(--warn)]">{error}</p>
) : null}
</div>
<div className="flex shrink-0 items-center gap-2">
{bound ? (
<Chips
chords={chords}
limit={single ? 1 : undefined}
title={def.title}
onRemove={
chords.length > 1 && !single ? (i) => removeBinding(def.id, i) : undefined
}
/>
) : status.disabled ? (
<span className={`${BADGE} bg-fill-weak text-muted`}>Disabled</span>
) : (
<span className="text-[13px] text-muted">—</span>
)}
{/* Hidden until the row is hovered so a 21-row list reads as chords, not as a wall of
buttons — `focus-within` is the keyboard user's door to the same controls. */}
<div className="flex items-center gap-0.5 opacity-0 transition-opacity focus-within:opacity-100 group-hover/row:opacity-100">
{/* Tooltips say what the glyphs cannot: Record REPLACES the current shortcut,
Add records ANOTHER one beside it. Native `title` is not used here — it takes
the OS's ~1.5s delay and reads as no tooltip at all. */}
<ShortcutRecorderButton
commandId={def.id}
appearance="icon"
idleLabel={bound ? 'Record' : 'Record shortcut'}
label={bound ? `Record ${def.title}` : `Record shortcut for ${def.title}`}
tooltip={bound ? 'Replace shortcut' : 'Record a shortcut'}
onCommit={(combo) => apply(def.id, combo, 'replace')}
/>
{bound && !single ? (
<ShortcutRecorderButton
commandId={def.id}
appearance="icon"
idleLabel="Add"
label={`Add a shortcut to ${def.title}`}
tooltip="Add another shortcut"
// Record sits immediately to its left in the same label-less cluster; the
// glyph is the only thing telling the two apart.
idleIcon={<IconPlusSmall />}
onCommit={(combo) => apply(def.id, combo, 'add')}
/>
) : null}
{bound ? (
<Tooltip label="Disable shortcut">
<button
type="button"
className={ICON_BUTTON}
aria-label={`Disable ${def.title}`}
onClick={() => write(def.id, [])}
>
<IconDisableSlash />
</button>
</Tooltip>
) : null}
{status.modified ? (
<Tooltip label="Reset to default">
<button
type="button"
className={ICON_BUTTON}
aria-label={`Reset ${def.title}`}
onClick={() => write(def.id, null)}
>
<IconResetArrow />
</button>
</Tooltip>
) : null}
</div>
</div>
</div>
</SearchableRow>
)
}
return (
<SettingsSection
id="shortcuts"
title="Keyboard Shortcuts"
// The one remaining limitation is the application MENU's, not macOS's: its accelerators are
// handled above the page on every platform. While a recorder is armed main now suspends the
// items in `menuItemIdsToSuspend` (Minimize, Toggle Kanban Board, Settings, off-mac Close),
// so those chords reach the recorder — but RELOAD is deliberately never suspended, because it
// is the crash-recovery lever. See `src/main/keydown-intercept.ts`.
// The residual clause is the KNOWN GAP `menuItemIdsToSuspend` documents: one list drives
// both stand-downs, so the always-on app roles are deliberately left unsuspended and still
// act while recording. The ruling stands; the user is simply told.
description="Remap any command. Overrides are stored in settings.json under `keybindings`; Disable turns a command's shortcut off, Reset restores its default. Reload (⌘R / ⌘⇧R) cannot be recorded — it always stays with the app; the system-level chords the menu keeps — ⌘Q (Quit), ⌘H (Hide) and the developer roles — also act while recording, so don't try to bind them."
isActive={isActive}
searchEntries={entries}
>
<SearchableRow {...POLICY_ROW}>
<div data-setting="terminal-shortcut-policy">
<FieldRow
label={POLICY_LABEL}
description={POLICY_DESCRIPTION}
control={
<SegmentedPill<TerminalShortcutPolicy>
value={policy}
ariaLabel={POLICY_LABEL}
options={[
{ value: 'app-first', label: 'App shortcuts first' },
{ value: 'terminal-first', label: 'Terminal first' }
]}
onChange={(v) => update({ terminalShortcutPolicy: v })}
/>
}
/>
</div>
</SearchableRow>
<SearchableRow {...RAIL_ROW}>
<div className="flex items-center justify-between gap-4">
<div className="relative">
{/* The sidebar's magnifier, verbatim — one search affordance, one look. */}
<svg
aria-hidden="true"
className="pointer-events-none absolute left-2.5 top-1/2 -translate-y-1/2 text-muted-2"
width="14"
height="14"
viewBox="0 0 14 14"
fill="none"
stroke="currentColor"
strokeWidth="1.5"
strokeLinecap="round"
>
<circle cx="6" cy="6" r="4" />
<path d="M9.2 9.2 12 12" />
</svg>
<Input
className="h-8 w-[220px] pl-8"
value={filterQuery}
onChange={(e) => setFilterQuery(e.target.value)}
placeholder="Filter shortcuts"
aria-label="Filter shortcuts"
/>
</div>
<SegmentedPill<ShortcutStatusFilter>
value={statusFilter}
ariaLabel="Filter shortcuts by status"
options={[
{ value: 'all', label: `All ${counts.all}` },
{ value: 'modified', label: `Modified ${counts.modified}` },
{ value: 'unassigned', label: `Unassigned ${counts.unassigned}` },
{ value: 'disabled', label: `Disabled ${counts.disabled}` }
]}
onChange={setStatusFilter}
/>
</div>
</SearchableRow>
{/* One wrapper per group, so the shell's `divide-y` separates GROUPS rather than every
single row — 21 dividers is a table, not a list. */}
{visibleGroups.map(({ group, rows }) => (
<div key={group} className="space-y-1">
<h3 className="text-[13px] font-semibold uppercase tracking-wide text-muted">{group}</h3>
{rows.map(renderRow)}
</div>
))}
{/* The sentence is ABOUT the rail, so it rides the rail's OWN search entry and can never
outlive the control it explains. A global settings query can keep this section for the
policy row alone ('policy', 'shell', 'tui', 'minimize' appear in no command title, id,
group or note) — and answering that with "No shortcuts match." would describe a filter
that is not on screen, in a section showing exactly what was asked for. */}
<SearchableRow {...RAIL_ROW}>
{visibleGroups.length === 0 ? (
<p className="text-[13px] text-muted">No shortcuts match.</p>
) : null}
</SearchableRow>
</SettingsSection>
)
}