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: bind the focus restore to the canvas on screen, and leave its guard armed

Bas Milius72157c6d0665
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 328b47b38..fa40d3108 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -7282,12 +7282,20 @@ export function Canvas() {
const onWindowFocus = () => {
if (timer) clearTimeout(timer)
timer = setTimeout(() => {
+ // Only the nodes we can prove belong to the canvas on screen: `nodesRef` and
+ // `activeProjectId` do not turn over in one commit, and an id we cannot place must not
+ // become a request that waits for its project to come back.
+ const activeProjectId = useProjects.getState().activeProjectId
+ const liveIds = new Set(
+ nodesProjectIdRef.current === activeProjectId ? nodesRef.current.map((n) => n.id) : []
+ )
const target = nodeToRefocus({
lastNodeId: useTerminalFocus.getState().lastNodeId,
activeElement: document.activeElement as unknown as ContextElement | null,
openDialogs: openDialogCount(),
- boardOpen: isKanbanOpen(useProjects.getState().activeProjectId),
- settingsOpen: settingsOpenRef.current
+ boardOpen: isKanbanOpen(activeProjectId),
+ settingsOpen: settingsOpenRef.current,
+ liveIds
})
if (target) {
useTerminalFocus.getState().request(target, { ack: false })
diff --git a/src/renderer/lib/focusRestore.test.ts b/src/renderer/lib/focusRestore.test.ts
index 258ab9d6b..f8083b656 100644
--- a/src/renderer/lib/focusRestore.test.ts
+++ b/src/renderer/lib/focusRestore.test.ts
@@ -14,6 +14,7 @@ const state = (over: Partial<FocusRestoreState> = {}): FocusRestoreState => ({
openDialogs: 0,
boardOpen: false,
settingsOpen: false,
+ liveIds: new Set(['term-1']),
...over
})
@@ -60,4 +61,22 @@ describe('nodeToRefocus', () => {
it('restores when nothing at all is focused', () => {
expect(nodeToRefocus(state({ activeElement: null }))).toBe('term-1')
})
+
+ it('refuses a remembered node that belongs to another project', () => {
+ // `lastNodeId` survives a project switch on purpose, and a request for an unmounted node is
+ // not dropped: it stays latent and fires when that node next mounts. Leaving project A with a
+ // terminal focused, switching to B and Cmd+Tabbing back would otherwise park a request that
+ // takes the keyboard on the next switch back to A, minutes after the activation.
+ expect(nodeToRefocus(state({ liveIds: new Set(['other-1', 'other-2']) }))).toBeNull()
+ })
+
+ it('refuses when the live nodes cannot be resolved at all', () => {
+ // Empty means "we do not know which project's nodes we are holding", not "the canvas is
+ // empty": the node array and the active project id do not turn over in one commit.
+ expect(nodeToRefocus(state({ liveIds: new Set() }))).toBeNull()
+ })
+
+ it('restores a node that is on the canvas alongside others', () => {
+ expect(nodeToRefocus(state({ liveIds: new Set(['other-1', 'term-1']) }))).toBe('term-1')
+ })
})
diff --git a/src/renderer/lib/focusRestore.ts b/src/renderer/lib/focusRestore.ts
index 10b44ae93..faaa1fca0 100644
--- a/src/renderer/lib/focusRestore.ts
+++ b/src/renderer/lib/focusRestore.ts
@@ -30,6 +30,13 @@ export interface FocusRestoreState {
boardOpen: boolean
/** The settings page is up. Also outside the dialog stack, for the same reason as `boardOpen`. */
settingsOpen: boolean
+ /**
+ * The nodes of the project currently on screen, by id.
+ *
+ * Empty means "we cannot tell which project's nodes we are holding", which refuses rather than
+ * guesses: `nodesRef` is only trustworthy while its epoch tag still matches the active project.
+ */
+ liveIds: ReadonlySet<string>
}
/**
@@ -49,12 +56,21 @@ export interface FocusRestoreState {
* user having left the app from a text field; it is not ours to override.
* - **A terminal already has focus**: the pointer never left, so nothing was lost. Restoring
* would be a no-op at best and could move focus to a DIFFERENT node at worst.
+ * - **The remembered node is not on the canvas we are looking at**: `lastNodeId` deliberately
+ * survives a project switch, and a request for an unmounted node is not dropped, it stays
+ * LATENT until that node mounts (`TerminalNode`'s `lastFocusReqRef` starts at 0, and only the
+ * consumer clears the store). So restoring a node that belongs to another project queues a
+ * focus that fires minutes later, the next time the user switches back to it. Refusing here is
+ * what keeps the restore bound to the canvas the activation actually returned to.
*/
export function nodeToRefocus(state: FocusRestoreState): string | null {
- const { lastNodeId, activeElement, openDialogs, boardOpen, settingsOpen } = state
+ const { lastNodeId, activeElement, openDialogs, boardOpen, settingsOpen, liveIds } = state
if (!lastNodeId || openDialogs > 0) {
return null
}
+ if (!liveIds.has(lastNodeId)) {
+ return null
+ }
if (boardOpen || settingsOpen) {
return null
}
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index fc5626d99..a975879f3 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -4334,21 +4334,29 @@ export function TerminalNode({
// ---- hover guard: dwell before entering the terminal ----
/**
- * Take the keyboard: leave the guard, focus xterm, and report the node active.
+ * Take the keyboard: focus xterm, leave the guard, and report the node active.
*
* Split out of `onBodyEnter` so a deliberate CLICK can run it with no delay — see `onGuardUp`.
*
- * `ack` (default true) also marks the node's finish read. Every gesture that reaches here aims
- * at THIS node — a dwell, a click, a sidebar or notification jump — so the read is real. The one
- * caller that passes false is the window-activation restore, which nobody aimed at anything.
+ * `ack` (default true) says a human AIMED at this node, and two things follow from it. It marks
+ * the node's finish read, which reaches past this machine (`clearUnread` → `ackDone` → the notch
+ * capsule and the paired phone). And it drops the hover guard, which is a POINTER contract: the
+ * guard makes a quick scroll pan the canvas until the dwell has elapsed, so a restore nobody
+ * pointed at must leave it armed, or the next pointer entry silently skips its dwell and the
+ * first wheel scrolls tmux instead. Keyboard focus does not need the guard down: it is an
+ * overlay, and a programmatic `focus()` is not hit-tested.
+ *
+ * Every gesture that reaches here aims at THIS node: a dwell, a click, a sidebar or notification
+ * jump. The one caller that passes false is the window-activation restore.
*/
const enterNow = (opts?: { ack?: boolean }) => {
+ const aimed = opts?.ack !== false
if (dwellRef.current) clearTimeout(dwellRef.current)
- setArmed(false)
+ if (aimed) setArmed(false)
termRef.current?.focus()
useTerminalFocus.getState().remember(id)
useAgentStatus.getState().setActive(id, true)
- if (opts?.ack !== false) {
+ if (aimed) {
useAgentStatus.getState().clearUnread(id)
}
presence.reportFocus(id)
diff --git a/src/renderer/state/terminalFocus.ts b/src/renderer/state/terminalFocus.ts
index e667478a1..560bff320 100644
--- a/src/renderer/state/terminalFocus.ts
+++ b/src/renderer/state/terminalFocus.ts
@@ -35,11 +35,17 @@ export const useTerminalFocus = create<{
* that is gone or unmounted simply misses the request, the same fail-open as `request`.
*
* It therefore also survives a PROJECT SWITCH, so the remembered node can belong to another
- * project. That fails open today because the request is consumed by a mounted `TerminalNode`
- * and the node of an inactive project is unmounted. Load-bearing: a change that starts routing
- * a focus request across projects (switching to the node's project first, as `focusNodeById`
- * does) has to clear or qualify this, or a window activation would yank the user out of the
- * project they are looking at.
+ * project. That does NOT fail open: a request for an unmounted node stays LATENT rather than
+ * being dropped. `nodeId` is cleared only by the consumer, and `TerminalNode`'s `lastFocusReqRef`
+ * starts at 0, so the node consumes the request the moment it mounts. The cross-project
+ * `pendingFocusRef` path in `Canvas` relies on exactly that, requesting right after a project
+ * loads and before the node exists.
+ *
+ * So the restore, not this field, is where the staleness is refused: `nodeToRefocus` takes the
+ * live nodes of the project on screen and returns null for an id that is not among them. Without
+ * it, leaving project A with a terminal focused, switching to B and Cmd+Tabbing back would park a
+ * request that fires on the next switch to A, handing a node the keyboard minutes after the
+ * activation nobody aimed at it.
*/
lastNodeId: string | null
/**