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.

38.6 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import {
  THEME,
  fakeBlinkSeam,
  fakeDecorations,
  fakeTerm,
  recordingAtlas,
  recordingHandle,
  type FakeTermOpts
} from './addon-fakes'
import { CELL_STRIDE, FLAG_CURSOR, FLAG_SELECTED, packColor, readCell } from './cells'
import type { GridCursor } from './cursor'
import { GlyphGridRendererAddonCore, type DeviceMetrics } from './addon'

function make(
  o: FakeTermOpts & { atlas?: ReturnType<typeof recordingAtlas> } = {}
): {
  core: GlyphGridRendererAddonCore
  term: ReturnType<typeof fakeTerm>
  handle: ReturnType<typeof recordingHandle>
  atlas: ReturnType<typeof recordingAtlas>
} {
  const term = fakeTerm(o)
  const handle = recordingHandle()
  const atlas = o.atlas ?? recordingAtlas()
  const core = new GlyphGridRendererAddonCore(term, handle, atlas)
  return { core, term, handle, atlas }
}

/** The glyph lane of a packed row decodes back to (absRow, col) — see rowCodedCell. */
function decodeRow(cells: Uint32Array, cols: number): Array<{ absRow: number; col: number }> {
  const out: Array<{ absRow: number; col: number }> = []
  for (let c = 0; c < cols; c++) {
    const g = readCell(cells, c).glyph
    out.push({ absRow: Math.floor((g - 0x100) / 16), col: (g - 0x100) % 16 })
  }
  return out
}

describe('GlyphGridRendererAddonCore.renderRows', () => {
  it('packs exactly the requested viewport rows, mapped through viewportY', () => {
    const { core, handle } = make({ viewportY: 0 })
    core.renderRows(2, 4)
    expect(handle.rows.map((r) => r.row)).toEqual([2, 3, 4])
    for (const rec of handle.rows) {
      // Every column of the row came from the SAME absolute buffer row, and that row is the
      // viewport row (viewportY = 0).
      expect(decodeRow(rec.cells, 4).map((d) => d.absRow)).toEqual([rec.row, rec.row, rec.row, rec.row])
      expect(decodeRow(rec.cells, 4).map((d) => d.col)).toEqual([0, 1, 2, 3])
    }
  })

  it('maps a SCROLLED buffer: viewport row r reads absolute row viewportY + r', () => {
    const { core, handle } = make({ viewportY: 100, baseY: 140 })
    core.renderRows(0, 1)
    expect(handle.rows.map((r) => r.row)).toEqual([0, 1])
    expect(decodeRow(handle.rows[0].cells, 4)[0].absRow).toBe(100)
    expect(decodeRow(handle.rows[1].cells, 4)[0].absRow).toBe(101)
  })

  it('clamps the requested range to the grid', () => {
    const { core, handle } = make({ rows: 3 })
    core.renderRows(-5, 99)
    expect(handle.rows.map((r) => r.row)).toEqual([0, 1, 2])
  })

  it('reuses ONE row buffer across rows (allocation-free hot path)', () => {
    const { core, handle } = make()
    core.renderRows(0, 3)
    const first = handle.rows[0].buf
    for (const rec of handle.rows) expect(rec.buf).toBe(first)
    expect(first.length).toBe(4 * CELL_STRIDE)
  })

  it('paints the block cursor on the cursor row, converted from base-relative coords', () => {
    // Cursor sits at buffer row baseY + cursorY = 140 + 3 = 143; the viewport starts at 140, so
    // it belongs on viewport row 3.
    const { core, handle } = make({ viewportY: 140, baseY: 140, cursorY: 3, cursorX: 2 })
    core.renderRows(0, 5)
    const flagsOn = (row: number, col: number): number =>
      readCell(handle.rows.find((r) => r.row === row)!.cells, col).flags & FLAG_CURSOR
    expect(flagsOn(3, 2)).toBe(FLAG_CURSOR)
    expect(flagsOn(3, 1)).toBe(0)
    expect(flagsOn(2, 2)).toBe(0)
  })

  it('clamps a deferred-wrap cursor (x === cols) onto the last column', () => {
    const { core, handle } = make({ cols: 4, rows: 2, cursorX: 4, cursorY: 0 })
    core.renderRows(0, 1)
    const row0 = handle.rows.find((r) => r.row === 0)!
    expect(readCell(row0.cells, 3).flags & FLAG_CURSOR).toBe(FLAG_CURSOR)
    expect(readCell(row0.cells, 2).flags & FLAG_CURSOR).toBe(0)
  })

  it('paints NO cursor while the cursor is hidden or the terminal is blurred', () => {
    const hidden = make({ cursorVisible: false, cursorY: 1, cursorX: 1 })
    hidden.core.renderRows(0, 2)
    for (const rec of hidden.handle.rows)
      for (let c = 0; c < 4; c++) expect(readCell(rec.cells, c).flags & FLAG_CURSOR).toBe(0)

    const blurred = make({ focus: false, cursorY: 1, cursorX: 1 })
    blurred.core.renderRows(0, 2)
    for (const rec of blurred.handle.rows)
      for (let c = 0; c < 4; c++) expect(readCell(rec.cells, c).flags & FLAG_CURSOR).toBe(0)
  })
})

