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.

13.7 KB
Raw Blame
// @vitest-environment jsdom
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { createRoot, type Root } from 'react-dom/client'
import { act } from 'react'
import { readFileSync } from 'node:fs'
import { resolve } from 'node:path'
import {
  focusXtermUnlessCovered,
  mayRestoreFocus,
  mayFocusComposer,
  requestTerminalFocusOnExit,
  takeComposerFocusRequest,
  terminalOwnsFileInput,
  useMdModeFocus,
  type FocusableTerm
} from './useMdModeFocus'

;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true

/** A stand-in for xterm: its helper textarea is what holds DOM focus while the terminal types. */
function fakeTerm(): FocusableTerm & { calls: string[] } {
  const textarea = document.createElement('textarea')
  document.body.appendChild(textarea)
  const calls: string[] = []
  return {
    textarea,
    calls,
    blur: () => {
      calls.push('blur')
      textarea.blur()
    },
    focus: () => {
      calls.push('focus')
      textarea.focus()
    }
  }
}

let host: HTMLDivElement
let root: Root
let term: ReturnType<typeof fakeTerm> | null
/** The node root: the terminal's textarea lives inside it, like a real `.term-node`. */
let nodeRoot: HTMLDivElement

function Harness({ mdMode, nodeId }: { mdMode: boolean; nodeId?: string }) {
  useMdModeFocus(mdMode, () => term, () => nodeRoot, nodeId)
  return null
}

const render = (mdMode: boolean, nodeId?: string) =>
  act(() => root.render(<Harness mdMode={mdMode} nodeId={nodeId} />))

beforeEach(() => {
  host = document.createElement('div')
  document.body.appendChild(host)
  root = createRoot(host)
  nodeRoot = document.createElement('div')
  document.body.appendChild(nodeRoot)
  term = fakeTerm()
  nodeRoot.appendChild(term.textarea!)
})

afterEach(() => {
  act(() => root.unmount())
  document.body.innerHTML = ''
})

describe('useMdModeFocus', () => {
  it('blurs the terminal when the view opens, so keystrokes stop reaching the hidden pane', () => {
    render(false)
    term!.focus()
    render(true)
    expect(document.activeElement).not.toBe(term!.textarea)
    expect(term!.calls).toContain('blur')
  })

  it('gives focus back on exit when the terminal had it on entry', () => {
    render(false)
    term!.focus()
    render(true)
    term!.calls.length = 0
    render(false)
    expect(term!.calls).toEqual(['focus'])
    expect(document.activeElement).toBe(term!.textarea)
  })

  it('does NOT steal focus on exit when the terminal did not have it on entry', () => {
    const other = document.createElement('input')
    document.body.appendChild(other)
    render(false)
    other.focus()
    render(true)
    render(false)
    expect(term!.calls).not.toContain('focus')
    expect(document.activeElement).toBe(other)
  })

  it('had focus on entry, but the user focused an input elsewhere meanwhile → no focus()', () => {
    render(false)
    term!.focus()
    render(true)
    const elsewhere = document.createElement('input')
    document.body.appendChild(elsewhere)
    elsewhere.focus()
    term!.calls.length = 0
    render(false)
    expect(term!.calls).not.toContain('focus')
    expect(document.activeElement).toBe(elsewhere)
  })

  it('restores when focus meanwhile stayed inside this node (e.g. the view\'s own controls)', () => {
    render(false)
    term!.focus()
    render(true)
    const insideNode = document.createElement('button')
    nodeRoot.appendChild(insideNode)
    insideNode.focus()
    term!.calls.length = 0
    render(false)
    expect(term!.calls).toEqual(['focus'])
  })

  it('never focuses on first mount, whatever the mode', () => {
    render(false)
    expect(term!.calls).toEqual([])
  })

  it('tolerates a terminal that does not exist (released / not yet spawned)', () => {
    term = null
    render(false)
    render(true)
    render(false)
  })
})

describe('mayRestoreFocus', () => {
  const body = document.createElement('body')
  const nodeRoot = document.createElement('div')
  const inside = document.createElement('span')
  nodeRoot.appendChild(inside)
  const outside = document.createElement('input')

  it('allows it when focus is nowhere or inside the node', () => {
    expect(mayRestoreFocus(null, nodeRoot, body)).toBe(true)
    expect(mayRestoreFocus(body, nodeRoot, body)).toBe(true)
    expect(mayRestoreFocus(inside, nodeRoot, body)).toBe(true)
  })

  it('refuses when focus is somewhere else, or the node root is unknown', () => {
    expect(mayRestoreFocus(outside, nodeRoot, body)).toBe(false)
    expect(mayRestoreFocus(inside, null, body)).toBe(false)
  })
})

