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.

fix(canvas): acknowledge the md view and keep activity across its opening in click-to-focus (#757)

Erik Zwep8dd2c1ffcbc9
diff --git a/CLAUDE.md b/CLAUDE.md
index 8cdaa7d97..89924b930 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1273,7 +1273,10 @@ session.
`shouldReleasePaneFocus`) — releases it and re-arms the guard. Activity claimed WITHOUT focus
(go-to-node under the ⌘M view, Canvas's own `setActive` on a jump) has no focusout, so a
document capture `pointerdown` outside the node releases it (`outsidePressReleases`) — else the
- stale `activeId` suppresses that node's unread dot. The guard listens to POINTER events
+ stale `activeId` suppresses that node's unread dot. The ⌘M view has no guard (`armed && !mdMode`)
+ and no dwell here, so a primary press in the node body while it is open runs `enterNow`
+ (`mdViewPressAcknowledges` — the dwell's ack, xterm left unfocused), and the xterm blur that
+ OPENING the view causes is `keep`, not a release (`lostIsCoveredXterm`). The guard listens to POINTER events
(`nodes/HoverGuard.tsx`): React Flow's d3-drag swallows a left `mousedown`/`mouseup` on a
draggable node before React sees them, so the old mouse-event guard never received a left click
(#87's click-to-focus only ever worked through the dwell). Only a literal `false` in
diff --git a/src/renderer/lib/terminalFocusMode.test.ts b/src/renderer/lib/terminalFocusMode.test.ts
index 5d0a6556c..9cf8bfb94 100644
--- a/src/renderer/lib/terminalFocusMode.test.ts
+++ b/src/renderer/lib/terminalFocusMode.test.ts
@@ -4,6 +4,7 @@ import { join } from 'path'
import { DEFAULT_SETTINGS } from '@shared/types'
import {
focusLossOutcome,
+ mdViewPressAcknowledges,
outsidePressReleases,
reclaimTarget,
hoverTakesKeyboard,
@@ -66,6 +67,7 @@ describe('terminal focus mode (#757)', () => {
activeElement: body,
windowFocused: true,
pressedInOwnNode: false,
+ lostIsCoveredXterm: false,
...over
})
@@ -100,6 +102,13 @@ describe('terminal focus mode (#757)', () => {
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')
})
@@ -143,6 +152,25 @@ describe('terminal focus mode (#757)', () => {
})
})
+ describe('mdViewPressAcknowledges', () => {
+ // With focus-follows-pointer, a dwell over the ⌘M view acknowledges the node (setActive,
+ // clearUnread, presence) without focusing the covered xterm. Click to focus has no dwell and no
+ // guard over that view (the guard renders only when !mdMode), so a click is the replacement.
+ it('acknowledges a primary press on the covered view in click-to-focus mode', () => {
+ expect(mdViewPressAcknowledges({ focusFollowsPointer: false, mdMode: true, primary: true, inBody: true })).toBe(true)
+ })
+
+ it('does nothing where something else already owns it', () => {
+ // the dwell owns it
+ expect(mdViewPressAcknowledges({ focusFollowsPointer: true, mdMode: true, primary: true, inBody: true })).toBe(false)
+ // the guard / xterm own it
+ expect(mdViewPressAcknowledges({ focusFollowsPointer: false, mdMode: false, primary: true, inBody: true })).toBe(false)
+ // a right click opens the menu; the header is chrome, not the view
+ expect(mdViewPressAcknowledges({ focusFollowsPointer: false, mdMode: true, primary: false, inBody: true })).toBe(false)
+ expect(mdViewPressAcknowledges({ focusFollowsPointer: false, mdMode: true, primary: true, inBody: 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', () => {
@@ -155,6 +183,8 @@ describe('terminal focus mode (#757)', () => {
expect(src).toContain('pointerLeaveReleases(focusFollowsPointer)')
expect(src).toContain('focusLossOutcome(')
expect(src).toContain('outsidePressReleases(')
+ expect(src).toContain('mdViewPressAcknowledges(')
+ expect(src).toContain('lostIsCoveredXterm:')
})
it('Settings → Behavior offers the toggle, findable by search', () => {
diff --git a/src/renderer/lib/terminalFocusMode.ts b/src/renderer/lib/terminalFocusMode.ts
index 8d40c960c..bd7e15975 100644
--- a/src/renderer/lib/terminalFocusMode.ts
+++ b/src/renderer/lib/terminalFocusMode.ts
@@ -63,6 +63,10 @@ export interface FocusLossEvent {
/** 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
+ /** 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 in click-to-focus mode. */
@@ -85,6 +89,10 @@ export type FocusLossOutcome =
* - **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
@@ -98,6 +106,7 @@ export type FocusLossOutcome =
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'
if (e.pressedInOwnNode) return 'reclaim'
@@ -140,3 +149,23 @@ export function outsidePressReleases(p: OutsidePress): boolean {
export function reclaimTarget(p: { lostIsXterm: boolean; lostStillInNode: boolean }): 'lost' | 'xterm' {
return !p.lostIsXterm && p.lostStillInNode ? 'lost' : 'xterm'
}
+
+/**
+ * Click to focus: does this press acknowledge the node while its ⌘M (Markdown / chat) view is open?
+ *
+ * With focus-follows-pointer, the hover dwell over that view runs the whole "I am here" routine —
+ * active flag, `clearUnread` (the cross-surface finish ACK), presence, remember — while
+ * `focusXtermUnlessCovered` leaves the hidden xterm unfocused. Click to focus has no dwell, and the
+ * hover guard is not rendered over the view (`armed && !mdMode`), so without this a user could click
+ * into an unread conversation, read it, type in its composer, and it stayed unread. A primary press
+ * inside the node BODY (the view) is the click equivalent; the header is chrome and a right click
+ * opens the menu.
+ */
+export function mdViewPressAcknowledges(p: {
+ focusFollowsPointer: boolean
+ mdMode: boolean
+ primary: boolean
+ inBody: boolean
+}): boolean {
+ return !p.focusFollowsPointer && p.mdMode && p.primary && p.inBody
+}
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index 7a2c44b58..31bc3ae48 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -212,6 +212,7 @@ import { HoverGuard } from './HoverGuard'
import {
focusLossOutcome,
hoverTakesKeyboard,
+ mdViewPressAcknowledges,
outsidePressReleases,
pointerLeaveReleases,
reclaimTarget,
@@ -5310,7 +5311,20 @@ export function TerminalNode({
let pressedInOwnNode = false
let pressTimer: ReturnType<typeof setTimeout> | null = null
let reclaimTimer: ReturnType<typeof setTimeout> | null = null
- const onPointerDown = () => {
+ const onPointerDown = (e: PointerEvent) => {
+ // A click on the open ⌘M view is click-to-focus's stand-in for the dwell over it: it runs
+ // `enterNow`, which acknowledges the node and leaves the covered xterm unfocused
+ // (`focusXtermUnlessCovered`) — exactly what the dwell does there in the default mode.
+ if (
+ mdViewPressAcknowledges({
+ focusFollowsPointer: false,
+ mdMode: mdModeRef.current,
+ primary: e.button === 0,
+ inBody: e.target instanceof Element && !!e.target.closest('.term-node__body') && root.contains(e.target)
+ })
+ ) {
+ enterNow()
+ }
pressedInOwnNode = true
if (pressTimer) clearTimeout(pressTimer)
pressTimer = setTimeout(() => {
@@ -5338,7 +5352,8 @@ export function TerminalNode({
gained: e.relatedTarget,
activeElement: document.activeElement,
windowFocused: document.hasFocus(),
- pressedInOwnNode
+ pressedInOwnNode,
+ lostIsCoveredXterm: mdModeRef.current && e.target === termRef.current?.textarea
})
if (outcome === 'keep') return
if (outcome === 'release') {