describe('GlyphGridRendererAddonCore.handleResize', () => {
  it('resizes the grid BEFORE repacking, then repacks every row', () => {
    const { core, handle } = make({ cols: 4, rows: 6 })
    handle.log.length = 0
    handle.rows.length = 0
    core.handleResize(8, 3)
    expect(handle.log[0]).toBe('resize:8x3')
    expect(handle.rows.map((r) => r.row)).toEqual([0, 1, 2])
    // The row buffer follows the new column count — the engine rejects a mismatched length.
    expect(handle.rows[0].buf.length).toBe(8 * CELL_STRIDE)
    expect(handle.rows[0].cells.length).toBe(8 * CELL_STRIDE)
  })

  it('updates dimensions from the new grid size', () => {
    const { core } = make({ cols: 4, rows: 6 })
    core.handleResize(10, 5)
    expect(core.dimensions.device.canvas.width).toBe(16 * 10)
    expect(core.dimensions.device.canvas.height).toBe(34 * 5)
    expect(core.dimensions.css.canvas.width).toBe(80) // round(160 / dpr 2)
    expect(core.dimensions.css.cell.width).toBe(8)
  })
})

describe('GlyphGridRendererAddonCore.dimensions', () => {
  it('is ONE object, mutated in place — xterm Viewport caches it by reference', () => {
    const { core, term } = make({ cols: 4, rows: 6 })
    const dims = core.dimensions
    const cssCell = dims.css.cell
    const deviceChar = dims.device.char

    core.handleResize(10, 5)
    expect(core.dimensions).toBe(dims)
    expect(core.dimensions.css.cell).toBe(cssCell)
    expect(cssCell.width).toBe(8)
    expect(dims.device.canvas.width).toBe(160)

    // A font-size change reaches us as new device metrics + handleCharSizeChanged.
    term.deviceMetrics = (): DeviceMetrics => ({ charW: 20, charH: 40, cellW: 20, cellH: 40 })
    core.handleCharSizeChanged()
    expect(core.dimensions).toBe(dims)
    expect(deviceChar.width).toBe(20)
    expect(dims.device.cell.height).toBe(40)
    expect(cssCell.height).toBe(20) // round(40 * 5 / dpr 2) / 5

    core.handleDevicePixelRatioChange()
    expect(core.dimensions).toBe(dims)
  })

  it('mirrors xterm dimension shape at construction', () => {
    const { core } = make({ cols: 4, rows: 6 })
    expect(core.dimensions).toEqual({
      css: { canvas: { width: 32, height: 102 }, cell: { width: 8, height: 17 } },
      device: {
        canvas: { width: 64, height: 204 },
        cell: { width: 16, height: 34 },
        char: { width: 16, height: 34, left: 0, top: 0 }
      }
    })
  })
})

describe('GlyphGridRendererAddonCore selection', () => {
  it('repacks the union of the OLD and NEW spans, and nothing else', () => {
    const { core, handle } = make({ rows: 8, viewportY: 0 })
    core.handleSelectionChanged([1, 1], [2, 2], false)
    handle.rows.length = 0
    core.handleSelectionChanged([0, 5], [3, 6], false)
    expect([...new Set(handle.rows.map((r) => r.row))].sort((a, b) => a - b)).toEqual([1, 2, 5, 6])
  })

  it('repacks the cleared rows when the selection goes away', () => {
    const { core, handle } = make({ rows: 8 })
    core.handleSelectionChanged([1, 2], [3, 3], false)
    handle.rows.length = 0
    core.handleSelectionChanged(undefined, undefined, false)
    expect(handle.rows.map((r) => r.row)).toEqual([2, 3])
    for (const rec of handle.rows)
      for (let c = 0; c < 4; c++) expect(readCell(rec.cells, c).flags & FLAG_SELECTED).toBe(0)
  })

  it('marks a LINEAR span: first row from startCol, middle rows full width, last row to endCol', () => {
    const { core, handle } = make({ rows: 8, cols: 4 })
    core.handleSelectionChanged([2, 1], [3, 3], false)
    const sel = (row: number): number[] =>
      [0, 1, 2, 3].filter(
        (c) => readCell(handle.rows.find((r) => r.row === row)!.cells, c).flags & FLAG_SELECTED
      )
    expect(sel(1)).toEqual([2, 3])
    expect(sel(2)).toEqual([0, 1, 2, 3])
    expect(sel(3)).toEqual([0, 1, 2])
  })

  it('marks a RECTANGULAR (column-select) span identically on every row in range', () => {
    const { core, handle } = make({ rows: 8, cols: 4 })
    core.handleSelectionChanged([3, 1], [1, 3], true)
    const sel = (row: number): number[] =>
      [0, 1, 2, 3].filter(
        (c) => readCell(handle.rows.find((r) => r.row === row)!.cells, c).flags & FLAG_SELECTED
      )
    // Endpoints arrive in either order; the rectangle spans [min, max).
    expect(sel(1)).toEqual([1, 2])
    expect(sel(2)).toEqual([1, 2])
    expect(sel(3)).toEqual([1, 2])
  })

  it('translates an absolute span through a scrolled viewport', () => {
    const { core, handle } = make({ rows: 4, cols: 4, viewportY: 100, baseY: 100 })
    core.handleSelectionChanged([0, 101], [4, 101], false)
    expect(handle.rows.map((r) => r.row)).toEqual([1])
    expect(readCell(handle.rows[0].cells, 0).flags & FLAG_SELECTED).toBe(FLAG_SELECTED)
  })

  it('ignores a span that lies entirely outside the viewport', () => {
    const { core, handle } = make({ rows: 4, viewportY: 100 })
    handle.rows.length = 0
    core.handleSelectionChanged([0, 10], [4, 12], false)
    expect(handle.rows).toEqual([])
  })
})

