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(chat): opening the ⌘M chat view puts the keyboard in its composer (#1163)

Paul Robertson5515bbd43ce7
diff --git a/CLAUDE.md b/CLAUDE.md
index bda953a83..a757ba1c4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1624,7 +1624,10 @@ tmux's `history-limit` keeps the raw value.
lifecycle: capture on mount + a ↻ refresh, a request token that drops stale/late answers, an
explicit empty state ('' is an answer; a rejected capture is a failure, not empty), only the
LAST `MD_OUTPUT_MAX_LINES` (5000) lines rendered and announced when cut, scrolled to the latest
- output. Entering the view (output or ChatPanel) blurs the xterm; leaving it restores focus
+ output. Entering the view (output or ChatPanel) blurs the xterm and, for the ChatPanel, puts the
+ keyboard in its composer (only when focus was nowhere, in this node or in a terminal — never out
+ of a text field elsewhere; a lazy-loading or disabled composer takes it when it mounts/enables,
+ and an exit cancels the request); leaving it restores focus
only if the terminal had it on entry AND focus is now nowhere or still inside this node
(`terminal/useMdModeFocus.ts`). While the view is open, every "take the keyboard" path (hover
dwell, click, sidebar/notification jump) goes through `focusXtermUnlessCovered` and leaves the
diff --git a/src/renderer/nodes/ChatComposer.tsx b/src/renderer/nodes/ChatComposer.tsx
index 6854b4e62..0f80d7e57 100644
--- a/src/renderer/nodes/ChatComposer.tsx
+++ b/src/renderer/nodes/ChatComposer.tsx
@@ -19,6 +19,7 @@ import { chatKeyAction } from '../lib/chatPanel'
import { appendToComposer, composerLabels, composerPickerCommand, type ComposerPicker } from '../lib/chatComposer'
import { requestComposerDictation, subscribeComposerDictation } from '../lib/chatComposerDictation'
import { clipboardImages, pasteHasText, pastedFiles } from '../terminal/file-drop'
+import { takeComposerFocusRequest } from '../terminal/useMdModeFocus'
import { IconMic, IconPlus } from '../components/icons'
import { Spinner } from '../components/Spinner'
import { builtinSlashCommands, sanitizeChatCatalog, type ChatCatalogEntry } from '@shared/chat-catalog'
@@ -245,6 +246,13 @@ export function ChatComposer({
[onChange]
)
+ // Opening the ⌘M view hands the keyboard to the composer. On the first open the ChatPanel chunk
+ // is still loading when the view's entry runs, so the request waits for this mount — or, when
+ // the composer mounts disabled (a dialog on screen), for the moment it is enabled.
+ useEffect(() => {
+ if (!disabled) takeComposerFocusRequest(nodeId, inputRef.current)
+ }, [nodeId, disabled])
+
// A dictated take for THIS composer lands in the draft, never in the pane.
useEffect(() => subscribeComposerDictation(composerId, insertIntoComposer), [composerId, insertIntoComposer])
diff --git a/src/renderer/terminal/useMdModeFocus.test.tsx b/src/renderer/terminal/useMdModeFocus.test.tsx
index 6fed3020e..b25ba6626 100644
--- a/src/renderer/terminal/useMdModeFocus.test.tsx
+++ b/src/renderer/terminal/useMdModeFocus.test.tsx
@@ -7,7 +7,9 @@ import { resolve } from 'node:path'
import {
focusXtermUnlessCovered,
mayRestoreFocus,
+ mayFocusComposer,
requestTerminalFocusOnExit,
+ takeComposerFocusRequest,
terminalOwnsFileInput,
useMdModeFocus,
type FocusableTerm
@@ -238,6 +240,142 @@ describe('requestTerminalFocusOnExit (the ⌘M composer model / effort label)',
})
})
+/** A mounted ChatComposer as the hook sees it: the box carrying the id, its textarea inside. */
+function composerIn(parent: Element): HTMLTextAreaElement {
+ const box = document.createElement('div')
+ box.setAttribute('data-chat-composer-id', ':r1:')
+ const ta = document.createElement('textarea')
+ box.appendChild(ta)
+ parent.appendChild(box)
+ return ta
+}
+
+describe('useMdModeFocus — the chat composer takes the keyboard on entry', () => {
+ it('focuses a composer that is already mounted when the view opens', () => {
+ render(false, 'n1')
+ term!.focus()
+ const ta = composerIn(nodeRoot)
+
+ render(true, 'n1')
+
+ expect(document.activeElement).toBe(ta)
+ })
+
+ it('leaves a request that the composer takes when it mounts later (lazy chunk)', () => {
+ render(false, 'n1')
+ term!.focus()
+ render(true, 'n1')
+ const ta = composerIn(nodeRoot)
+
+ takeComposerFocusRequest('n1', ta)
+
+ expect(document.activeElement).toBe(ta)
+ })
+
+ it('takes a request only once', () => {
+ render(false, 'n1')
+ render(true, 'n1')
+ const ta = composerIn(nodeRoot)
+ takeComposerFocusRequest('n1', ta)
+ ta.blur()
+
+ takeComposerFocusRequest('n1', ta)
+
+ expect(document.activeElement).not.toBe(ta)
+ })
+
+ it('drops the request on exit, so a composer that appears later does not grab the keyboard', () => {
+ render(false, 'n1')
+ render(true, 'n1')
+ render(false, 'n1')
+ const ta = composerIn(nodeRoot)
+
+ takeComposerFocusRequest('n1', ta)
+
+ expect(document.activeElement).not.toBe(ta)
+ })
+
+ it('ignores a composer of the same session mounted outside this view (card modal vs node)', () => {
+ render(false, 'n1')
+ render(true, 'n1')
+ const elsewhere = document.createElement('div')
+ document.body.appendChild(elsewhere)
+ const other = composerIn(elsewhere)
+
+ takeComposerFocusRequest('n1', other)
+ const ta = composerIn(nodeRoot)
+ takeComposerFocusRequest('n1', ta)
+
+ expect(document.activeElement).toBe(ta)
+ })
+
+ it('leaves a text field elsewhere alone', () => {
+ render(false, 'n1')
+ const field = document.createElement('input')
+ document.body.appendChild(field)
+ field.focus()
+ const ta = composerIn(nodeRoot)
+
+ render(true, 'n1')
+
+ expect(document.activeElement).toBe(field)
+ takeComposerFocusRequest('n1', ta)
+ expect(document.activeElement).toBe(field)
+ })
+
+ it('does not focus a composer when the view is already open at mount (restored node, no entry)', () => {
+ const ta = composerIn(nodeRoot)
+
+ render(true, 'n1')
+
+ expect(document.activeElement).not.toBe(ta)
+ })
+
+ it('does not focus a disabled composer, but keeps the request for when it is enabled', () => {
+ render(false, 'n1')
+ render(true, 'n1')
+ const ta = composerIn(nodeRoot)
+ ta.disabled = true
+ takeComposerFocusRequest('n1', ta)
+ expect(document.activeElement).not.toBe(ta)
+ ta.disabled = false
+
+ takeComposerFocusRequest('n1', ta)
+
+ expect(document.activeElement).toBe(ta)
+ })
+
+ it('still gives the terminal back on exit after the composer had the keyboard', () => {
+ render(false, 'n1')
+ term!.focus()
+ const ta = composerIn(nodeRoot)
+ render(true, 'n1')
+ expect(document.activeElement).toBe(ta)
+ ta.parentElement!.remove() // the panel unmounts with the view
+ term!.calls.length = 0
+
+ render(false, 'n1')
+
+ expect(term!.calls).toEqual(['focus'])
+ })
+
+ it('treats another terminal as a pane, not a field the user is typing into', () => {
+ const other = document.createElement('textarea')
+ other.className = 'xterm-helper-textarea'
+
+ expect(mayFocusComposer(other, nodeRoot, document.body)).toBe(true)
+ expect(mayFocusComposer(document.createElement('input'), nodeRoot, document.body)).toBe(false)
+ })
+
+ it('the composer asks for the request on mount (source pin: ChatComposer cannot mount here)', () => {
+ const src = readFileSync(resolve(__dirname, '../nodes/ChatComposer.tsx'), 'utf8').replace(/\r\n/g, '\n')
+
+ expect(src).toMatch(
+ /useEffect\(\(\) => \{\s*if \(!disabled\) takeComposerFocusRequest\(nodeId, inputRef\.current\)\s*\}, \[nodeId, disabled\]\)/
+ )
+ })
+})
+
describe('terminalOwnsFileInput', () => {
it('hands dropped / pasted files to the terminal only while the ⌘M view is not covering it', () => {
expect(terminalOwnsFileInput(false)).toBe(true)
diff --git a/src/renderer/terminal/useMdModeFocus.ts b/src/renderer/terminal/useMdModeFocus.ts
index 4d5269071..4e3e7593d 100644
--- a/src/renderer/terminal/useMdModeFocus.ts
+++ b/src/renderer/terminal/useMdModeFocus.ts
@@ -12,7 +12,8 @@ export interface FocusableTerm {
*
* Opening the view covers the xterm but used to leave it focused, so every keystroke kept flowing
* into a pane the user could no longer see — into an agent's composer or a shell prompt. On entry
- * the terminal is blurred; on exit focus goes back ONLY if the terminal had it when the view
+ * the terminal is blurred and, when the face is the ChatPanel, its composer takes the keyboard
+ * (`takeComposerFocusRequest`); on exit focus goes back ONLY if the terminal had it when the view
* opened. Restoring unconditionally would pull focus out of whatever the user moved to meanwhile
* (another node, a text field) the moment they toggle the view off from the menu.
*
@@ -42,6 +43,57 @@ export function requestTerminalFocusOnExit(nodeId: string): void {
focusOnExit.add(nodeId)
}
+/**
+ * Entries of a ⌘M view whose chat composer has not mounted yet, keyed by node id. Opening the
+ * view moves the keyboard to the composer (the reason to open the chat face is usually to type
+ * into it), but the ChatPanel is code-split: on the first open it suspends, so the composer
+ * mounts a commit or more AFTER this hook's entry effect ran. The composer takes the request on
+ * mount (`takeComposerFocusRequest`). The root is kept so the composer can tell whether it is
+ * the one the request was made for (the canvas node and the kanban card modal share a node id)
+ * and whether the user moved on to something else while it loaded. Cleared on exit, so a
+ * composer that appears later — the session id arrived while the output view was up — does not
+ * grab the keyboard out of nowhere.
+ */
+const composerFocusPending = new Map<string, () => Element | null | undefined>()
+
+/** The selector of a mounted, usable chat composer textarea (ChatComposer's box carries the id). */
+const COMPOSER_TEXTAREA = '[data-chat-composer-id] textarea:not(:disabled)'
+
+/**
+ * Whether opening the ⌘M view may move the keyboard into its composer: focus is nowhere, already
+ * inside this node, or in a terminal (this one was just blurred; another terminal under a
+ * click-to-focus pointer is a pane, not a field the user is typing a form into). A text field
+ * elsewhere — a rename box, the sessions filter, another node's composer — keeps it.
+ */
+export function mayFocusComposer(
+ active: Element | null,
+ nodeRoot: Element | null | undefined,
+ body: Element | null
+): boolean {
+ if (mayRestoreFocus(active, nodeRoot, body)) return true
+ return active !== null && active.classList.contains('xterm-helper-textarea')
+}
+
+function focusComposerIn(root: Element | null | undefined): boolean {
+ const ta = root?.querySelector<HTMLTextAreaElement>(COMPOSER_TEXTAREA)
+ if (ta === null || ta === undefined) return false
+ ta.focus()
+ return true
+}
+
+/**
+ * Called by a chat composer on mount: if the ⌘M view of `nodeId` was just opened and its
+ * composer had not mounted yet, take the keyboard now. `el` is the composer's textarea.
+ */
+export function takeComposerFocusRequest(nodeId: string, el: HTMLTextAreaElement | null): void {
+ const getRoot = composerFocusPending.get(nodeId)
+ if (getRoot === undefined || el === null || el.disabled) return
+ const root = getRoot()
+ if (root === null || root === undefined || !root.contains(el)) return // another mount of the same session (card modal vs node)
+ composerFocusPending.delete(nodeId)
+ if (mayFocusComposer(document.activeElement, root, document.body)) el.focus()
+}
+
export function useMdModeFocus(
mdMode: boolean,
getTerm: () => FocusableTerm | null | undefined,
@@ -66,7 +118,18 @@ export function useMdModeFocus(
const ta = term?.textarea
restoreRef.current = !!ta && document.activeElement === ta
term?.blur()
- } else if (nodeIdRef.current !== undefined && focusOnExit.delete(nodeIdRef.current)) {
+ // Hand the keyboard to the chat composer (when this face has one). Mounted already — the
+ // ChatPanel chunk was loaded and the composer's own mount effect ran before this parent
+ // effect — focus it here; otherwise leave a request for its mount.
+ const id = nodeIdRef.current
+ const root = getRootRef.current()
+ if (id !== undefined && mayFocusComposer(document.activeElement, root, document.body)) {
+ if (!focusComposerIn(root)) composerFocusPending.set(id, () => getRootRef.current())
+ }
+ return
+ }
+ if (nodeIdRef.current !== undefined) composerFocusPending.delete(nodeIdRef.current)
+ if (nodeIdRef.current !== undefined && focusOnExit.delete(nodeIdRef.current)) {
// An explicit "go to the terminal" (see `requestTerminalFocusOnExit`): the user just clicked
// inside this node to get here, so nothing they chose elsewhere is being overridden.
restoreRef.current = false