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.9 KB
Raw Blame
// @vitest-environment jsdom
import { act } from 'react'
import { createRoot, type Root } from 'react-dom/client'
import { afterEach, describe, expect, it, vi } from 'vitest'
import {
  COMMAND_DEFINITIONS,
  getEffectiveBindings,
  normalizeBindingForCommand,
  sanitizeKeybindingOverrides,
  type CommandId
} from '@shared/keybindings'
import { DEFAULT_SETTINGS } from '@shared/types'
import { useSettings } from '../state/settings'
import { buildShortcutSections, ShortcutsPanel, type ShortcutSectionsOptions } from './ShortcutsPanel'

vi.mock('../bridge/runtime', () => ({ isBrowserRuntime: () => false }))

const BASE: Omit<ShortcutSectionsOptions, 'bindingsFor'> = {
  isMac: true,
  browser: false,
  panHoverDelay: DEFAULT_SETTINGS.panHoverDelay,
  dragMode: 'select',
  doubleClickFocus: true,
  wheelZoom: false,
  focusFollowsPointer: true
}

const build = (
  bindingsFor: (id: CommandId) => readonly string[],
  over: Partial<ShortcutSectionsOptions> = {}
) => buildShortcutSections({ ...BASE, ...over, bindingsFor })

const labelsOf = (sections: ReturnType<typeof buildShortcutSections>): string[] =>
  sections.flatMap((s) => s.rows.map((r) => r.label))

/** The row's FIRST chord — the shape most assertions care about. */
const rowFor = (
  sections: ReturnType<typeof buildShortcutSections>,
  label: string
): string[] | undefined =>
  sections.flatMap((s) => s.rows).find((r) => r.label === label)?.chords[0]

/** EVERY chord on the row. */
const chordsFor = (
  sections: ReturnType<typeof buildShortcutSections>,
  label: string
): string[][] | undefined =>
  sections.flatMap((s) => s.rows).find((r) => r.label === label)?.chords

/** Every command bound to its OWN distinct chord, so nothing is dropped as unbound and no two
 *  rows collide. Keys are drawn from a pool wide enough for the whole registry, and each chord
 *  is validated the way settings.json would be — a pool that ran out, or a chord a command's own
 *  flags refuse, must fail loudly here rather than silently shrink the expected row set. */
function bindEverything(isMac: boolean): (id: CommandId) => readonly string[] {
  const pool = [
    ...'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split(''),
    ...'0123456789'.split(''),
    ...Array.from({ length: 12 }, (_, i) => `F${i + 1}`),
    'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'PageUp', 'PageDown',
    'Comma', 'Slash', 'Period', 'Home', 'End', 'Insert', 'Delete', 'Backspace', 'Tab',
    '[', ']', ';', '='
  ]
  expect(pool.length).toBeGreaterThanOrEqual(COMMAND_DEFINITIONS.length)
  const map = new Map<CommandId, string[]>()
  COMMAND_DEFINITIONS.forEach((def, i) => {
    const chord = `Cmd+Alt+Shift+${pool[i]}`
    const r = normalizeBindingForCommand(def, chord, isMac)
    expect(r.ok, `${def.id} refused ${chord}`).toBe(true)
    map.set(def.id, [r.ok ? r.value : chord])
  })
  return (id) => map.get(id) ?? []
}

describe('buildShortcutSections — registry parity (watchdog)', () => {
  // THE guard: the panel derives its inventory from COMMAND_DEFINITIONS, so a command added to
  // the registry shows up here without an edit to ShortcutsPanel.tsx. A hand-written list — the
  // shape this file replaced, which had drifted 21 commands behind — reds this test.
  it('renders a row for EVERY registry command when all are bound', () => {
    const labels = labelsOf(build(bindEverything(true)))
    for (const def of COMMAND_DEFINITIONS) {
      // speech.dictation is the one row whose label is decorated by chord shape; a keyed chord
      // (which bindEverything hands it) keeps the bare title.
      expect(labels, `missing registry command: ${def.id}`).toContain(def.title)
    }
  })

  it('puts each command under its own registry group, in registry order', () => {
    const sections = build(bindEverything(true))
    for (const def of COMMAND_DEFINITIONS) {
      const section = sections.find((s) => s.rows.some((r) => r.label === def.title))
      expect(section?.title, `${def.id} landed in the wrong section`).toBe(def.group)
    }
    const groups = sections.map((s) => s.title)
    const expected: string[] = []
    for (const d of COMMAND_DEFINITIONS) if (!expected.includes(d.group)) expected.push(d.group)
    expect(groups.slice(0, expected.length)).toEqual(expected)
  })

  it('shows every command that ships with a default chord on this platform', () => {
    for (const isMac of [true, false]) {
      const labels = labelsOf(
        build((id) => getEffectiveBindings(id, {}, isMac), { isMac })
      )
      for (const def of COMMAND_DEFINITIONS) {
        const bound = (isMac ? def.defaultBindings.darwin : def.defaultBindings.other).length > 0
        if (!bound) continue
        // speech.dictation's default IS a hold chord, so its row carries the "(hold)" suffix —
        // the one command whose label is decorated by the shape of the chord it resolved to.
        const shown = labels.some((l) => l === def.title || l === `${def.title} (hold)`)
        expect(shown, `${def.id} (isMac=${isMac}) missing from the panel`).toBe(true)
      }
    }
  })
})