describe('GlyphGridRendererAddonCore cursor + focus', () => {
  it('repacks exactly the old and the new cursor row on a move', () => {
    const { core, term, handle } = make({ rows: 8, cursorY: 1 })
    core.renderRows(0, 7)
    handle.rows.length = 0
    term.state.cursorY = 5
    core.handleCursorMove()
    expect(handle.rows.map((r) => r.row).sort((a, b) => a - b)).toEqual([1, 5])
  })

  it('repacks one row when the cursor moves within its row', () => {
    const { core, term, handle } = make({ rows: 8, cursorY: 2, cursorX: 0 })
    handle.rows.length = 0
    term.state.cursorX = 3
    core.handleCursorMove()
    expect(handle.rows.map((r) => r.row)).toEqual([2])
    expect(readCell(handle.rows[0].cells, 3).flags & FLAG_CURSOR).toBe(FLAG_CURSOR)
  })

  it('blur repacks the cursor row without the cursor; focus paints it back', () => {
    const { core, handle } = make({ rows: 8, cursorY: 4, cursorX: 1 })
    handle.rows.length = 0
    core.handleBlur()
    expect(handle.rows.map((r) => r.row)).toEqual([4])
    expect(readCell(handle.rows[0].cells, 1).flags & FLAG_CURSOR).toBe(0)

    handle.rows.length = 0
    core.handleFocus()
    expect(handle.rows.map((r) => r.row)).toEqual([4])
    expect(readCell(handle.rows[0].cells, 1).flags & FLAG_CURSOR).toBe(FLAG_CURSOR)
  })
})

/** THE CURSOR SHAPE — which half of the renderer draws it, and where.
 *
 *  A block is a CELL rewrite (only the cell path can invert the glyph) and every other shape is an
 *  OVERLAY pushed to the grid. So each test here asserts BOTH halves: the shape that should be drawn
 *  as an overlay, and the absence of the one that should not be drawn as cells — a bug that put the
 *  cursor on both paths would paint an opaque quad over the very inversion it just produced. */
