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
import { describe, expect, it } from 'vitest'
import { readFileSync } from 'fs'
import { join } from 'path'
import { DEFAULT_SETTINGS } from '@shared/types'
import {
focusLossOutcome,
reclaimOnRelease,
bodyPressAcknowledges,
outsidePressReleases,
reclaimTarget,
hoverTakesKeyboard,
pointerLeaveRearmsGuard,
focusDrivesGuard,
dwellBlursForeignTerminal,
resolveFocusFollowsPointer
} from './terminalFocusMode'
/**
* Issue #757 — "option to disable X Window focus-follows-pointer (Mac-style click to select what
* UI element has the input focus)". A terminal node's keyboard used to follow the POINTER: a hover
* dwell took it, leaving the node took it away. `settings.terminalFocusFollowsPointer` keeps the
* hover dwell (the default) or switches to click-to-focus, where the pointer decides nothing and the
* clicked terminal keeps the keyboard until the user clicks somewhere else.
*
* Since then the default became SLOPPY focus: the dwell still takes the keyboard, but leaving the
* node no longer takes it away — it stays until another node takes it (a dwell, a click) or the
* user clicks elsewhere. Typing into a terminal while the mouse rests on the canvas no longer
* silently stops working.
*/
describe('terminal focus mode (#757)', () => {
it('defaults to focus-follows-pointer, so nobody’s terminal changes behaviour on upgrade', () => {
expect(DEFAULT_SETTINGS.terminalFocusFollowsPointer).toBe(true)
})
describe('resolveFocusFollowsPointer', () => {
it('switches to click to focus only on a literal false', () => {
expect(resolveFocusFollowsPointer(false)).toBe(false)
expect(resolveFocusFollowsPointer(true)).toBe(true)
// settings.json is hand-editable: a mangled value keeps the default, never flips the mode.
expect(resolveFocusFollowsPointer(undefined)).toBe(true)
expect(resolveFocusFollowsPointer('false')).toBe(true)
expect(resolveFocusFollowsPointer(null)).toBe(true)
})
})
describe('hoverTakesKeyboard', () => {
it('lets a hover dwell take the keyboard only while focus follows the pointer', () => {
expect(hoverTakesKeyboard(true)).toBe(true)
expect(hoverTakesKeyboard(false)).toBe(false)
})
})
describe('pointerLeaveRearmsGuard', () => {
it('re-arms the guard on mouseleave only while focus follows the pointer', () => {
// The guard is a POINTER contract in that mode: a pass-over scroll pans the canvas until the
// next dwell, so leaving must put it back.
expect(pointerLeaveRearmsGuard(true)).toBe(true)
// Click to focus: the guard follows DOM focus, and the pointer wandering off changes nothing.
expect(pointerLeaveRearmsGuard(false)).toBe(false)
})
})
describe('focusDrivesGuard', () => {
it('lets focus changes arm and disarm the guard only in click to focus', () => {
expect(focusDrivesGuard(false)).toBe(true)
// Focus follows the pointer: the dwell, a click and mouseleave own the guard. A release that
// re-armed it would strand a pointer resting on the body behind an armed guard with no
// mouseenter coming to restart the dwell; a reclaim that dropped it would let a pass-over
// scroll reach tmux.
expect(focusDrivesGuard(true)).toBe(false)
})
})
describe('dwellBlursForeignTerminal', () => {
// Sloppy focus: the pointer leaving a terminal no longer takes its keyboard, so the dwell onto
// the NEXT node is what moves it. A node whose ⌘M view covers its xterm cannot take it, and
// without this the terminal the user came from would keep receiving keystrokes while another
// node reads as the active one.
it('takes the keyboard off another terminal when this node cannot take it itself', () => {
expect(dwellBlursForeignTerminal({ covered: true, activeIsForeignXterm: true })).toBe(true)
})
it('leaves it to focus() when the xterm is not covered (focusing it moves the keyboard anyway)', () => {
expect(dwellBlursForeignTerminal({ covered: false, activeIsForeignXterm: true })).toBe(false)
})
it('never blurs anything but another terminal (a sticky, an editor, a field keep their caret)', () => {
expect(dwellBlursForeignTerminal({ covered: true, activeIsForeignXterm: false })).toBe(false)
})
})
describe('focusLossOutcome', () => {
// Plain objects stand in for DOM nodes: all the helper asks of `nodeRoot` is `contains`.
const lost = { id: 'xterm-textarea' }
const header = { id: 'rename-input' }
const elsewhere = { id: 'other-node-textarea' }
const ownWrapper = { id: 'react-flow-node-wrapper' }
const body = { id: 'body' }
const nodeRoot = { contains: (n: unknown) => n === lost || n === header }
const ev = (over: Partial<Parameters<typeof focusLossOutcome>[0]>) =>
focusLossOutcome({
nodeRoot,
nodeChrome: null,
lost,
gained: null,
activeElement: body,
windowFocused: true,
pressedInOwnNode: false,
pressedInReadableText: false,
lostIsCoveredXterm: false,
...over
})
it('keeps when focus moved into a field beside the root but inside the node (comments flyout)', () => {
const composer = { id: 'comments-composer' }
// The wrapper is the chrome: a header press focuses the very element passed as nodeChrome.
const nodeChrome: { id: string; contains: (n: unknown) => boolean } = {
id: 'react-flow-node-wrapper',
contains: (n) => n === nodeChrome || n === composer || nodeRoot.contains(n)
}
// The press landed in the node's wrapper, which used to read as "own chrome" → reclaim → the
// xterm took the keyboard back and the composer could never be typed into.
expect(ev({ nodeChrome, gained: composer, activeElement: composer, pressedInOwnNode: true })).toBe('keep')
// A press on the header/border still sends focus to the wrapper itself, and that still reclaims.
expect(ev({ nodeChrome, gained: nodeChrome, activeElement: nodeChrome, pressedInOwnNode: true })).toBe('reclaim')
// Another card is still elsewhere.
expect(ev({ nodeChrome, gained: elsewhere, activeElement: elsewhere })).toBe('release')
})
it('releases when focus moved to something outside the node (another card, a field)', () => {
expect(ev({ gained: elsewhere, activeElement: elsewhere })).toBe('release')
})
it('releases when a click sent focus nowhere (the empty canvas blurs the xterm, #86)', () => {
expect(ev({ gained: null, activeElement: body })).toBe('release')
})
it('keeps it when focus only moved inside the same node (header field, ⌘M composer)', () => {
expect(ev({ gained: header, activeElement: header })).toBe('keep')
// …even when the press that moved it was on this node.
expect(ev({ gained: header, activeElement: header, pressedInOwnNode: true })).toBe('keep')
})
it('reclaims the keyboard when the user pressed this node’s own chrome (header drag)', () => {
// The wrapper is focusable in React Flow, so a header press moves focus to it — outside
// `.term-node`, where the next Backspace would be the canvas's delete-selection.
expect(ev({ gained: ownWrapper, activeElement: ownWrapper, pressedInOwnNode: true })).toBe('reclaim')
// A non-focusable wrapper sends focus to <body> instead; same press, same answer.
expect(ev({ gained: null, activeElement: body, pressedInOwnNode: true })).toBe('reclaim')
})
it('defers the reclaim to the end of the press when it landed on readable text (⌘M chat selection)', () => {
// Reclaiming now would move the selection into the composer and cancel the drag.
expect(ev({ gained: null, activeElement: body, pressedInOwnNode: true, pressedInReadableText: true })).toBe(
'reclaim-on-release'
)
// The flag alone (no press on this node in this task) changes nothing.
expect(ev({ gained: null, activeElement: body, pressedInReadableText: true })).toBe('release')
// Focus moving to another element inside the node still wins.
expect(ev({ gained: header, activeElement: header, pressedInOwnNode: true, pressedInReadableText: true })).toBe('keep')
})
it('keeps it when the WINDOW lost focus (Cmd+Tab away): the terminal still owns the keyboard', () => {
// Chromium fires blur/focusout on the focused element when the window deactivates, but the
// element stays `document.activeElement` and gets focus back on return. Releasing here would
// drop the node's active flag on every app switch.
expect(ev({ activeElement: lost, windowFocused: false })).toBe('keep')
expect(ev({ activeElement: lost, windowFocused: true })).toBe('keep')
expect(ev({ activeElement: body, windowFocused: false })).toBe('keep')
})
it('keeps it when the xterm is blurred by opening the node\'s own ⌘M view', () => {
// useMdModeFocus blurs the xterm on entry and focuses nothing, so the focusout has no
// destination and no press — exactly the shape of a click on the empty canvas. It is an
// internal view change on the node the user is looking at, not leaving it.
expect(ev({ gained: null, activeElement: body, lostIsCoveredXterm: true })).toBe('keep')
})
it('answers keep without a node root (unmounted mid-event) rather than guessing', () => {
expect(ev({ nodeRoot: null })).toBe('keep')
})
})
describe('outsidePressReleases', () => {
// Activity can be claimed without this node ever holding DOM focus: "go to node" while the ⌘M
// view covers the xterm (`focusXtermUnlessCovered` deliberately does not focus it), and Canvas's
// own `setActive` on a sidebar / notification jump. No `focusout` can come from a node that has
// no focus, and with click to focus `mouseleave` no longer releases either — so a stale active
// flag suppressed the unread dot for that node until something else became active.
it('releases a node that claims activity but holds no focus when the user presses elsewhere', () => {
expect(outsidePressReleases({ isActive: true, pressInsideNode: false, focusInsideNode: false })).toBe(true)
})
it('leaves a node alone whose focus will report its own loss (the focusout path owns that)', () => {
expect(outsidePressReleases({ isActive: true, pressInsideNode: false, focusInsideNode: true })).toBe(false)
})
it('never releases on a press inside the node itself', () => {
expect(outsidePressReleases({ isActive: true, pressInsideNode: true, focusInsideNode: false })).toBe(false)
})
it('has nothing to release when the node is not the active one', () => {
expect(outsidePressReleases({ isActive: false, pressInsideNode: false, focusInsideNode: false })).toBe(false)
})
})
describe('reclaimTarget', () => {
// MEASURED in Electron 42 (Blink): a press on the node's own header moves focus from whatever
// held it to the React Flow wrapper (tabindex 0). When the ⌘M view is open, what held it was the
// composer, and the covered xterm cannot take focus back — so reclaiming only to the xterm left
// the keyboard on the wrapper, where Backspace is the canvas's delete-selection.
it('hands focus back to the element inside the node that lost it (the ⌘M composer)', () => {
expect(reclaimTarget({ lostIsXterm: false, lostStillInNode: true })).toBe('lost')
})
it('uses the xterm when the xterm lost it, or when the lost element is gone (rename field closed)', () => {
expect(reclaimTarget({ lostIsXterm: true, lostStillInNode: true })).toBe('xterm')
expect(reclaimTarget({ lostIsXterm: false, lostStillInNode: false })).toBe('xterm')
})
})
describe('bodyPressAcknowledges', () => {
// Click to focus has no dwell, so a deliberate press is the acknowledgement (active,
// clearUnread, presence) — on the xterm with the guard already down (a finish that turned unread
// while the window was inactive), on the ⌘M view, on its composer. Only a press can: a focus
// restore on window activation is not the user aiming at the node.
it('acknowledges any primary press inside the node body', () => {
expect(bodyPressAcknowledges({ primary: true, inBody: true, onGuard: false })).toBe(true)
})
it('leaves the guard to HoverGuard, since a press there may be the start of a node drag', () => {
expect(bodyPressAcknowledges({ primary: true, inBody: true, onGuard: true })).toBe(false)
})
it('ignores the header chrome and non-primary buttons', () => {
expect(bodyPressAcknowledges({ primary: true, inBody: false, onGuard: false })).toBe(false)
expect(bodyPressAcknowledges({ primary: false, inBody: true, onGuard: false })).toBe(false)
})
})
// The decisions above are only worth something if the node and the settings page use them. A
// source check, like `focusRestore.test.ts`: TerminalNode cannot be mounted without an xterm.
describe('wiring', () => {
const read = (rel: string) => readFileSync(join(process.cwd(), rel), 'utf8')
it('TerminalNode reads the setting live and routes hover, leave and focus loss through it', () => {
const src = read('src/renderer/nodes/TerminalNode.tsx')
expect(src).toContain('useSettings((s) => s.settings.terminalFocusFollowsPointer)')
expect(src).toContain('hoverTakesKeyboard(focusFollowsPointer)')
expect(src).toContain('pointerLeaveRearmsGuard(focusFollowsPointer)')
// Sloppy focus: DOM focus owns the keyboard in BOTH modes, so the hook always runs and only
// the guard is mode-dependent.
expect(src).toContain('useClickToFocus({')
expect(src).toContain('if (focusDrivesGuard(focusFollowsPointer)) setArmed(armed)')
expect(src).toContain('dwellBlursForeignTerminal({')
// The pointer leaving never takes the keyboard away: no blur, no release, in either mode.
const leave = src.slice(src.indexOf('const onBodyLeave = () => {'), src.indexOf('useClickToFocus({'))
expect(leave).not.toContain('blur()')
expect(leave).not.toContain('setActive(id, false)')
expect(leave).not.toContain('releaseFocus(')
// A dwell already running when the setting is switched off must not still take the keyboard:
// the timer re-reads the LIVE setting, and switching off cancels a pending dwell.
expect(src).toContain('if (!hoverTakesKeyboard(focusFollowsPointerRef.current)) return')
expect(src).toMatch(/if \(focusFollowsPointer\) return\s*\n\s*if \(dwellRef\.current\) clearTimeout\(dwellRef\.current\)/)
// Focus mode keeps the keyboard across its reparent in BOTH modes, and tells the hook.
expect(src.match(/reparentKeepingFocus\(/g)?.length).toBe(2)
expect(src).toContain('reparenting: () => reparentingRef.current')
const hook = read('src/renderer/nodes/useClickToFocus.ts')
for (const call of ['focusLossOutcome(', 'outsidePressReleases(', 'bodyPressAcknowledges(', 'reclaimTarget(']) {
expect(hook).toContain(call)
}
expect(hook).toContain('lostIsCoveredXterm:')
})
it('Settings → Behavior offers the toggle, findable by search', () => {
const src = read('src/renderer/components/settings/sections/BehaviorSection.tsx')
expect(src).toContain('update({ terminalFocusFollowsPointer: v })')
for (const k of ['focus', 'hover', 'pointer', 'click', 'follows', 'x11']) {
expect(src).toMatch(new RegExp(`focusFollowsPointer: \\{[^}]*'${k}'`))
}
})
})
describe('reclaimOnRelease', () => {
it('gives the keyboard back only for a plain click, and only to an element still in the node', () => {
expect(reclaimOnRelease({ selectionEmpty: true, lostStillInNode: true })).toBe(true)
expect(reclaimOnRelease({ selectionEmpty: false, lostStillInNode: true })).toBe(false)
expect(reclaimOnRelease({ selectionEmpty: true, lostStillInNode: false })).toBe(false)
})
})
})