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
/**
* Who decides which terminal node holds the keyboard: the POINTER, or a CLICK.
*
* Issue #757 — "option to disable X Window focus-follows-pointer (Mac-style click to select what
* UI element has the input focus)". `TerminalNode`'s hover guard has always tied the keyboard to
* the pointer: dwelling `settings.panHoverDelay` over a terminal focuses its xterm, and
* `mouseleave` blurs it again and drops the node's agent-status active flag and presence focus. On
* a crowded canvas that is the X11 "focus follows mouse" model, and a user who reaches for another
* card, a second display or the sidebar while an agent is mid-prompt loses the keyboard every time.
*
* `settings.terminalFocusFollowsPointer` (default ON — the long-standing behaviour) picks the model:
*
* - **ON — focus follows the pointer, sloppily.** A hover dwell takes the keyboard, and the
* terminal KEEPS it after the pointer leaves — until another node takes it (its own dwell, a
* click) or the user clicks elsewhere. This used to be strict X11 focus-follows-mouse, where
* `mouseleave` blurred the xterm and dropped the active flag and presence focus: typing into a
* terminal while the mouse rested on the canvas silently went nowhere, and so did every reach for
* the sidebar mid-prompt. Only the hover GUARD still follows the pointer here (leaving re-arms
* it, so a pass-over scroll pans the canvas until the next dwell).
* - **OFF — click to focus.** The pointer decides nothing. A click on the terminal (the guard's
* `onGuardClick` → `enterNow`, issue #87) or a "go to node" request takes the keyboard, and the
* terminal KEEPS it until focus really goes somewhere else: another node, the empty canvas
* (whose `onPaneClick` blurs the xterm textarea, issue #86), a text field. The guard follows
* DOM focus too.
*
* In BOTH modes the node's active flag and presence focus follow DOM focus, through
* `useClickToFocus` (named for #757, where it was born) — see `focusLossOutcome`. The modes differ
* only in how the keyboard is TAKEN (dwell or click) and in who owns the guard.
*
* Pure so the decisions are testable without a mounted xterm; `TerminalNode` owns the effects.
*/
/**
* The setting as read from a hand-editable settings.json: only a literal `false` switches to click
* to focus. Anything else (absent, a string, null) keeps the long-standing default, so a mangled
* file can never silently change how every terminal takes the keyboard.
*/
export function resolveFocusFollowsPointer(value: unknown): boolean {
return value !== false
}
/** Does a hover dwell over the body hand the keyboard to the terminal? */
export function hoverTakesKeyboard(focusFollowsPointer: boolean): boolean {
return focusFollowsPointer
}
/**
* Does the pointer leaving the body re-arm the hover guard? Only while focus follows the pointer,
* where the guard is a pointer contract. It never takes the keyboard away, in either mode: the
* keyboard, the active flag and presence focus are released by `focusLossOutcome`, which follows
* where the KEYBOARD goes rather than where the mouse goes.
*/
export function pointerLeaveRearmsGuard(focusFollowsPointer: boolean): boolean {
return focusFollowsPointer
}
/**
* Do DOM focus changes arm and disarm the hover guard (`useClickToFocus`'s `setArmed`)?
*
* Only in click to focus, where the guard has no other owner. While focus follows the pointer the
* dwell, a click and `mouseleave` own it, and focus moving would get it wrong both ways: a release
* while the pointer rests on the body (⌘K, a sidebar jump) would re-arm it with no `mouseenter`
* coming to restart the dwell, and a reclaim after a header drag would drop it while the pointer is
* elsewhere, so the next pass-over scroll would reach tmux instead of panning the canvas.
*/
export function focusDrivesGuard(focusFollowsPointer: boolean): boolean {
return !focusFollowsPointer
}
/**
* Should a hover dwell that has just made this node active blur the element holding the keyboard?
*
* With sloppy focus the dwell onto the NEXT node is what moves the keyboard: focusing its xterm
* takes it from the terminal the user came from. A node whose ⌘M view covers its xterm cannot take
* it (`focusXtermUnlessCovered`), so the previous terminal would keep receiving keystrokes while
* this node reads as the active one — typing into a pane nobody is looking at. Only ANOTHER
* terminal's xterm is blurred: a sticky, an editor or a text field keeps its caret, exactly as it
* did when `mouseleave` was what released a terminal.
*/
export function dwellBlursForeignTerminal(p: { covered: boolean; activeIsForeignXterm: boolean }): boolean {
return p.covered && p.activeIsForeignXterm
}
/** The slice of a node's root element this module reads. */
export interface NodeRootLike {
contains(other: unknown): boolean
}
export interface FocusLossEvent {
/** The node's root (`.term-node`), or null if it is gone. */
nodeRoot: NodeRootLike | null
/** The node's React Flow wrapper (`.react-flow__node`), which also holds the root's SIBLINGS —
* the 💬 comments flyout sits outside the root (overflow:hidden would clip it) but inside this. */
nodeChrome: NodeRootLike | null
/** The element that lost focus (`focusout`'s target). */
lost: unknown
/** Where focus went (`focusout`'s `relatedTarget`); null for "nowhere" AND for a window blur. */
gained: unknown
/** `document.activeElement` at the time of the event. */
activeElement: unknown
/** `document.hasFocus()` at the time of the event. */
windowFocused: boolean
/** A press landed on THIS node (its React Flow wrapper, header included) in the same task — the
* focus change is that press's default action, not a click somewhere else. */
pressedInOwnNode: boolean
/** That press landed on text the user READS and may select — the ⌘M chat's message list. The
* press is the start of a drag-selection, and handing focus back to the composer in the same
* moment moves the document selection into the textarea and cancels the drag. */
pressedInReadableText: boolean
/** The element that lost focus is this node's xterm while its ⌘M view is open: the only way that
* happens is `useMdModeFocus` blurring it as the view opens (every other "take the keyboard"
* path goes through `focusXtermUnlessCovered`, which never focuses a covered xterm). */
lostIsCoveredXterm: boolean
}
/** What a `focusout` inside the node means (both modes since sloppy focus). */
export type FocusLossOutcome =
/** Nothing changed that the node must act on. */
| 'keep'
/** The user clicked this node's own chrome: hand the keyboard straight back to its terminal. */
| 'reclaim'
/** The user pressed text they may be selecting: hand the keyboard back only when the press
* ends WITHOUT a selection (a plain click), so a drag-selection survives to be copied. */
| 'reclaim-on-release'
/** The keyboard really went somewhere else: release the node. */
| 'release'
/**
* What did a `focusout` inside this node mean? (Born for click to focus; both modes use it now.)
*
* The one place the node's "I hold the keyboard" state is released in that mode, so it must tell
* a real move from its look-alikes:
*
* - **Focus stayed inside the node** (the header's rename field, a header button, the ⌘M view's
* composer, the 💬 comments flyout beside the root). The user is still working HERE → `keep`.
* - **The window lost focus** (Cmd+Tab, a click on another app). Chromium fires `blur`/`focusout`
* on the focused element, but that element remains `document.activeElement` and is focused
* again on return — the terminal never stopped owning the keyboard → `keep`.
* - **The node's own ⌘M view opening** (`lostIsCoveredXterm`). `useMdModeFocus` blurs the xterm and
* focuses nothing, so this focusout has no destination and no press — the same shape as a click
* on the empty canvas — yet the user is still looking at this node → `keep`. If they then click
* elsewhere, focus is already on `<body>` and `outsidePressReleases` ends it.
* - **A press on this node's own chrome** (dragging it by the header, clicking its border). The
* browser moves focus to the React Flow wrapper (it is focusable) or to `<body>`, and either
* way the keystroke after it would land on the canvas — where a bare Backspace is
* `canvas.deleteSelection`. #757 asks that the terminal keep the keyboard until the user clicks a
* DIFFERENT card, so this hands it back → `reclaim`.
* - **A press on text the user may select** (`pressedInReadableText`, the ⌘M chat's messages). The
* same press as above, but reclaiming NOW moves the selection into the composer and kills the
* drag — nothing could be highlighted or copied. So the reclaim waits for the press to end, and
* only happens if it ended without a selection → `reclaim-on-release` (see `reclaimOnRelease`).
*
* Everything else — focus on another node's xterm or a text field, or on `<body>` because a click
* landed on the empty canvas — is the user clicking elsewhere, which is exactly what #757 wants to
* be the ONLY way to leave → `release`. A node that is gone answers `keep` rather than guessing.
*/
export function focusLossOutcome(e: FocusLossEvent): FocusLossOutcome {
if (!e.nodeRoot) return 'keep'
if (!e.windowFocused) return 'keep'
if (e.lostIsCoveredXterm) return 'keep'
if (e.activeElement === e.lost) return 'keep'
if (e.gained && e.nodeRoot.contains(e.gained)) return 'keep'
// Focus went to a field this node renders beside its root (the comments composer). The wrapper
// ITSELF is excluded: that is where a header/border press sends focus, and it must still reclaim.
// Without this the press read as "own chrome" and `reclaim` put the keyboard back in the xterm
// a tick later — the composer's caret blinked once and nothing could be typed.
if (e.gained && e.nodeChrome && e.gained !== e.nodeChrome && e.nodeChrome.contains(e.gained)) return 'keep'
if (e.pressedInOwnNode) return e.pressedInReadableText ? 'reclaim-on-release' : 'reclaim'
return 'release'
}
export interface OutsidePress {
/** This node is the agent-status `activeId` (the one whose finishes are "being watched"). */
isActive: boolean
/** The press landed on this node (its React Flow wrapper, header included). */
pressInsideNode: boolean
/** `document.activeElement` is inside this node's root at the time of the press. */
focusInsideNode: boolean
}
/**
* Does a press ANYWHERE ELSE release a node that holds no DOM focus? (Both modes.)
*
* `focusLossOutcome` can only answer for a node that had focus to lose. Activity is also claimed
* without it: a "go to node" while the ⌘M view covers the xterm (`enterNow` reports activity, but
* `focusXtermUnlessCovered` deliberately leaves the hidden terminal unfocused) and Canvas's own
* `setActive` on a sidebar or notification jump. Strict focus-follows-pointer had `mouseleave`
* clean that up; with click to focus, and now sloppy focus, nothing else does, and a stale active
* flag makes Canvas treat the node as watched — its next finish never gets an unread dot — and
* leaves presence saying "working here".
*
* So a press outside such a node is the user clicking elsewhere, which is the release #757 names.
* A node that DOES hold focus is left to its own `focusout` (the press may not move focus at all —
* a pane drag, a scroll — and then it rightly keeps the keyboard).
*/
export function outsidePressReleases(p: OutsidePress): boolean {
return p.isActive && !p.pressInsideNode && !p.focusInsideNode
}
/**
* `reclaim`: which element gets the keyboard back after a press on the node's own
* chrome? The one that lost it, when it is still inside the node and is not the xterm (the ⌘M
* composer — the covered xterm cannot take focus, so falling back to it strands the keyboard on the
* React Flow wrapper); otherwise the xterm, through `focusXtermUnlessCovered`.
*/
export function reclaimTarget(p: { lostIsXterm: boolean; lostStillInNode: boolean }): 'lost' | 'xterm' {
return !p.lostIsXterm && p.lostStillInNode ? 'lost' : 'xterm'
}
/**
* Does this press ACKNOWLEDGE the node (the `enterNow` routine — active flag, `clearUnread`,
* presence, remember, and the xterm focused unless the ⌘M view covers it)?
*
* Focus-follows-pointer acknowledges on every dwell, and a body press there is a dwell's worth of
* intent anyway (the guard is already down). Click to focus has no dwell, so a deliberate
* primary press anywhere in the node BODY is the acknowledgement: on the xterm even when the guard is
* already down (Codex round 3 — a finish that turned unread while the window was inactive could not
* be cleared by clicking the terminal it belongs to), on the open ⌘M view, on its composer. Three
* exclusions: the guard itself, because a press there may start a node drag and `HoverGuard` owns
* that decision on release; the header chrome; and non-primary buttons (the context menu). A focus
* restore with no press (window activation) is never an acknowledgement — only presses reach this.
*/
export function bodyPressAcknowledges(p: { primary: boolean; inBody: boolean; onGuard: boolean }): boolean {
return p.primary && p.inBody && !p.onGuard
}
/**
* `reclaim-on-release`, decided when the press ends: give the keyboard back to the element that
* lost it only for a plain click (nothing selected) and only if that element is still in the node.
* A press that selected text keeps the selection — and the keyboard off the composer, so Cmd/Ctrl+C
* copies it; clicking the composer (or anywhere) afterwards behaves as usual.
*/
export function reclaimOnRelease(p: { selectionEmpty: boolean; lostStillInNode: boolean }): boolean {
return p.selectionEmpty && p.lostStillInNode
}