describe('GlyphGridRendererAddonCore cursor shape', () => {
  const last = (h: ReturnType<typeof recordingHandle>): GridCursor | null | undefined =>
    h.cursors.at(-1)

  it('pushes NO overlay for a focused block — the cells carry it', () => {
    const { core, handle } = make({ rows: 4, cursorY: 1, cursorX: 2, cursorStyle: { style: 'block' } })
    core.renderRows(0, 3)
    expect(last(handle)).toBe(null)
    expect(readCell(handle.rows.find((r) => r.row === 1)!.cells, 2).flags & FLAG_CURSOR).toBe(
      FLAG_CURSOR
    )
  })

  it('pushes a BAR overlay, and leaves the cell un-inverted', () => {
    const { core, handle } = make({ rows: 4, cursorY: 1, cursorX: 2, cursorStyle: { style: 'bar' } })
    core.renderRows(0, 3)
    expect(last(handle)).toEqual({
      col: 2,
      row: 1,
      shape: 'bar',
      widthCells: 1,
      color: THEME.cursorBg
    })
    expect(readCell(handle.rows.find((r) => r.row === 1)!.cells, 2).flags & FLAG_CURSOR).toBe(0)
  })

  it('pushes an UNDERLINE overlay for that style', () => {
    const { core, handle } = make({ rows: 4, cursorY: 0, cursorX: 1, cursorStyle: { style: 'underline' } })
    core.renderRows(0, 3)
    expect(last(handle)?.shape).toBe('underline')
  })

  it('a BLURRED terminal gets the hollow outline xterm draws by default', () => {
    // The row this task exists for: `outline` is xterm's default `cursorInactiveStyle`, so this is
    // the DEFAULT path, not an exotic setting. Limitation L2 was that it could not be expressed.
    const { core, handle } = make({ rows: 4, cursorY: 2, cursorX: 3, focus: false })
    core.renderRows(0, 3)
    expect(last(handle)).toEqual({
      col: 3,
      row: 2,
      shape: 'outline',
      widthCells: 1,
      color: THEME.cursorBg
    })
    expect(readCell(handle.rows.find((r) => r.row === 2)!.cells, 3).flags & FLAG_CURSOR).toBe(0)
  })

  it('honours an inactive style of none — nothing on either path', () => {
    const { core, handle } = make({
      rows: 4,
      cursorY: 2,
      cursorX: 3,
      focus: false,
      cursorStyle: { inactiveStyle: 'none' }
    })
    core.renderRows(0, 3)
    expect(last(handle)).toBe(null)
    for (const rec of handle.rows)
      for (let c = 0; c < 4; c++) expect(readCell(rec.cells, c).flags & FLAG_CURSOR).toBe(0)
  })

  it('honours an inactive style of BLOCK through the cell path, not the overlay', () => {
    const { core, handle } = make({
      rows: 4,
      cursorY: 2,
      cursorX: 3,
      focus: false,
      cursorStyle: { inactiveStyle: 'block' }
    })
    core.renderRows(0, 3)
    expect(last(handle)).toBe(null)
    expect(readCell(handle.rows.find((r) => r.row === 2)!.cells, 3).flags & FLAG_CURSOR).toBe(
      FLAG_CURSOR
    )
  })

  it('clears the overlay when the app hides the cursor', () => {
    // DECTCEM inside a TUI. A stale overlay would leave a bar sitting in the middle of vim — and
    // unlike a packed row, nothing else ever erases a grid-level value.
    const { core, term, handle } = make({
      rows: 4,
      cursorY: 1,
      cursorX: 1,
      cursorStyle: { style: 'bar' }
    })
    core.renderRows(0, 3)
    expect(last(handle)?.shape).toBe('bar')
    term.state.cursorVisible = false
    core.renderRows(0, 3)
    expect(last(handle)).toBe(null)
  })

  it('reports widthCells 2 when the cursor sits on a WIDE glyph', () => {
    // The overlay's half of L13: a bar on 日 is still one hairline, but an underline or an outline
    // has to span the whole character — which needs the cell's width, not the cursor's column.
    const { core, handle } = make({
      rows: 4,
      cursorY: 0,
      cursorX: 1,
      wideCols: [1],
      cursorStyle: { style: 'underline' }
    })
    core.renderRows(0, 3)
    expect(last(handle)?.widthCells).toBe(2)
  })

  it('clamps the overlay column exactly as the cell path does (deferred wrap)', () => {
    const { core, handle } = make({ cols: 4, rows: 2, cursorX: 4, cursorY: 0, cursorStyle: { style: 'bar' } })
    core.renderRows(0, 1)
    expect(last(handle)?.col).toBe(3)
  })

  it('clears the overlay when the cursor scrolls out of the viewport', () => {
    // The cursor's row is baseY + cursorY - viewportY; scroll back far enough and it is off the top
    // of the viewport. An overlay is a GRID-level value, so nothing else would erase it — a stale
    // one would draw a cursor over whatever text scrolled into that row.
    const { core, term, handle } = make({
      rows: 4,
      baseY: 100,
      viewportY: 100,
      cursorY: 1,
      cursorStyle: { style: 'bar' }
    })
    core.renderRows(0, 3)
    expect(last(handle)?.row).toBe(1)
    term.state.viewportY = 106
    core.renderRows(0, 3)
    expect(last(handle)).toBe(null)
  })

  it('degrades to a block / outline when the shell reports no cursor options at all', () => {
    // An xterm bump that renames the options must cost the user their chosen SHAPE, never their
    // cursor — so the fallbacks are xterm's own defaults.
    const focused = make({ rows: 4, cursorY: 1, cursorX: 1 })
    focused.core.renderRows(0, 3)
    expect(focused.handle.cursors.at(-1)).toBe(null)
    expect(readCell(focused.handle.rows.find((r) => r.row === 1)!.cells, 1).flags & FLAG_CURSOR).toBe(
      FLAG_CURSOR
    )

    const blurred = make({ rows: 4, cursorY: 1, cursorX: 1, focus: false })
    blurred.core.renderRows(0, 3)
    expect(blurred.handle.cursors.at(-1)?.shape).toBe('outline')
  })

  it('follows blur and focus without waiting for a redraw', () => {
    const { core, handle } = make({ rows: 4, cursorY: 1, cursorX: 1, cursorStyle: { style: 'bar' } })
    core.renderRows(0, 3)
    expect(last(handle)?.shape).toBe('bar')
    core.handleBlur()
    expect(last(handle)?.shape).toBe('outline')
    core.handleFocus()
    expect(last(handle)?.shape).toBe('bar')
  })

  it('repacks the cursor row when a style flip changes BLOCK-ness under a pack that misses it', () => {
    // The two halves run on different schedules: the overlay is re-pushed by EVERY pack, the cell
    // half only by one that covers the cursor row. Flip `cursorInactiveStyle` from block to outline
    // on a BLURRED terminal and then do something that packs other rows — a drag-select — and the
    // outline would be drawn around a cell still holding the inverted block. Self-healing
    // eventually, but checklist 2.12 walks a tester straight into it.
    const style = { style: 'block', inactiveStyle: 'block' }
    const { core, handle } = make({
      rows: 8,
      cols: 4,
      cursorY: 0,
      cursorX: 1,
      focus: false,
      cursorStyle: style
    })
    core.renderRows(0, 7)
    expect(readCell(handle.rows.find((r) => r.row === 0)!.cells, 1).flags & FLAG_CURSOR).toBe(
      FLAG_CURSOR
    )
    handle.rows.length = 0
    style.inactiveStyle = 'outline'
    core.renderRows(4, 5)
    expect(handle.rows.map((r) => r.row)).toContain(0)
    expect(readCell(handle.rows.find((r) => r.row === 0)!.cells, 1).flags & FLAG_CURSOR).toBe(0)
    expect(last(handle)?.shape).toBe('outline')
  })

  it('repacks it the other way too — the overlay goes at once, so the block must arrive at once', () => {
    const style = { style: 'block', inactiveStyle: 'outline' }
    const { core, handle } = make({
      rows: 8,
      cols: 4,
      cursorY: 0,
      cursorX: 1,
      focus: false,
      cursorStyle: style
    })
    core.renderRows(0, 7)
    expect(last(handle)?.shape).toBe('outline')
    handle.rows.length = 0
    style.inactiveStyle = 'block'
    core.renderRows(4, 5)
    expect(last(handle)).toBe(null)
    // Without the repair this terminal would show NO cursor at all until its cursor row happened
    // to be packed by something else.
    expect(readCell(handle.rows.find((r) => r.row === 0)!.cells, 1).flags & FLAG_CURSOR).toBe(
      FLAG_CURSOR
    )
  })

  it('repairs nothing when the pack already covers the cursor row', () => {
    // Both halves of the cost/termination argument: the repair re-enters packRows, so it must fire
    // only when the cursor row is genuinely stale AND is a row a pack can reach.
    const style = { style: 'block', inactiveStyle: 'block' }
    const { core, handle } = make({
      rows: 4,
      cols: 4,
      cursorY: 1,
      cursorX: 1,
      focus: false,
      cursorStyle: style
    })
    core.renderRows(0, 3)
    handle.rows.length = 0
    style.inactiveStyle = 'outline'
    core.renderRows(1, 1) // the cursor row itself — repainted once, not twice
    expect(handle.rows.map((r) => r.row)).toEqual([1])

    handle.rows.length = 0
    style.inactiveStyle = 'block'
    core.renderRows(3, 3) // flips back, and now the cursor row is NOT in range
    expect(handle.rows.map((r) => r.row).sort((a, b) => a - b)).toEqual([1, 3])
  })
})