describe('focusXtermUnlessCovered', () => {
  it('focuses only while the ⌘M view is not covering the terminal', () => {
    let n = 0
    const t: FocusableTerm = { blur: () => {}, focus: () => void n++ }
    focusXtermUnlessCovered(t, true)
    expect(n).toBe(0)
    focusXtermUnlessCovered(t, false)
    expect(n).toBe(1)
    focusXtermUnlessCovered(null, false)
  })

  it('is what every TerminalNode "take the keyboard" path calls (no bare xterm focus left)', () => {
    // Source pin: the dwell and enterNow are closures deep in a 6000-line component that cannot
    // be mounted here; a bare `termRef.current?.focus()` reintroduced there would route
    // keystrokes into the hidden pane again with every unit test still green.
    const src = readFileSync(resolve(__dirname, '../nodes/TerminalNode.tsx'), 'utf8').replace(/\r\n/g, '\n')
    expect(src).not.toMatch(/termRef\.current\?\.focus\(\)/)
    // Three paths: the hover dwell, `enterNow`, and the click-to-focus reclaim after a press on the
    // node's own chrome (#757) — each one asks about the cover.
    expect(src.match(/focusXtermUnlessCovered\(termRef\.current, mdModeRef\.current\)/g)?.length).toBe(3)
  })

  it('the kanban card modal viewer uses the same hand-off (blur when covered, no attach-time focus)', () => {
    // Source pin, same reason: ModalTerminal attaches asynchronously and focuses on completion,
    // which a quick ⌘M in the card modal can precede — that focus must ask about the cover too.
    const src = readFileSync(resolve(__dirname, '../components/kanban/ModalTerminal.tsx'), 'utf8').replace(/\r\n/g, '\n')
    expect(src).toMatch(/useMdModeFocus\(covered,/)
    expect(src).toMatch(/focusXtermUnlessCovered\(term, coveredRef\.current\)/)
  })
})

describe('requestTerminalFocusOnExit (the ⌘M composer model / effort label)', () => {
  it('focuses the terminal on exit even when it did NOT have focus on entry (⌘K / menu / board)', () => {
    render(false, 'n1')
    render(true, 'n1')
    term!.calls.length = 0
    requestTerminalFocusOnExit('n1')
    render(false, 'n1')
    expect(term!.calls).toEqual(['focus'])
    expect(document.activeElement).toBe(term!.textarea)
  })

  it('wins over focus sitting elsewhere: the click that asked for it was the user choosing', () => {
    render(false, 'n2')
    render(true, 'n2')
    const other = document.createElement('input')
    document.body.appendChild(other)
    other.focus()
    requestTerminalFocusOnExit('n2')
    render(false, 'n2')
    expect(document.activeElement).toBe(term!.textarea)
  })

  it('is consumed once: the next ordinary exit is back on the restore rule', () => {
    render(false, 'n3')
    render(true, 'n3')
    requestTerminalFocusOnExit('n3')
    render(false, 'n3')
    term!.textarea!.blur()
    render(true, 'n3')
    term!.calls.length = 0
    render(false, 'n3')
    expect(term!.calls).toEqual([])
  })

  it("answers only its own node's request", () => {
    render(false, 'mine')
    render(true, 'mine')
    term!.calls.length = 0
    requestTerminalFocusOnExit('someone-else')
    render(false, 'mine')
    expect(term!.calls).toEqual([])
  })

  it('both mount sites request focus before flipping, and both hooks are keyed by node id', () => {
    // Source pins: TerminalNode and CardModal cannot be mounted here. The request must come
    // BEFORE the state change, or the hook's exit transition runs first and misses it.
    const read = (rel: string) => readFileSync(resolve(__dirname, rel), 'utf8').replace(/\r\n/g, '\n')
    const node = read('../nodes/TerminalNode.tsx')
    expect(node).toMatch(/useMdModeFocus\(mdMode, \(\) => termRef\.current, \(\) => rootRef\.current, id\)/)
    expect(node).toMatch(/requestTerminalFocusOnExit\(id\)\s*\n\s*updateNodeData\(id, \(\) => \(\{ mdMode: false \}\)\)/)
    const modal = read('../components/kanban/CardModal.tsx')
    expect(modal).toMatch(/requestTerminalFocusOnExit\(session\.id\)\s*\n\s*setMdFor\(null\)/)
    const viewer = read('../components/kanban/ModalTerminal.tsx')
    expect(viewer).toMatch(/useMdModeFocus\(covered, [^\n]*, nodeId\)/)
  })
})

/** 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)
    expect(terminalOwnsFileInput(true)).toBe(false)
  })

  it("gates every TerminalNode file-input handler on the node's ⌘M cover", () => {
    // Source pin: the handlers sit on `.term-node__body`, which ALSO hosts the ⌘M overlay — so a
    // screenshot pasted into the ChatPanel composer (or a file dropped on the view) was caught in
    // the capture phase and pasted as a path into the hidden pane, with focus stolen to match.
    // The handlers are closures in a component that cannot be mounted here.
    const src = readFileSync(resolve(__dirname, '../nodes/TerminalNode.tsx'), 'utf8').replace(/\r\n/g, '\n')
    for (const handler of ['onBodyDragOver', 'onBodyDrop', 'onBodyPaste']) {
      const start = src.indexOf(`const ${handler} = `)
      expect(start, handler).toBeGreaterThan(-1)
      const head = src.slice(start, src.indexOf('\n', src.indexOf('\n', start) + 1))
      expect(head, handler).toMatch(/if \(!terminalOwnsFileInput\(mdModeRef\.current\)\) return/)
    }
  })
})