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.

10.7 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import type { Terminal } from '@xterm/xterm'
import { patchViewportScrollSync } from './viewport-scroll-sync'

interface FakeDims {
  css: { canvas: { width: number; height: number }; cell: { width: number; height: number } }
  device: { cell: { width: number; height: number } }
}

function makeDims(cellH: number, canvasH: number): FakeDims {
  return {
    css: { canvas: { width: 640, height: canvasH }, cell: { width: 8, height: cellH } },
    device: { cell: { width: 8, height: cellH } }
  }
}

function createFakeTerm(opts?: { rows?: number; cols?: number; rowHeight?: number }) {
  const rows = opts?.rows ?? 50
  const cols = opts?.cols ?? 80
  const rowHeight = opts?.rowHeight ?? 16
  let csiJHandler: ((params: { params: number[] }) => boolean) | null = null

  const buffer = {
    lines: { length: 200 },
    ybase: 150,
    ydisp: 150
  }
  const bufferService = {
    buffer,
    isUserScrolling: false
  }

  let currentDims = makeDims(rowHeight, rows * rowHeight)
  let resizeCalls = 0
  const renderService = {
    get dimensions() {
      return currentDims
    },
    setRenderer(newRenderer: { dimensions: FakeDims }) {
      currentDims = newRenderer.dimensions
    },
    handleResize(_c: number, _r: number) {
      resizeCalls++
      if (currentDims.device.cell.height === 0) {
        currentDims = makeDims(rowHeight, rows * rowHeight)
      }
    }
  }

  let rawScrollTop = 150 * rowHeight
  let scrollAreaHeightPx = 200 * rowHeight
  const viewportHeight = rows * rowHeight

  // Simulate Blink's synchronous layout clamping when scrollArea.style.height shrinks and
  // viewportElement.scrollTop is subsequently read.
  const scrollArea = {
    style: {
      set height(v: string) {
        scrollAreaHeightPx = Number.parseFloat(v) || 0
      },
      get height() {
        return `${scrollAreaHeightPx}px`
      }
    }
  } as unknown as HTMLElement

  const viewportElement = {
    offsetHeight: viewportHeight,
    get scrollTop() {
      const maxScroll = Math.max(0, scrollAreaHeightPx - viewportHeight)
      if (rawScrollTop > maxScroll) {
        rawScrollTop = maxScroll
      }
      return rawScrollTop
    },
    set scrollTop(v: number) {
      const maxScroll = Math.max(0, scrollAreaHeightPx - viewportHeight)
      rawScrollTop = Math.max(0, Math.min(v, maxScroll))
    }
  } as unknown as HTMLElement

  let syncImmediateCalls = 0
  let wheelCalls = 0
  const viewport = {
    _viewportElement: viewportElement,
    _scrollArea: scrollArea,
    _renderDimensions: currentDims,
    _activeBuffer: buffer,
    _currentRowHeight: rowHeight,
    _currentDeviceCellHeight: rowHeight,
    _lastRecordedBufferLength: 200,
    _lastRecordedViewportHeight: viewportHeight,
    _lastRecordedBufferHeight: 200 * rowHeight,
    _lastScrollTop: 150 * rowHeight,
    _ignoreNextScrollEvent: false,
    _innerRefresh() {
      this._currentRowHeight = this._renderDimensions.device.cell.height
      this._currentDeviceCellHeight = this._renderDimensions.device.cell.height
      this._lastRecordedViewportHeight = viewportHeight
      const newBufferHeight =
        Math.round(this._currentRowHeight * this._lastRecordedBufferLength) +
        (this._lastRecordedViewportHeight - this._renderDimensions.css.canvas.height)
      if (this._lastRecordedBufferHeight !== newBufferHeight) {
        this._lastRecordedBufferHeight = newBufferHeight
        scrollArea.style.height = `${this._lastRecordedBufferHeight}px`
      }
      const scrollTop = bufferService.buffer.ydisp * this._currentRowHeight
      // Mirrors xterm's exact line 134: reading viewportElement.scrollTop triggers layout clamping!
      if (viewportElement.scrollTop !== scrollTop) {
        this._ignoreNextScrollEvent = true
        viewportElement.scrollTop = scrollTop
      }
    },
    syncScrollArea(immediate?: boolean) {
      if (immediate) {
        syncImmediateCalls++
        this._lastRecordedBufferLength = bufferService.buffer.lines.length
        this._innerRefresh()
      }
    },
    handleWheel(ev: WheelEvent) {
      wheelCalls++
      viewportElement.scrollTop += ev.deltaY
      return true
    }
  }

  const term = {
    cols,
    rows,
    parser: {
      registerCsiHandler(id: { final: string }, cb: (params: { params: number[] }) => boolean) {
        if (id.final === 'J') csiJHandler = cb
        return { dispose() {} }
      }
    },
    _core: {
      _renderService: renderService,
      _bufferService: bufferService,
      viewport
    }
  } as unknown as Terminal

  return {
    term,
    buffer,
    bufferService,
    renderService,
    viewport,
    viewportElement,
    getCsiJHandler: () => csiJHandler,
    getResizeCalls: () => resizeCalls,
    getSyncImmediateCalls: () => syncImmediateCalls,
    getWheelCalls: () => wheelCalls
  }
}