/** THE BLINK PHASE — the producer half of the canvas's cursor-blink clock.
 *
 *  The clock (`canvas/SharedGlyphLayer.tsx`) owns the timing; the addon is the only thing that can
 *  APPLY a phase, because a block cursor is a CELL rewrite and every other shape is an OVERLAY and
 *  only this class holds both. So every test here asserts BOTH halves: a phase that hid one and not
 *  the other would leave an inverted cell under a cleared overlay, or a bar hanging beside a cursor
 *  that is supposed to be gone. */
describe('GlyphGridRendererAddonCore.setCursorBlinkPhase', () => {
  const lastCursor = (h: ReturnType<typeof recordingHandle>): GridCursor | null | undefined =>
    h.cursors.at(-1)
  /** The cursor flag on the NEWEST pack of a row — the older packs are still in the log, and a
   *  blink is precisely a sequence of packs of the same row. */
  const cursorFlag = (
    h: ReturnType<typeof recordingHandle>,
    row: number,
    col: number
  ): number => {
    const rec = [...h.rows].reverse().find((r) => r.row === row)
    if (!rec) throw new Error(`row ${row} was never packed`)
    return readCell(rec.cells, col).flags & FLAG_CURSOR
  }

  it('hides BOTH halves of a block cursor for the hidden phase, and brings both back', () => {
    const { core, handle } = make({ rows: 4, cols: 4, cursorY: 1, cursorX: 2 })
    core.renderRows(0, 3)
    expect(cursorFlag(handle, 1, 2)).toBe(FLAG_CURSOR)
    // A block never uses the overlay — the cells carry it, which is why the overlay alone could
    // never have implemented this.
    expect(lastCursor(handle)).toBe(null)

    core.setCursorBlinkPhase(false)
    expect(cursorFlag(handle, 1, 2)).toBe(0)
    expect(lastCursor(handle)).toBe(null)

    core.setCursorBlinkPhase(true)
    expect(cursorFlag(handle, 1, 2)).toBe(FLAG_CURSOR)
  })

  it('hides the OVERLAY half too — a bar cursor blinks on the same phase', () => {
    const { core, handle } = make({
      rows: 4,
      cols: 4,
      cursorY: 1,
      cursorX: 2,
      cursorStyle: { style: 'bar' }
    })
    core.renderRows(0, 3)
    expect(lastCursor(handle)?.shape).toBe('bar')

    core.setCursorBlinkPhase(false)
    expect(lastCursor(handle)).toBe(null)
    expect(cursorFlag(handle, 1, 2)).toBe(0)

    core.setCursorBlinkPhase(true)
    expect(lastCursor(handle)?.shape).toBe('bar')
  })

  it('repacks the cursor row SYNCHRONOUSLY, and asks for NO redraw', () => {
    // THE contract. The clock brackets this call to route the damage it produces through the frame
    // loop's one-shot `pulse()`; a repack handed to `onRequestRedraw` (as an atlas reset or a
    // decoration change is) would land outside that bracket, take `wake()`, and re-arm the 30-frame
    // idle streak twice a second.
    const { core, handle } = make({ rows: 4, cols: 4, cursorY: 2, cursorX: 0 })
    const redraws: Array<{ start: number; end: number }> = []
    core.onRequestRedraw((e) => redraws.push(e))
    handle.rows.length = 0

    core.setCursorBlinkPhase(false)

    expect(handle.rows.map((r) => r.row)).toEqual([2])
    expect(redraws).toEqual([])
  })

  it('is change-gated — the same phase twice costs one pack', () => {
    const { core, handle } = make({ rows: 4, cols: 4, cursorY: 2, cursorX: 0 })
    handle.rows.length = 0
    core.setCursorBlinkPhase(false)
    core.setCursorBlinkPhase(false)
    expect(handle.rows.map((r) => r.row)).toEqual([2])
  })

  it('is inert after dispose — a clock tick racing a teardown must not touch the grid', () => {
    const { core, handle } = make({ rows: 4, cols: 4, cursorY: 2, cursorX: 0 })
    core.dispose()
    handle.log.length = 0
    core.setCursorBlinkPhase(false)
    expect(handle.log).toEqual([])
  })

  it('a pack that misses the cursor row during a hidden phase neither repairs nor resurrects it', () => {
    // A hidden phase is the same "no cursor row in this pass" case DECTCEM already produces, so
    // `settleCursorCells` takes neither branch: no repair repack, and certainly no block painted
    // back onto a row the blink just cleared.
    const { core, handle } = make({ rows: 8, cols: 4, cursorY: 0, cursorX: 1 })
    core.renderRows(0, 7)
    core.setCursorBlinkPhase(false)
    handle.rows.length = 0
    core.renderRows(4, 5)
    expect(handle.rows.map((r) => r.row)).toEqual([4, 5])
  })

  it('the block-ness repair still fires once the phase returns', () => {
    // Constraint: hiding the cursor must not corrupt `cellCursorBlock`. Flip block-ness WHILE the
    // cursor is hidden and pack rows that miss it — the bookkeeping the repair reads is stale by
    // construction — then show the cursor again and the row must come back as an outline: cells
    // un-inverted, overlay pushed.
    const style = { style: 'block', inactiveStyle: 'block' }
    const { core, handle } = make({
      rows: 8,
      cols: 4,
      cursorY: 0,
      cursorX: 1,
      focus: false,
      cursorStyle: style
    })
    core.renderRows(0, 7)
    expect(cursorFlag(handle, 0, 1)).toBe(FLAG_CURSOR)

    core.setCursorBlinkPhase(false)
    style.inactiveStyle = 'outline'
    core.renderRows(4, 5)
    handle.rows.length = 0

    core.setCursorBlinkPhase(true)
    expect(handle.rows.map((r) => r.row)).toEqual([0])
    expect(cursorFlag(handle, 0, 1)).toBe(0)
    expect(lastCursor(handle)?.shape).toBe('outline')
  })

  it('a cursor the APP has hidden stays hidden through a shown phase', () => {
    // DECTCEM and the blink are independent reasons not to draw; neither may override the other.
    const { core, handle } = make({
      rows: 4,
      cols: 4,
      cursorY: 1,
      cursorX: 1,
      cursorVisible: false
    })
    core.renderRows(0, 3)
    core.setCursorBlinkPhase(false)
    core.setCursorBlinkPhase(true)
    expect(cursorFlag(handle, 1, 1)).toBe(0)
    expect(lastCursor(handle)).toBe(null)
  })
})