describe('buildShortcutSections — bindings', () => {
  it('omits a command with no effective binding', () => {
    const labels = labelsOf(build((id) => getEffectiveBindings(id, {}, true)))
    // Ships unbound on purpose (it expands the remappable pool), so it advertises no key.
    expect(labels).not.toContain('New sticky note')
  })

  it('omits a command the user DISABLED, and follows one they remapped', () => {
    const { overrides } = sanitizeKeybindingOverrides(
      { 'app.commandPalette': [], 'canvas.tidy': ['Cmd+Alt+Shift+F9'] },
      true
    )
    const sections = build((id) => getEffectiveBindings(id, overrides, true))
    expect(labelsOf(sections)).not.toContain('Command palette')
    expect(rowFor(sections, 'Tidy canvas')).toEqual(['⌘', '⌥', '⇧', 'F9'])
  })

  it('shows EVERY effective chord of a multi-binding command', () => {
    const sections = build((id) => getEffectiveBindings(id, {}, false), { isMac: false })
    expect(chordsFor(sections, 'Redo')).toEqual([
      ['Ctrl', 'Shift', 'Z'],
      ['Ctrl', 'Y']
    ])
    // The one that matters: off-mac Chromium reserves Ctrl+Shift+C for the inspector and a page
    // cannot preventDefault it, so in the Server Edition Ctrl+Insert is the ONLY chord that
    // copies. Printing the first chord alone advertised the broken one.
    expect(chordsFor(sections, 'Copy terminal selection')).toEqual([
      ['Ctrl', 'Shift', 'C'],
      ['Ctrl', 'Insert']
    ])
    // Same reason on the canvas: Delete and Backspace both delete.
    expect(chordsFor(sections, 'Delete selection')).toEqual([['Delete'], ['Backspace']])
  })

  it('spells the dictation row by the CHORD SHAPE, never settings.speech.shortcut', () => {
    const hold = build((id) => getEffectiveBindings(id, {}, true))
    expect(labelsOf(hold)).toContain('Dictate (hold)')
    const keyed = build((id) =>
      getEffectiveBindings(id, { 'speech.dictation': ['Cmd+Alt+Shift+D'] }, true)
    )
    expect(labelsOf(keyed)).toContain('Dictate')
    expect(labelsOf(keyed)).not.toContain('Dictate (hold)')
    // Disabled: `isHoldChord('')` is TRUE, so a missing `chord !== ''` check would print a
    // "(hold)" row for a shortcut the user turned off.
    const off = build((id) => getEffectiveBindings(id, { 'speech.dictation': [] }, true))
    expect(labelsOf(off).filter((l) => l.startsWith('Dictate'))).toEqual([])
  })
})

describe('buildShortcutSections — platform and non-command rows', () => {
  it('renders mac glyphs on mac and Ctrl/Shift words elsewhere', () => {
    const mac = build((id) => getEffectiveBindings(id, {}, true), { isMac: true })
    expect(rowFor(mac, 'Command palette')).toEqual(['⌘', 'K'])
    const other = build((id) => getEffectiveBindings(id, {}, false), { isMac: false })
    expect(rowFor(other, 'Command palette')).toEqual(['Ctrl', 'K'])
  })

  it('drops the ⌘1-9 project jump in the Server Edition (the browser owns it)', () => {
    const desktop = build(() => [], { browser: false })
    expect(labelsOf(desktop)).toContain('Jump to project')
    const browser = build(() => [], { browser: true })
    expect(labelsOf(browser)).not.toContain('Jump to project')
  })

  it('swaps the drag rows with settings.canvasDragMode', () => {
    const select = build(() => [], { dragMode: 'select' })
    expect(rowFor(select, 'Box-select (touch to select)')).toEqual(['Left-drag'])
    expect(rowFor(select, 'Pan the canvas')).toEqual(['Middle-drag'])
    const pan = build(() => [], { dragMode: 'pan' })
    expect(rowFor(pan, 'Pan the canvas')).toEqual(['Left-drag'])
    expect(rowFor(pan, 'Box-select (touch to select)')).toEqual(['⇧', 'drag'])
  })

  it('prints the live hover dwell, not a baked-in 0.6s', () => {
    expect(rowFor(build(() => [], { panHoverDelay: 250 }), 'Enter the terminal (type / select)'))
      .toEqual(['Hover 0.3s'])
    expect(rowFor(build(() => [], { panHoverDelay: 600 }), 'Enter the terminal (type / select)'))
      .toEqual(['Hover 0.6s'])
  })

  it('says "click" instead of a hover dwell when focus does not follow the pointer (#757)', () => {
    // Click-to-focus: no dwell ever hands over the keyboard, so printing "Hover 0.6s" would
    // advertise a gesture that does nothing.
    const click = build(() => [], { focusFollowsPointer: false, panHoverDelay: 600 })
    expect(rowFor(click, 'Enter the terminal (type / select)')).toEqual(['Click'])
    expect(rowFor(click, 'Move the terminal (before it focuses)')).toEqual(['Drag'])
    const hover = build(() => [], { focusFollowsPointer: true, panHoverDelay: 600 })
    expect(rowFor(hover, 'Move the terminal (before it focuses)')).toEqual(['Quick drag'])
  })

  it('names the force-select modifier per platform (Option on mac, Shift elsewhere)', () => {
    const label = 'Select in the emulator (apps that grab the mouse)'
    expect(rowFor(build(() => [], { isMac: true }), label)).toEqual(['⌥', 'drag'])
    expect(rowFor(build(() => [], { isMac: false }), label)).toEqual(['Shift', 'drag'])
  })

  it('gives every row in a section a distinct label (they key the rendered list)', () => {
    for (const s of build(bindEverything(true), { wheelZoom: true, dragMode: 'pan' })) {
      const labels = s.rows.map((r) => r.label)
      expect(new Set(labels).size, `duplicate label in ${s.title}`).toBe(labels.length)
    }
  })
})