describe('patchViewportScrollSync', () => {
  it('flags _ignoreNextScrollEvent when shrinking scrollArea clamps scrollTop to 0 during CSI 3 J', () => {
    const { term, buffer, viewport } = createFakeTerm()
    expect(patchViewportScrollSync(term)).toBe(true)

    // Simulate CSI 3 J (clear scrollback): buffer shrinks to 50 rows and ybase/ydisp become 0.
    buffer.lines.length = 50
    buffer.ybase = 0
    buffer.ydisp = 0

    // Without the patch, shrinking scrollArea.style.height clamps viewportElement.scrollTop from
    // 2400 -> 0 on read, so `viewportElement.scrollTop !== 0` is false and _ignoreNextScrollEvent
    // stays false (causing the queued DOM 'scroll' event to yank ydisp to 0 and lock isUserScrolling).
    viewport._innerRefresh()
    expect(viewport._ignoreNextScrollEvent).toBe(true)
    expect(viewport._lastScrollTop).toBe(0)
  })

  it('clears _ignoreNextScrollEvent when a programmatic scrollTop assignment is clamped with no movement', () => {
    const { term, buffer, viewport, viewportElement } = createFakeTerm()
    patchViewportScrollSync(term)

    // Scroll area is only 1 page (50 rows = 800px), so maxScrollTop is 0, and scrollTop is 0.
    buffer.lines.length = 50
    buffer.ybase = 0
    buffer.ydisp = 0
    viewport._innerRefresh()
    // Consume the initial clamp's ignore flag
    viewport._ignoreNextScrollEvent = false
    expect(viewportElement.scrollTop).toBe(0)

    // Suppose ydisp is transiently > 0 while scrollArea cannot scroll past 0: xterm sets
    // _ignoreNextScrollEvent = true and assigns scrollTop, which clamps back to 0 (no DOM scroll event).
    buffer.ydisp = 10
    // Force scrollArea height to remain 800px by keeping lines.length = 50
    viewport._innerRefresh()
    expect(viewportElement.scrollTop).toBe(0)
    expect(viewport._ignoreNextScrollEvent).toBe(false)
  })

  it('resets BufferService.isUserScrolling on CSI 3 J (Erase Saved Lines) but not CSI 2 J', () => {
    const { term, bufferService, getCsiJHandler } = createFakeTerm()
    patchViewportScrollSync(term)
    const handler = getCsiJHandler()
    expect(handler).not.toBeNull()

    // Public `term.parser.registerCsiHandler` passes `(number | number[])[]` via `IParams.toArray()`
    bufferService.isUserScrolling = true
    expect(handler!([2] as unknown as { params: number[] })).toBe(false)
    expect(bufferService.isUserScrolling).toBe(true)

    expect(handler!([3] as unknown as { params: number[] })).toBe(false)
    expect(bufferService.isUserScrolling).toBe(false)

    // Also supports `_core.registerCsiHandler` style `{ params: number[] }`
    bufferService.isUserScrolling = true
    expect(handler!({ params: [3] })).toBe(false)
    expect(bufferService.isUserScrolling).toBe(false)
  })

  it('parses CSI 2 J and CSI 3 J on a real @xterm/xterm Terminal without throwing in WriteBuffer', async () => {
    const { Terminal: RealTerminal } = await import('@xterm/xterm')
    const realTerm = new RealTerminal({ rows: 10, cols: 40, scrollback: 100 })
    const core = (realTerm as unknown as { _core: Record<string, unknown> })._core
    // Attach a minimal viewport & renderService stub to headless Terminal so patchViewportScrollSync installs
    core._renderService = {
      dimensions: makeDims(16, 160),
      setRenderer() {},
      handleResize() {},
      refreshRows() {}
    }
    core.viewport = {
      _innerRefresh() {},
      syncScrollArea() {}
    }
    expect(patchViewportScrollSync(realTerm)).toBe(true)

    const bufSvc = core._bufferService as { isUserScrolling: boolean; buffer: { ybase: number; ydisp: number } }
    await new Promise<void>((resolve) => {
      realTerm.write(
        Array.from({ length: 25 }, (_, i) => `line-${i}`).join('\r\n'),
        () => resolve()
      )
    })
    bufSvc.isUserScrolling = true
    bufSvc.buffer.ydisp = 0

    // Emit the exact Antigravity CLI inline redraw burst: \x1b[2J\x1b[3J\x1b[H followed by 25 lines
    await new Promise<void>((resolve) => {
      realTerm.write(
        '\x1b[2J\x1b[3J\x1b[H' + Array.from({ length: 25 }, (_, i) => `rewritten-${i}`).join('\r\n'),
        () => resolve()
      )
    })

    expect(bufSvc.isUserScrolling).toBe(false)
    expect(bufSvc.buffer.ybase).toBeGreaterThan(0)
    expect(bufSvc.buffer.ydisp).toBe(bufSvc.buffer.ybase)
    realTerm.dispose()
  })

  it('updates Viewport._renderDimensions and syncs scroll area across setRenderer swaps', () => {
    const { term, renderService, viewport, getResizeCalls, getSyncImmediateCalls } = createFakeTerm()
    patchViewportScrollSync(term)

    // Simulate WebglAddon dispose / fresh DomRenderer whose dimensions start at 0 before handleResize
    const zeroDims = makeDims(0, 0)
    renderService.setRenderer({ dimensions: zeroDims })

    expect(getResizeCalls()).toBe(1)
    expect(viewport._renderDimensions).toBe(renderService.dimensions)
    expect(viewport._renderDimensions.device.cell.height).toBe(16)
    expect(getSyncImmediateCalls()).toBeGreaterThanOrEqual(1)
  })

  it('synchronizes stale scrollArea before handling wheel events', () => {
    const { term, buffer, viewport, viewportElement, getSyncImmediateCalls } = createFakeTerm()
    patchViewportScrollSync(term)

    // Simulate 3 pages of output written after a scrollback clear before rAF ran _innerRefresh
    buffer.lines.length = 50
    buffer.ybase = 0
    buffer.ydisp = 0
    viewport._innerRefresh()

    buffer.lines.length = 200
    buffer.ybase = 150
    buffer.ydisp = 150
    // Notice viewport._lastRecordedBufferLength is still 50 and scrollArea is still 800px!
    const beforeSyncs = getSyncImmediateCalls()

    viewport.handleWheel({ deltaY: -48 } as WheelEvent)
    expect(getSyncImmediateCalls()).toBe(beforeSyncs + 1)
    expect(viewportElement.scrollTop).toBe(150 * 16 - 48)
  })

  it('is idempotent and fails open when xterm internals are missing', () => {
    const { term } = createFakeTerm()
    expect(patchViewportScrollSync(term)).toBe(true)
    expect(patchViewportScrollSync(term)).toBe(true)
    expect(patchViewportScrollSync({} as Terminal)).toBe(false)
  })
})