/** WHICH terminal blinks — the focus edge the clock's only gate is built on. */
describe('GlyphGridRendererAddonCore blink target', () => {
  it('claims the blink at construction when the terminal already has focus', () => {
    // A mode switch or a remount attaches to a terminal the user is already typing in; a clock
    // that only learned about focus on the NEXT focus event would leave that cursor static.
    const blink = fakeBlinkSeam()
    const { core } = make({ blink: blink.seam, focus: true })
    expect(blink.target()).not.toBe(null)
    core.dispose()
  })

  it('claims nothing while the terminal is blurred', () => {
    const blink = fakeBlinkSeam()
    make({ blink: blink.seam, focus: false })
    expect(blink.claims).toEqual([])
    expect(blink.target()).toBe(null)
  })

  it('claims on focus, releases on blur, and hands over the SAME object every time', () => {
    // Identity is the contract: the clock is change-gated on it (`next !== current`), so a fresh
    // object per focus event would restart the blink period on every notification.
    const blink = fakeBlinkSeam()
    const { core } = make({ blink: blink.seam, focus: false })
    core.handleFocus()
    const first = blink.target()
    expect(first).not.toBe(null)
    core.handleBlur()
    expect(blink.target()).toBe(null)
    core.handleFocus()
    expect(blink.target()).toBe(first)
  })

  it('a LATE blur cannot steal the blink from the terminal that just took focus', () => {
    // Browsers do not promise the blur of the old terminal reaches us before the focus of the new
    // one. An unconditional clear on blur would stop the cursor of the terminal the user just
    // clicked into — which is the only terminal that is supposed to be blinking.
    const blink = fakeBlinkSeam()
    const a = make({ blink: blink.seam, focus: true })
    const b = make({ blink: blink.seam, focus: false })
    b.core.handleFocus()
    const bTarget = blink.target()
    a.core.handleBlur()
    expect(blink.target()).toBe(bTarget)
  })

  it('releases BEFORE it goes inert, so the clock can hand the cursor back shown', () => {
    // The clock restores the phase from inside its release path. If dispose had already flipped the
    // addon inert, that restore would be a silent no-op and the last packed row would keep the
    // cursor the blink happened to be hiding — an invisible cursor on a node swapped back to the
    // DOM renderer.
    const blink = fakeBlinkSeam({ onRelease: (t) => t.setPhase(true) })
    const { core, handle } = make({ rows: 4, cols: 4, cursorY: 1, cursorX: 2, blink: blink.seam })
    core.renderRows(0, 3)
    core.setCursorBlinkPhase(false)
    handle.rows.length = 0

    core.dispose()

    const rec = [...handle.rows].reverse().find((r) => r.row === 1)
    expect(rec).toBeDefined()
    expect(readCell(rec!.cells, 2).flags & FLAG_CURSOR).toBe(FLAG_CURSOR)
    expect(blink.target()).toBe(null)
  })

  it('restarts the blink on a cursor move — but only while it has focus', () => {
    // xterm's own `restartBlinkAnimation` holds the cursor solid while you type. The FOCUS check is
    // the addon's own: a background terminal streaming output moves its cursor constantly, and the
    // fake below deliberately does NOT guard by identity (the module-level `restartCursorBlink`
    // does that) so this asserts the addon's guard rather than the seam's.
    const blink = fakeBlinkSeam()
    const { core } = make({ rows: 8, cols: 4, cursorY: 1, cursorX: 1, blink: blink.seam })
    core.handleCursorMove()
    expect(blink.restarts.length).toBe(1)

    core.handleBlur()
    core.handleCursorMove()
    expect(blink.restarts.length).toBe(1)

    core.handleFocus()
    core.handleCursorMove()
    expect(blink.restarts.length).toBe(2)
  })

  it('asks for no restart once disposed', () => {
    const blink = fakeBlinkSeam()
    const { core } = make({ rows: 8, cols: 4, cursorY: 1, blink: blink.seam })
    core.dispose()
    core.handleCursorMove()
    expect(blink.restarts).toEqual([])
  })

  it('constructs and packs normally when the shell offers no blink seam at all', () => {
    // The degrade: no shared layer, no clock, no blink — Phase 1b's behaviour, not a broken addon.
    const { core, handle } = make({ rows: 4, cols: 4, cursorY: 1, cursorX: 2 })
    core.renderRows(0, 3)
    core.handleFocus()
    core.handleBlur()
    core.dispose()
    expect(handle.rows.length).toBeGreaterThan(0)
  })
})

