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
/**
* Generalized shortcut recorder: click to arm, press a chord. Keyed chords commit on keydown;
* for allowHoldChord commands a modifier-only chord commits on full release (hold-to-talk).
*
* **Two separate mechanisms hold the keys off, one per process.** In the RENDERER it is this
* component's own `preventDefault` + `stopPropagation` on every key it sees — the window
* dispatcher bails on `defaultPrevented`, so nothing else in the page acts on the chord. The
* `data-shortcut-recording` attribute is NOT part of that path: nothing reads it, and it is kept
* only as the DOM-visible signal that the recorder is armed (tests, debugging, styling hooks). In
* MAIN it is `shortcuts.setRecording`, because a chord the window intercepts in
* `before-input-event` (⌘W, ⌘M, ⌘0) never reaches the page at all — no amount of renderer-side
* preventing can catch a key the page was never given. Recording ⌘W without it DELETES THE
* SELECTED NODES.
*
* **The main-process bit is GLOBAL, so it owes an unmount release.** Chromium does not reliably
* fire `blur` on a focused element that is REMOVED from the DOM, so closing Settings while the
* recorder is armed can skip `onBlur` entirely — leaving the bit set with no component left to
* clear it, suppressing ⌘W/⌘M/⌘0 app-wide until the next arm/disarm cycle. `release` (below) is
* the teardown both `stop()` and the unmount cleanup run; it touches refs only, so it is stable.
* It is safe to run from an instance that was never armed because it CHECKS (`armedRef`) — not
* because the send would be harmless. One global bit, many instances: an unconditional release
* would let a sibling unmounting for unrelated reasons clear the armed recorder's bit.
*
* **A menu accelerator needs a THIRD mechanism, and it now has one.** The main-process bit above
* only stops nodeterm's own `before-input-event` intercepts; the application menu's accelerators
* are handled above the page regardless. So main also DISABLES the command-style menu items in
* `menuItemIdsToSuspend` while this bit is set (`menuStandsDown` → `syncMenuForStandDown` in
* `src/main/index.ts`) — a disabled item suppresses its accelerator, which is what lets ⌘M
* (Window ▸ Minimize), ⌘⇧B (Toggle Kanban Board), ⌘, (Settings) and, off-mac, Ctrl+W (Window ▸
* Close) reach this component instead of acting. Pressing ⌘⇧B or ⌘, into an armed recorder used to
* FIRE — opening the board behind the Settings dialog, or re-opening Settings.
*
* **What stays out of reach**, deliberately: **Reload** (⌘R / ⌘⇧R) is excluded from that list as
* the crash-recovery lever, so it can never be recorded. And the list only covers the items the
* policy stand-down needed — the always-on app roles (`quit` ⌘Q, `hide`/`hideOthers`,
* `toggleDevTools`, `togglefullscreen`) are NOT suspended, so those chords still act while a
* recorder is armed. See `menuItemIdsToSuspend` in `src/main/keydown-intercept.ts`.
*/
import { useCallback, useEffect, useRef, useState } from 'react'
import { COMMANDS_BY_ID, normalizeBindingForCommand, type CommandId } from '@shared/keybindings'
import { isMacPlatform } from '@shared/platform-utils'
import { recordingKeydown, recordingKeyup, type RecordingState } from './shortcutRecording'
import { IconRecordKey } from './ShortcutRowIcons'
import { Tooltip } from '../Tooltip'
const isMac = isMacPlatform()
export function ShortcutRecorderButton({
commandId,
idleLabel,
onCommit,
appearance = 'button',
label,
idleIcon,
tooltip
}: {
commandId: CommandId
idleLabel: string
onCommit: (combo: string) => void
appearance?: 'button' | 'icon'
label?: string
/** Hover-tooltip text for the IDLE `appearance="icon"` button (the app's custom Tooltip, not
* the OS-delayed native one). The icon is the whole visible label, so this is where "replace"
* vs "add another" gets said. Omitted ⇒ the accessible label. */
tooltip?: string
/** The glyph the IDLE `appearance="icon"` button shows — presentational only, and it changes
* nothing else about the recorder. It exists because a row can carry two recorders (Record and
* Add) side by side in one label-less cluster, where the icon IS the label and two identical
* keycaps would leave the pair unreadable. Omitted ⇒ the keycap, so every existing call site
* renders exactly what it did before. */
idleIcon?: React.ReactNode
}): React.JSX.Element {
const [capturing, setCapturing] = useState(false)
const [hint, setHint] = useState('')
const stateRef = useRef<RecordingState>({ mods: null })
// Did THIS instance arm the (global) main-process bit? See `release`.
const armedRef = useRef(false)
const def = COMMANDS_BY_ID.get(commandId)!
const opts = {
isMac,
allowHold: def.allowHoldChord === true,
// Bare keys only where the registry lets the command have one; normalizeBindingForCommand
// (below) still refuses a bare key a command's flags do not permit (e.g. Delete's SAFE set).
allowBare: def.scope === 'board' || def.allowBareKey === true
}
// Refs only ⇒ stable with no deps, so the mount-time cleanup below cannot capture stale state,
// and idempotent ⇒ running it twice, or on an unmount that was never armed, does nothing.
//
// **`armedRef` is what makes it safe to run from every instance.** The main-process bit is ONE
// global boolean while this component is rendered once per command, so a sibling unmounting for
// reasons that have nothing to do with recording must not speak for the armed one. That is not
// hypothetical in this page: settings rows are wrapped in `SearchableRow`, which returns `null`
// for every row the filter box does not match — so typing there unmounts a batch of recorders at
// once. An unconditional `setRecording(false)` in that cleanup would clear the ARMED recorder's
// bit from under it, re-arming ⌘W/⌘M mid-capture: the original bug, reached by a different door.
// Only the instance that sent `true` may send `false`.
const release = useCallback((): void => {
stateRef.current = { mods: null }
if (!armedRef.current) return
armedRef.current = false
window.nodeTerminal.shortcuts.setRecording(false)
}, [])
// The unmount leg — the one that matters most (Settings closed mid-recording fires no blur).
useEffect(() => release, [release])
const stop = (): void => {
setCapturing(false)
setHint('')
release()
}
const start = (): void => {
stateRef.current = { mods: null }
setCapturing(true)
setHint('')
armedRef.current = true
window.nodeTerminal.shortcuts.setRecording(true)
}
const commit = (combo: string): void => {
const r = normalizeBindingForCommand(def, combo, isMac)
if (!r.ok) {
setHint(r.error)
return
}
onCommit(r.value)
stop()
}
const onKeyDown = (e: React.KeyboardEvent<HTMLButtonElement>): void => {
if (!capturing) return
e.preventDefault()
e.stopPropagation()
const action = recordingKeydown(stateRef.current, e, opts)
if (action.kind === 'cancel') stop()
else if (action.kind === 'commit') commit(action.combo)
else if (action.kind === 'pending') {
stateRef.current = action.state
setHint(action.hint)
}
}
const onKeyUp = (e: React.KeyboardEvent<HTMLButtonElement>): void => {
if (!capturing) return
const action = recordingKeyup(stateRef.current, e, opts)
if (action.kind === 'commit') commit(action.combo)
}
const effectiveLabel = label ?? idleLabel
// ARMED look is the design spec's accent pill, identical for both appearances — an armed
// recorder should look the same everywhere. Idle look depends on `appearance`; the 'button'
// idle branch is byte-identical to the pre-appearance markup.
const className = capturing
? 'min-w-[140px] rounded-md border border-accent bg-[color:var(--accent)]/10 px-3 py-1 text-[12px] text-text ring-1 ring-[color:var(--accent)]/40'
: appearance === 'icon'
? // No Tailwind preflight in this repo: `border-0 bg-transparent p-0` must be explicit or
// the browser's native button chrome (border + fill + padding) renders around the glyph.
'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'
: 'min-w-[120px] cursor-pointer rounded-md border border-border bg-panel-header px-3 py-1.5 text-[13px] font-medium text-text outline-none hover:bg-[rgba(255,255,255,0.06)]'
const btn = (
<button
type="button"
// Observability only — no dispatcher reads it (see the header). Keeps the armed state
// visible to tests and to anyone inspecting the DOM.
data-shortcut-recording={capturing || undefined}
className={className}
onClick={start}
onKeyDown={onKeyDown}
onKeyUp={onKeyUp}
onBlur={stop}
// The icon button has no text in EITHER state, so the label is its only accessible name —
// and it must survive arming. Dropping it on capture (as this did) left a screen-reader
// user with a button whose name flipped to the hint text mid-interaction, i.e. no way to
// tell which command is being recorded for. The 'button' appearance keeps its own text and
// is deliberately untouched. There is no native `title`: the icon appearance carries the
// app's custom Tooltip below instead, and two tooltips for one hover is noise.
aria-label={appearance === 'icon' ? effectiveLabel : undefined}
>
{capturing ? (
<>
<span className="mr-1.5 inline-block size-1.5 rounded-full bg-accent animate-pulse" />
{hint || 'Press keys…'}
</>
) : appearance === 'icon' ? (
(idleIcon ?? <IconRecordKey />)
) : (
idleLabel
)}
</button>
)
// Only the icon appearance gets the custom tooltip — the 'button' appearance has visible text,
// and wrapping it would change its markup. `appearance` is fixed per instance, so the wrapper
// never appears/disappears mid-capture (that would remount the armed button and kill capture).
if (appearance !== 'icon') return btn
return (
<Tooltip label={capturing ? 'Press the new shortcut · Esc cancels' : (tooltip ?? effectiveLabel)}>
{btn}
</Tooltip>
)
}