describe('macOS screenshot paste discoverability', () => {
  it('distinguishes file paste from a foreground control key without promising agent support', () => {
    const sections = build(() => [])
    expect(rowFor(sections, 'Save the image and paste its file path')).toEqual(['⌘', 'V'])
    expect(rowFor(sections, 'Send a control key to the foreground program')).toEqual(['Ctrl', 'V'])
    const note = sections.find((s) => s.title === 'Pasting screenshots on macOS')?.note
    expect(note).toContain('only at that agent’s input prompt')
    expect(note).toContain('For SSH sessions, use Cmd+V')
    expect(note).toContain('does not detect image support or retry')
  })

  it('never advertises a local clipboard attachment from a Server browser', () => {
    const note = build(() => [], { browser: true })
      .find((s) => s.title === 'Pasting screenshots on macOS')?.note
    expect(note).toContain('Ctrl+V does not transfer your browser clipboard')
    expect(note).toContain('browser clipboard access')
    expect(note).not.toContain('may attach an image')
  })

  it('does not teach the macOS Ctrl+V behavior on other platforms', () => {
    for (const browser of [true, false]) {
      expect(rowFor(build(() => [], { isMac: false, browser }),
        'Send a control key to the foreground program')).toBeUndefined()
    }
  })
})

describe('ShortcutsPanel (DOM)', () => {
  ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
  let root: Root | null = null

  afterEach(() => {
    act(() => root?.unmount())
    root = null
    document.body.innerHTML = ''
    useSettings.setState({ settings: { ...DEFAULT_SETTINGS } })
    vi.restoreAllMocks()
  })

  const render = (props: Partial<Parameters<typeof ShortcutsPanel>[0]> = {}): void => {
    const host = document.createElement('div')
    document.body.appendChild(host)
    root = createRoot(host)
    act(() => root!.render(<ShortcutsPanel onClose={() => {}} {...props} />))
  }

  const rowLabels = (): string[] =>
    [...document.querySelectorAll('.shortcut-label')].map((n) => n.textContent ?? '')

  it('renders the screenshot explanation alongside both keys on macOS', () => {
    vi.spyOn(navigator, 'platform', 'get').mockReturnValue('MacIntel')
    render()
    expect(rowLabels()).toContain('Save the image and paste its file path')
    expect(rowLabels()).toContain('Send a control key to the foreground program')
    expect(document.querySelector('.shortcuts__note')?.textContent)
      .toContain('only at that agent’s input prompt')
  })

  it('reads the live override map through the settings store', () => {
    useSettings.setState({
      settings: { ...DEFAULT_SETTINGS, keybindings: { 'canvas.tidy': [] } as never }
    })
    render()
    expect(rowLabels()).toContain('Command palette')
    expect(rowLabels()).not.toContain('Tidy canvas')
  })

  it('separates a row\'s alternative chords rather than printing one run of badges', () => {
    render()
    const row = [...document.querySelectorAll('.shortcut-row')].find(
      (n) => n.querySelector('.shortcut-label')?.textContent === 'Delete selection'
    )
    expect(row).toBeTruthy()
    expect(row!.querySelectorAll('.shortcut-or').length).toBe(1)
    expect([...row!.querySelectorAll('.kbd')].map((n) => n.textContent)).toEqual([
      'Delete',
      'Backspace'
    ])
  })

  it('offers the Settings route only when the host wires it', () => {
    render()
    expect(document.querySelector('.shortcuts__customize')).toBeNull()
    act(() => root!.unmount())
    document.body.innerHTML = ''
    const onCustomize = vi.fn()
    render({ onCustomize })
    const btn = document.querySelector('.shortcuts__customize') as HTMLButtonElement
    expect(btn).not.toBeNull()
    act(() => btn.click())
    expect(onCustomize).toHaveBeenCalledOnce()
  })
})