// The blink's END-TO-END test — the real addon driven by the real clock — lives in
// `canvas/SharedGlyphLayer.test.ts`, not here: it needs the clock, and the dependency direction is
// canvas → glyphgrid. Importing the layer from a glyphgrid unit test would drag React, zustand and
// three stores into this file's module graph. The fakes the two files share live in
// `addon-fakes.ts` (a plain module, because importing a `.test.ts` collects its suite twice).

/** BLUR AND THE SELECTION — limitation L3.
 *
 *  xterm paints an unfocused terminal's selection in a quieter colour; this engine's theme lanes
 *  carry no inactive colour, so the feed blends toward the plate. The addon's share is the REPAINT:
 *  blur used to repack the cursor row only, which would have left the selection bright until
 *  something else happened to touch those rows. */
describe('GlyphGridRendererAddonCore blur dims the selection', () => {
  /** THEME.selectionBg blended half-way to THEME.bg — see feed.ts's INACTIVE_SELECTION_BLEND. */
  const DIMMED = packColor(0x20, 0x31, 0x49, 0xff)

  it('repacks the selected rows on blur, in the inactive colour', () => {
    const { core, handle } = make({ rows: 8, cols: 4, cursorY: 0 })
    core.handleSelectionChanged([0, 2], [4, 3], false)
    handle.rows.length = 0
    core.handleBlur()
    expect([...new Set(handle.rows.map((r) => r.row))].sort((a, b) => a - b)).toEqual([0, 2, 3])
    const row2 = handle.rows.find((r) => r.row === 2)!
    expect(readCell(row2.cells, 0).bg).toBe(DIMMED)
    expect(readCell(row2.cells, 0).flags & FLAG_SELECTED).toBe(FLAG_SELECTED)
  })

  it('paints the ACTIVE colour back on focus', () => {
    const { core, handle } = make({ rows: 8, cols: 4, cursorY: 0 })
    core.handleSelectionChanged([0, 2], [4, 3], false)
    core.handleBlur()
    handle.rows.length = 0
    core.handleFocus()
    const row2 = handle.rows.find((r) => r.row === 2)!
    expect(readCell(row2.cells, 0).bg).toBe(THEME.selectionBg)
  })

  it('packs a selection made WHILE blurred in the inactive colour', () => {
    const { core, handle } = make({ rows: 8, cols: 4, focus: false })
    core.handleSelectionChanged([0, 2], [4, 3], false)
    const row2 = handle.rows.find((r) => r.row === 2)!
    expect(readCell(row2.cells, 0).bg).toBe(DIMMED)
  })
})

describe('GlyphGridRendererAddonCore redraw requests', () => {
  it('clear() repacks everything and asks xterm for a full redraw', () => {
    const { core, handle } = make({ rows: 5 })
    const seen: Array<{ start: number; end: number }> = []
    core.onRequestRedraw((e) => seen.push(e))
    handle.rows.length = 0
    core.clear()
    expect(handle.rows.map((r) => r.row)).toEqual([0, 1, 2, 3, 4])
    expect(seen).toEqual([{ start: 0, end: 4 }])
  })

  it('a theme change repacks everything and asks for a full redraw', () => {
    const { core, handle } = make({ rows: 3 })
    const seen: Array<{ start: number; end: number }> = []
    core.onRequestRedraw((e) => seen.push(e))
    handle.rows.length = 0
    core.handleThemeChange()
    expect(handle.rows.map((r) => r.row)).toEqual([0, 1, 2])
    expect(seen).toEqual([{ start: 0, end: 2 }])
  })

  it('a disposed redraw subscription stops receiving', () => {
    const { core } = make()
    const seen: number[] = []
    const sub = core.onRequestRedraw(() => seen.push(1))
    core.clear()
    sub.dispose()
    core.clear()
    expect(seen).toHaveLength(1)
  })
})

/** ATLAS RESETS. The atlas clears its whole page when the colour key space fills, which leaves
 *  every already-packed lane pointing at a slot that now holds someone else's glyph. The addon's
 *  job is to get all its rows repacked — and to do it WITHOUT repacking from inside the reset,
 *  which fires synchronously in the middle of a `glyphFor` call during someone's row pack. */
