Skip to content

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.

feat(focus-mode): ⌘←/→/↑/↓ swap the focused node instead of leaving focus mode

eneskirca97ac3b634849
diff --git a/CLAUDE.md b/CLAUDE.md
index e09bd3d29..39fa191d4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8338,6 +8338,23 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
what a column layout discards); mobile N/A - *nodeterm mobile* attaches to tmux sessions over
the transport protocol and has no canvas, so surfacing a layout means extending that protocol
(follow-up in the iOS repo).
+- **Directional focus (⌘←/→/↑/↓, `node.focus*`)** — the multiplexer gesture (Ghostty `goto_split`,
+ tmux `select-pane -L`) on a canvas with no split tree: `lib/directionalFocus.ts` ranks candidates
+ by geometry (same-row/column overlap first, then diagonal with a sideways penalty; no wrap). The
+ ONE decision — where to land AND how — is the pure `planDirectionalMove`, and the "how" has two
+ answers that must not be merged: on the canvas the move **travels** (`focusNodeById`: frame +
+ keyboard + read-ack), origin = the node the keyboard is in, else the selection, else the first
+ press ADOPTS the node nearest the view center. In **focus mode** (⌘⇧F, issue #78) the move
+ **swaps the focused node** (`useFocusNode.focus(next)`) — the flow pane is `display:none` there,
+ so a travel would frame a node on a 0-sized pane (the origin-jump bug) while the user kept
+ staring at the old terminal; before this, moving between two focused terminals was ⌘⇧F, ⌘→, ⌘⇧F.
+ Three details carry it: the origin is the FOCUSED id (the reparent detaches the node root from
+ its `.react-flow__node` wrapper, so the keyboard origin reads null there); candidates are
+ TERMINALS only (the one kind focus mode can show — `focusTargetId`); and the keyboard is handed
+ over explicitly (`useTerminalFocus.request`), because the reparent gives focus back to whichever
+ xterm had it, i.e. the OLD node. Selection follows the swap so leaving focus mode lands on the
+ node the user was in. An edge with nowhere to go is a CLAIMED no-op in both modes — declining
+ would hand ⌘→ to the terminal, which is not "nothing".
- **Command palette** (`CommandPalette.tsx`): ⌘/Ctrl+K; `Canvas.buildCommands` (create,
switch project, jump to node by title/tag, open file…).
- **Explorer** (`ExplorerPanel.tsx`, 🗂 / ⌘⇧E): lazy file tree of the active project `cwd`
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 7fdd15d28..7e873701b 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -264,8 +264,7 @@ import { installLockedMiddleGuard, installModifierPan } from '../lib/modifierPan
import {
FLOW_NODE_CLASS,
isFocusTarget,
- nextNodeInDirection,
- nodeNearestPoint,
+ planDirectionalMove,
type FocusDirection
} from '../lib/directionalFocus'
import { UpdateCard } from '../components/UpdateCard'
@@ -10587,29 +10586,41 @@ export function Canvas() {
const moveNodeFocus = useCallback(
(dir: FocusDirection): boolean => {
const nodes = nodesRef.current
- const from =
- document.activeElement?.closest(`.${FLOW_NODE_CLASS}`)?.getAttribute('data-id') ??
- nodes.find((n) => n.selected && isFocusTarget(n))?.id ??
- null
- // Nothing focused, nothing selected: the first press ADOPTS the node nearest the view center
- // instead of moving from it. Walking from an origin the user never chose lands somewhere
- // arbitrary; adopting is the "you are here" a multiplexer's first move gives you for free.
- if (!from) {
- const center = viewCenter()
- const seed = center ? nodeNearestPoint(nodes, center) : null
- if (!seed) return false
- focusNodeRef.current(seed)
- return true
- }
- const next = nextNodeInDirection(nodes, from, dir)
- if (next) focusNodeRef.current(next)
+ // Which node to land on, and HOW, is the pure `planDirectionalMove`: on the canvas the move
+ // travels (from the keyboard's node, else the selection, else — first press — the node
+ // nearest the view center is ADOPTED rather than moved from); in focus mode it SWAPS the
+ // focused node for its neighbour, because the flow pane is display:none there and a travel
+ // would frame a node on a hidden, 0-sized pane (the origin-jump bug) while the user stays
+ // staring at the old terminal. Before this, moving between two focused terminals took
+ // ⌘⇧F, ⌘→, ⌘⇧F.
+ const move = planDirectionalMove(nodes, dir, {
+ focusedId: useFocusNode.getState().focusedId,
+ keyboardId: document.activeElement?.closest(`.${FLOW_NODE_CLASS}`)?.getAttribute('data-id') ?? null,
+ selectedId: nodes.find((n) => n.selected && isFocusTarget(n))?.id ?? null,
+ viewCenter: viewCenter() ?? null
+ })
// Claimed even at the edge of the canvas, where there is nothing to move to. Declining
// would offer ⌘→ back to the focused terminal instead, and whatever it does there it is
// not "nothing" — a navigation key with nowhere to go should do nothing, not something
- // else.
+ // else. The one unclaimed case is a canvas with no node to seed from.
+ if (!move) return !!useFocusNode.getState().focusedId || nodes.some(isFocusTarget)
+ if (move.kind === 'travel') {
+ focusNodeRef.current(move.id)
+ return true
+ }
+ // Swap inside focus mode: the store change reparents the new node into the focus surface
+ // (TerminalNode's layout effect) and sends the old one home. The keyboard does NOT follow on
+ // its own — the reparent hands focus back to whichever xterm had it, i.e. the old node —
+ // so it is requested explicitly, the way every "go to node" path does. Selection follows
+ // too, so leaving focus mode later lands the camera on the node the user was in.
+ useFocusNode.getState().focus(move.id)
+ setNodes((ns) => ns.map((n) => ({ ...n, selected: n.id === move.id })))
+ useTerminalFocus.getState().request(move.id)
+ useAgentStatus.getState().setActive(move.id, true)
+ useAgentStatus.getState().clearUnread(move.id)
return true
},
- [viewCenter]
+ [viewCenter, setNodes]
)
/**
diff --git a/src/renderer/lib/directionalFocus.test.ts b/src/renderer/lib/directionalFocus.test.ts
index 002b9d8ac..0707196dc 100644
--- a/src/renderer/lib/directionalFocus.test.ts
+++ b/src/renderer/lib/directionalFocus.test.ts
@@ -5,6 +5,7 @@ import {
isFocusTarget,
nextNodeInDirection,
nodeNearestPoint,
+ planDirectionalMove,
type DirectionalNode
} from './directionalFocus'
@@ -222,3 +223,61 @@ describe('FLOW_NODE_CLASS', () => {
expect(dist.includes(FLOW_NODE_CLASS)).toBe(true)
})
})
+
+/**
+ * The same chord, two very different moves. On the canvas ⌘→ TRAVELS: the camera frames the
+ * neighbour. In focus mode (one terminal fills the window) there is no camera to move — the flow
+ * pane is display:none — so ⌘→ SWAPS the focused node for its neighbour and the user never leaves
+ * focus mode. Before this the only way between two focused terminals was ⌘⇧F, ⌘→, ⌘⇧F.
+ */
+describe('planDirectionalMove', () => {
+ const terminals = [
+ node('a', 0, 0, { type: 'terminal' }),
+ node('b', 300, 0, { type: 'terminal' }),
+ node('note', 600, 0, { type: 'sticky' }),
+ node('c', 900, 0, { type: 'terminal' })
+ ]
+ const ctx = { focusedId: null, keyboardId: null, selectedId: null, viewCenter: null }
+
+ it('in focus mode, swaps focus to the neighbouring TERMINAL, skipping what focus mode cannot show', () => {
+ expect(planDirectionalMove(terminals, 'right', { ...ctx, focusedId: 'b' })).toEqual({
+ kind: 'swap-focus',
+ id: 'c'
+ })
+ expect(planDirectionalMove(terminals, 'left', { ...ctx, focusedId: 'b' })).toEqual({
+ kind: 'swap-focus',
+ id: 'a'
+ })
+ })
+
+ it('in focus mode, the origin is the FOCUSED node, whatever the keyboard or selection say', () => {
+ // The reparent detaches the node root from its xyflow wrapper, so the keyboard origin reads
+ // as null or as a stale node; neither may decide the move.
+ expect(
+ planDirectionalMove(terminals, 'right', { ...ctx, focusedId: 'a', keyboardId: 'c', selectedId: 'c' })
+ ).toEqual({ kind: 'swap-focus', id: 'b' })
+ })
+
+ it('in focus mode, the edge is a claimed no-op: nothing to swap to, and no travel either', () => {
+ expect(planDirectionalMove(terminals, 'right', { ...ctx, focusedId: 'c' })).toBeNull()
+ })
+
+ it('on the canvas, travels from the keyboard node, else the selected one', () => {
+ expect(planDirectionalMove(terminals, 'right', { ...ctx, keyboardId: 'a', selectedId: 'c' })).toEqual({
+ kind: 'travel',
+ id: 'b'
+ })
+ expect(planDirectionalMove(terminals, 'left', { ...ctx, selectedId: 'c' })).toEqual({
+ kind: 'travel',
+ id: 'note'
+ })
+ })
+
+ it('on the canvas with no origin, seeds from the node nearest the view center', () => {
+ expect(planDirectionalMove(terminals, 'right', { ...ctx, viewCenter: { x: 950, y: 50 } })).toEqual({
+ kind: 'travel',
+ id: 'c'
+ })
+ expect(planDirectionalMove(terminals, 'right', ctx)).toBeNull()
+ })
+})
diff --git a/src/renderer/lib/directionalFocus.ts b/src/renderer/lib/directionalFocus.ts
index 5b404f74a..eeb1dba97 100644
--- a/src/renderer/lib/directionalFocus.ts
+++ b/src/renderer/lib/directionalFocus.ts
@@ -176,3 +176,48 @@ const better = (a: Score, b: Score): boolean =>
: a.perp !== b.perp
? a.perp < b.perp
: a.id < b.id
+
+/** What a directional move should do: swap the focus-mode node, or travel the camera. */
+export type DirectionalMove = { kind: 'swap-focus' | 'travel'; id: string }
+
+export interface DirectionalMoveContext {
+ /** Focus mode's node (`useFocusNode.focusedId`), or null on the plain canvas. */
+ focusedId: string | null
+ /** The node the KEYBOARD is in (the `.react-flow__node` ancestor of the active element). */
+ keyboardId: string | null
+ /** The single selected focus target, if any. */
+ selectedId: string | null
+ /** The view center in world coordinates, for seeding a canvas with no origin; null = unknown. */
+ viewCenter: { x: number; y: number } | null
+}
+
+/**
+ * The one decision behind ⌘←/→/↑/↓, in both places the chord can fire:
+ *
+ * - **Focus mode** — one terminal fills the window and the flow pane is display:none, so there is
+ * no camera to move; the move SWAPS the focused node for its neighbour and the user stays in
+ * focus mode (before this, going from one focused terminal to the next was ⌘⇧F, ⌘→, ⌘⇧F). The
+ * origin is the focused node itself — the reparent detaches its root from the xyflow wrapper,
+ * so the keyboard origin reads as null there — and the candidates are TERMINALS only, the one
+ * kind focus mode can show (`focusTargetId`). A null at the edge is still a claimed chord.
+ * - **Canvas** — the origin is the node the keyboard is in, else the selected node, else (first
+ * press) the node nearest the view center is ADOPTED rather than moved from; the move TRAVELS.
+ */
+export function planDirectionalMove(
+ nodes: readonly DirectionalNode[],
+ dir: FocusDirection,
+ ctx: DirectionalMoveContext
+): DirectionalMove | null {
+ if (ctx.focusedId) {
+ const terminals = nodes.filter((n) => n.type === 'terminal')
+ const next = nextNodeInDirection(terminals, ctx.focusedId, dir)
+ return next ? { kind: 'swap-focus', id: next } : null
+ }
+ const from = ctx.keyboardId ?? ctx.selectedId
+ if (!from) {
+ const seed = ctx.viewCenter ? nodeNearestPoint(nodes, ctx.viewCenter) : null
+ return seed ? { kind: 'travel', id: seed } : null
+ }
+ const next = nextNodeInDirection(nodes, from, dir)
+ return next ? { kind: 'travel', id: next } : null
+}