describe('GlyphGridRendererAddonCore atlas resets', () => {
  it('asks for a DEFERRED full redraw instead of repacking on the spot', () => {
    const { core, handle, atlas } = make({ rows: 5 })
    const seen: Array<{ start: number; end: number }> = []
    core.onRequestRedraw((e) => seen.push(e))
    handle.rows.length = 0
    atlas.fireReset()
    // The repack itself is xterm's to schedule: packing here would run inside whatever pack loop
    // the reset interrupted.
    expect(handle.rows).toEqual([])
    expect(seen).toEqual([{ start: 0, end: 4 }])
  })

  it('a reset fired from INSIDE a row pack does not recurse into the pack loop', () => {
    // The real shape of the event: the page fills on some cell's glyphFor, mid-row. Every
    // requested row must still be packed exactly once, and the repack must arrive as a redraw
    // request rather than as a nested pack.
    let fired = false
    const atlas = recordingAtlas({
      onGlyphFor: (fire) => {
        if (fired) return
        fired = true
        fire()
      }
    })
    const { core, handle } = make({ rows: 4, atlas })
    const seen: Array<{ start: number; end: number }> = []
    core.onRequestRedraw((e) => seen.push(e))
    core.renderRows(0, 2)
    expect(handle.rows.map((r) => r.row)).toEqual([0, 1, 2])
    expect(seen).toEqual([{ start: 0, end: 3 }])
  })

  it('unsubscribes from the atlas on dispose — a torn-down terminal owes it no repack', () => {
    const { core, atlas } = make()
    const seen: number[] = []
    core.onRequestRedraw(() => seen.push(1))
    expect(atlas.subCount()).toBe(1)
    core.dispose()
    expect(atlas.subCount()).toBe(0)
    atlas.fireReset()
    expect(seen).toEqual([])
  })
})

/** DECORATIONS. The terminal's decoration service colours cells (a ⌘F hit is one), and it changes
 *  from OUTSIDE the render loop — the search addon registers a decoration per match while nothing
 *  is being packed. The addon's job is to hand the reader through to the feed keyed by the right
 *  row, and to get every row repacked when the set changes. */
describe('GlyphGridRendererAddonCore decorations', () => {
  const DECO_BG = packColor(0xff, 0xc8, 0x00, 0xff)

  it('feeds decorations keyed by the ABSOLUTE buffer row, not the viewport row', () => {
    // Viewport starts at absolute 100, so viewport row 1 is absolute 101 — the row the decoration
    // marker is on. Keyed by the viewport row instead, the highlight would slide with every scroll.
    const deco = fakeDecorations([{ col: 2, row: 101, bg: DECO_BG }])
    const { core, handle } = make({ rows: 4, cols: 4, viewportY: 100, baseY: 100, decorations: deco })
    core.renderRows(0, 3)
    const row1 = handle.rows.find((r) => r.row === 1)!
    expect(readCell(row1.cells, 2).bg).toBe(DECO_BG)
    const row0 = handle.rows.find((r) => r.row === 0)!
    expect(readCell(row0.cells, 2).bg).toBe(THEME.bg)
  })

  it('asks for a DEFERRED full redraw when a decoration is registered or removed', () => {
    // Same mechanism as an atlas reset: a decoration changes cell COLOURS, so every row has to be
    // re-fed — but the pack itself is xterm's to schedule, never a repack from inside this event.
    const deco = fakeDecorations()
    const { core, handle } = make({ rows: 5, decorations: deco })
    const seen: Array<{ start: number; end: number }> = []
    core.onRequestRedraw((e) => seen.push(e))
    handle.rows.length = 0

    deco.fireRegistered()
    expect(handle.rows).toEqual([])
    expect(seen).toEqual([{ start: 0, end: 4 }])

    deco.fireRemoved()
    expect(handle.rows).toEqual([])
    expect(seen).toEqual([
      { start: 0, end: 4 },
      { start: 0, end: 4 }
    ])
  })

  it('unsubscribes from BOTH decoration events on dispose', () => {
    const deco = fakeDecorations()
    const { core } = make({ rows: 3, decorations: deco })
    const seen: number[] = []
    core.onRequestRedraw(() => seen.push(1))
    expect(deco.subCount()).toBe(2)
    core.dispose()
    expect(deco.subCount()).toBe(0)
    deco.fireRegistered()
    deco.fireRemoved()
    expect(seen).toEqual([])
  })

  it('constructs and packs normally when the terminal has no decoration service at all', () => {
    // The degradation contract: an xterm build without `_decorationService` must render, minus the
    // highlights — never refuse the attach.
    const { core, handle } = make({ rows: 2, cols: 2 })
    core.renderRows(0, 1)
    expect(handle.rows.map((r) => r.row)).toEqual([0, 1])
  })
})

describe('GlyphGridRendererAddonCore.dispose', () => {
  it('makes every further call inert — a torn-down terminal must never touch the grid', () => {
    const { core, handle } = make({ rows: 6 })
    const seen: number[] = []
    core.onRequestRedraw(() => seen.push(1))
    core.dispose()
    handle.log.length = 0
    handle.rows.length = 0
    core.renderRows(0, 5)
    core.clear()
    core.handleThemeChange()
    core.handleResize(9, 9)
    core.handleSelectionChanged([0, 0], [2, 2], false)
    core.handleCursorMove()
    core.handleBlur()
    core.handleFocus()
    core.handleCharSizeChanged()
    core.handleDevicePixelRatioChange()
    expect(handle.log).toEqual([])
    expect(handle.rows).toEqual([])
    expect(seen).toEqual([])
  })

  it('does NOT dispose the grid handle — the node that registered it owns its lifetime', () => {
    const { core, handle } = make()
    core.dispose()
    expect(handle.log).not.toContain('dispose')
  })
})