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.

41.3 KB
Raw Blame
/** The xterm-facing brain of the glyphgrid renderer: xterm's renderer callbacks in, packed grid
 *  rows out.
 *
 *  Like the rest of this directory it imports NOTHING from xterm. Everything the terminal knows
 *  arrives through `TermInternals`, a hand-written narrowing of the handful of xterm internals we
 *  read, built by `src/renderer/terminal/glyphgrid-attach.ts`. That split is the point: xterm's
 *  private surface is the part of that library most likely to move under us, and keeping it behind
 *  one injected interface means a bump breaks ONE thin shell instead of the renderer, and lets the
 *  whole render path be unit-tested without a DOM, a canvas or a terminal. */

import type { GlyphAtlas, GlyphAtlasSubscription } from './atlas'
import { CELL_STRIDE } from './cells'
import { resolveCursorShape, type CursorShape, type GridCursor } from './cursor'
import type { DecorationReader } from './decorations'
import type { GridHandle } from './engine'
import { packViewportRow, type CellView, type ThemeLanes } from './feed'

/** Cell/char metrics in DEVICE pixels, already carrying xterm's own rounding (charSize × dpr,
 *  ceil on char height, letterSpacing, lineHeight). The shell computes them exactly the way
 *  xterm's own renderers do, because `dimensions.css.cell` derived from them is what xterm maps
 *  MOUSE COORDINATES through — a rounding that differs by a fraction of a pixel per row puts the
 *  selection on the wrong line at the bottom of a tall terminal. */
export interface DeviceMetrics {
  charW: number
  charH: number
  cellW: number
  cellH: number
}

/** This terminal's end of the canvas cursor-blink clock: the clock hands the focused terminal its
 *  phase through here. Declared structurally rather than imported from the shared layer — this
 *  directory imports nothing — and it is the same shape as the layer's `CursorBlinkTarget`. */
export interface CursorBlinkPhaseTarget {
  setPhase(visible: boolean): void
}

/**
 * How the addon publishes WHICH terminal the canvas's single blink clock should be driving.
 *
 * The addon is the only thing that can answer it: it tracks focus itself (see `focused`), and a
 * focused block cursor produces no overlay at all, so focus is invisible from the engine side.
 *
 * OPTIONAL, like the decorations: a build with no shared layer hands over nothing and the cursor
 * simply never blinks — Phase 1b's behaviour, not a broken renderer.
 *
 * `release(target)` rather than a bare `setTarget(null)`, and it is IDENTITY-GUARDED by the shell:
 * browsers do not promise that the blurred terminal's blur reaches us before the newly focused
 * one's focus, and an unconditional clear on a late blur would stop the cursor of the terminal the
 * user just clicked into — the only one that is supposed to be blinking.
 */
export interface CursorBlinkSeam {
  claim(target: CursorBlinkPhaseTarget): void
  release(target: CursorBlinkPhaseTarget): void
  /** The cursor MOVED: hold it solid and start the period over, exactly as xterm's own
   *  `CursorBlinkStateManager.restartBlinkAnimation` does. Identity-guarded in the shell like
   *  `release`, and for a second reason on top of that one — a background terminal streaming output
   *  moves its cursor constantly, and any of them re-arming the focused terminal's period would
   *  hold the blink permanently solid. */
  restart(target: CursorBlinkPhaseTarget): void
}

/** What the addon needs from a live terminal. Kept minimal so the addon is testable with fakes and
 *  survives xterm minor bumps. */
export interface TermInternals {
  cols(): number
  rows(): number
  /** buffer.ydisp — the absolute row the viewport's top line shows. */
  viewportY(): number
  /** buffer.ybase — the absolute row the cursor's row index is relative to. */
  baseY(): number
  cursorX(): number
  /** base-relative (buffer.y); viewport row = baseY + cursorY - viewportY */
  cursorY(): number
  /** xterm's `isCursorInitialized && !isCursorHidden`. A TUI that hides the cursor (DECTCEM)
   *  must not leave a phantom block sitting in the middle of the screen. */
  cursorVisible(): boolean
  readCell(absoluteRow: number, col: number, into: CellView): CellView | undefined
  makeWorkCell(): CellView
  deviceMetrics(): DeviceMetrics
  dpr(): number
  theme(): ThemeLanes
  /** Read ONCE, at construction — see `focused`. */
  hasFocus(): boolean
  /** xterm's `options.cursorStyle` and `options.cursorInactiveStyle`, verbatim strings.
   *
   *  OPTIONAL, and read on every pack rather than cached: the user can change either from Settings
   *  at any moment, and the option object is the shell's live view of the terminal. A build that
   *  reports neither degrades to xterm's own defaults (a focused block, a blurred outline) —
   *  a bumped xterm must cost the user their chosen SHAPE, never their cursor.
   *
   *  The FOCUS half is deliberately not read from here: this addon tracks focus itself (see
   *  `focused`), because whether the browser service's flag has flipped by the time xterm calls
   *  handleBlur is an ordering detail the cursor's correctness must not rest on. */
  cursorStyle?(): { style?: string; inactiveStyle?: string }
  /** The canvas's blink clock, or undefined on a build that has none. See `CursorBlinkSeam`. */
  blink?: CursorBlinkSeam
  /** The terminal's decorations — the cell colours a ⌘F hit paints — or undefined.
   *
   *  ALL THREE DECORATION MEMBERS ARE OPTIONAL, together: an xterm build whose decoration service
   *  is missing or reshaped must degrade to "this terminal has no highlights", never to a refused
   *  attach or a terminal on no renderer at all. The shell decides that once and hands over either
   *  the whole trio or none of it. */
  decorations?: DecorationReader
  onDecorationRegistered?(cb: () => void): { dispose(): void }
  onDecorationRemoved?(cb: () => void): { dispose(): void }
  /**
   * The link the pointer is currently over, in VIEWPORT cell coordinates, or null.
   *
   * xterm reports a hovered link as a range and its own render layers answer by underlining it —
   * the affordance that says ⌘-click will open this. Replacing xterm's renderer removes those
   * layers, so this renderer has to draw it, or every link looks inert (reported 2026-08-05).
   *
   * OPTIONAL like the decorations, and for the same reason: a build whose linkifier is missing or
   * reshaped degrades to "no link underlines", never to a refused attach.
   */
  linkUnderline?: LinkUnderline
}

/**
 * A hovered link's extent, in VIEWPORT cell coordinates — the shape xterm's linkifier fires
 * (`y` already has `ydisp` subtracted). Inclusive on both ends, as xterm reports it.
 */
export interface LinkUnderline {
  /** The current range, or null when nothing is hovered. Read once per pack. */
  current(): { x1: number; y1: number; x2: number; y2: number } | null
  /** Fires when the hovered range changes, so the shell can repaint the rows it covers. */
  onChange(cb: () => void): { dispose(): void }
}

/** The exact shape of xterm's `IRenderer.dimensions`. RenderService reads it straight off the
 *  renderer object (`get dimensions()`), so it must exist from the first tick after setRenderer. */
export interface RendererDims {
  css: { canvas: { width: number; height: number }; cell: { width: number; height: number } }
  device: {
    canvas: { width: number; height: number }
    cell: { width: number; height: number }
    char: { width: number; height: number; left: number; top: number }
  }
}

type SelPoint = readonly [number, number]

/** Inclusive viewport-row range, or null for "nothing to do". */
type RowRange = readonly [number, number] | null

/** Order two absolute buffer points. xterm's selection service already hands them over ordered,
 *  but a renderer that assumed so and was wrong would silently draw NOTHING (every row would fall
 *  outside the range) — a cheap comparison buys immunity. */
function orderPoints(a: SelPoint, b: SelPoint): [SelPoint, SelPoint] {
  if (a[1] > b[1] || (a[1] === b[1] && a[0] > b[0])) return [b, a]
  return [a, b]
}

export class GlyphGridRendererAddonCore {
  /** Allocated ONCE and mutated in place on resize / char-size / dpr change — never reassigned.
   *
   *  xterm's `Viewport` caches this object BY REFERENCE (it keeps whatever `onDimensionsChange`
   *  handed it) and re-reads only on the next dimensions event — which fires BEFORE our
   *  `handleResize` runs, since RenderService registered its own listeners first. Hand out a FRESH
   *  object and the Viewport goes on computing row height and scroll-area geometry from the
   *  previous font size, with its `syncScrollArea` guard comparing stale to stale so it never
   *  notices. Identity is the contract here, not an optimization. */
  readonly dimensions: RendererDims = {
    css: { canvas: { width: 0, height: 0 }, cell: { width: 0, height: 0 } },
    device: {
      canvas: { width: 0, height: 0 },
      cell: { width: 0, height: 0 },
      char: { width: 0, height: 0, left: 0, top: 0 }
    }
  }

  private cols: number
  private rows: number
  private disposed = false
  /** ONE row buffer for every row of every frame — `GridHandle.updateRow` copies, so reusing it is
   *  safe, and packing a 200-row canvas of terminals must not allocate. Replaced only when the
   *  column count changes (the engine rejects a row of the wrong length). */
  private rowBuf: Uint32Array
  private readonly workCell: CellView
  private readonly redrawListeners = new Set<(e: { start: number; end: number }) => void>()

  /** Absolute buffer selection, normalized so `selTop` is never after `selBottom`. */
  private selTop: SelPoint | undefined
  private selBottom: SelPoint | undefined
  private columnSelect = false

  /** Focus is OURS to track, not a live read of the terminal: xterm calls handleBlur/handleFocus
   *  from its own focus events, and whether the browser-service flag has already flipped by then
   *  is an ordering detail we would be betting the cursor's correctness on. Seeded once. */
  private focused: boolean
  /** Viewport row the cursor was on at the last cursor-move — the row a move has to REPAINT to
   *  erase the old block. Geometric (not focus-gated), so blur/focus and moves stay independent. */
  private lastCursorRow: number
  /**
   * Whether the CELLS currently hold an inverted block cursor — i.e. the block-ness of the last pack
   * that actually covered the cursor row.
   *
   * The two halves of the cursor are updated on different schedules: the OVERLAY is re-pushed by
   * every pack (it is a property of the terminal, not of the rows), while the CELL half only changes
   * on a pack that covers the cursor row. A style change that flips block-ness between those two —
   * `cursorInactiveStyle` going `block` → `outline` while the terminal is blurred, then a
   * drag-select, which packs only the selected rows — would leave an outline drawn AROUND a cell
   * that is still inverted, or (the other direction) clear the overlay and leave no cursor at all.
   * Remembering what the cells show is what lets `packRows` notice and repaint the cursor row.
   *
   * Kept HERE rather than closing the same gap by subscribing to xterm's
   * `onSpecificOptionChange('cursorInactiveStyle')` through the shell: that would widen the shell's
   * private-xterm surface (the thing this whole split exists to keep small) for a setting nobody
   * touches at runtime, and it would only cover the option — this covers every way the two halves
   * can drift apart, including a focus change racing a pack.
   */
  private cellCursorBlock: boolean

  /**
   * Whether the canvas's blink clock currently wants this terminal's cursor SHOWN.
   *
   * A third reason a cursor may not be drawn this instant, independent of focus and of the app's
   * own DECTCEM state — see `cursorShown`, which is the single place the three meet. True whenever
   * no clock is driving this terminal, so every terminal that is not the blink target (and every
   * terminal at all, on a build with no shared layer) draws exactly as it did before.
   */
  private blinkVisible = true

  /** ONE object for the addon's lifetime, handed to the clock on every focus edge. Identity is the
   *  contract, not an optimization: the clock is change-gated on it (`next !== current`, and
   *  `setCursorBlinkTarget` compares by reference), so a fresh object per focus event would restart
   *  the blink period every time a focus notification arrived. */
  private readonly blinkSelf: CursorBlinkPhaseTarget = {
    setPhase: (visible: boolean): void => this.setCursorBlinkPhase(visible)
  }

  /** Mutable because `readCellBound` closes over it: one closure for the lifetime of the addon
   *  instead of one per packed row. */
  private absRow = 0
  private readonly readCellBound = (col: number, into: CellView): CellView | undefined =>
    this.internals.readCell(this.absRow, col, into)

  /** Live for the addon's whole life; disposed in `dispose()`. The atlas is SHARED by every
   *  terminal on the canvas, so a subscription left behind holds a torn-down addon alive and asks
   *  it to repack rows into a grid its node has already dropped. */
  private readonly atlasResetSub: GlyphAtlasSubscription

  /** The terminal's decoration events, empty when it has no decoration service. Disposed with the
   *  addon for the same reason the atlas subscription is: a live subscription on a terminal that
   *  outlives its renderer (an attach that was swapped back to DOM) would go on asking a dead addon
   *  to redraw a grid its node has dropped. */
  private readonly decorationSubs: Array<{ dispose(): void }> = []

  constructor(
    private readonly internals: TermInternals,
    private readonly handle: GridHandle,
    private readonly atlas: Pick<GlyphAtlas, 'glyphFor' | 'onReset'>
  ) {
    this.cols = internals.cols()
    this.rows = internals.rows()
    this.rowBuf = new Uint32Array(Math.max(0, this.cols) * CELL_STRIDE)
    this.workCell = internals.makeWorkCell()
    this.focused = internals.hasFocus()
    this.lastCursorRow = this.cursorViewportRow()
    // Seeded from the CURRENT shape rather than from `false`: no row has been packed yet, so there
    // is no stale block to heal, and seeding the other way would spend one repack of the cursor row
    // on the first pack of every terminal that misses it.
    this.cellCursorBlock = this.cursorShape() === 'block'
    this.updateDims()
    // EVERY subscription goes last, and they go TOGETHER. The shell catches a failing construction
    // and restores the DOM renderer without ever holding an addon to dispose, so anything
    // subscribed before a throw is disposed by nobody and keeps the dead addon reachable from the
    // object it subscribed to. That is the whole invariant, and it does not care which of these is
    // likelier to throw — splitting them to put the "riskier" pair first only widens the window it
    // exists to close.
    this.atlasResetSub = this.atlas.onReset(() => this.handleAtlasReset())
    const onRegistered = internals.onDecorationRegistered
    const onRemoved = internals.onDecorationRemoved
    if (onRegistered) this.decorationSubs.push(onRegistered(() => this.handleDecorationChange()))
    if (onRemoved) this.decorationSubs.push(onRemoved(() => this.handleDecorationChange()))
    // The hovered link changes with the POINTER, not with the buffer, so nothing else would ever
    // repaint those rows: without this the underline appears only when some unrelated output
    // happens to redraw the line under the cursor. Shares the decoration bag — same lifetime, same
    // teardown, and one fewer thing for `dispose` to remember.
    const onLink = internals.linkUnderline?.onChange
    if (onLink) {
      this.decorationSubs.push(
        internals.linkUnderline!.onChange(() => this.handleDecorationChange())
      )
    }
    // LAST, and after the subscriptions, for the same reason they go last: this publishes the addon
    // into a CANVAS-LEVEL singleton, and a construction that threw afterwards would leave it there
    // with nobody holding an addon to release it. Seeded rather than waited for, because 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.
    this.publishBlinkTarget()
  }

  // ---------------------------------------------------------------- xterm renderer surface
  //
  // Every member RenderService calls, and nothing else. The one deliberate omission is the
  // OPTIONAL `clearTextureAtlas`: the atlas is SHARED by every terminal on the canvas, so one
  // terminal must not be able to wipe it — a font change tears the whole shared context down and
  // re-registers each node instead. RenderService calls it as `?.()`, so leaving it off is the
  // supported way to decline.

  renderRows(start: number, end: number): void {
    this.packRows(start, end)
  }

  /** xterm calls this when the active buffer switches (alt screen in/out). The grid's rows are
   *  simply repacked from whatever buffer is now active; the redraw request is what gets the
   *  ranges xterm considers dirty replayed on top. */
  clear(): void {
    this.repackAll()
  }

  handleResize(cols: number, rows: number): void {
    if (this.disposed) return
    this.cols = cols
    this.rows = rows
    if (this.rowBuf.length !== cols * CELL_STRIDE) this.rowBuf = new Uint32Array(cols * CELL_STRIDE)
    // The grid must be the new size BEFORE the first row of the new frame reaches it — an
    // updateRow of the new width against the old grid is rejected outright.
    this.handle.resize(cols, rows)
    this.updateDims()
    this.packRows(0, rows - 1)
  }

  /** Cell metrics changed (font size, letter spacing). Only the DIMENSIONS are ours to fix: the
   *  grid's own cell size is fixed at registration and a change tears the shared context down and
   *  re-registers every node (see the shared layer), so there is nothing to repack here. */
  handleCharSizeChanged(): void {
    if (this.disposed) return
    this.updateDims()
  }

  handleDevicePixelRatioChange(): void {
    if (this.disposed) return
    this.updateDims()
  }

  /** Absolute buffer coords, straight from xterm's selection service.
   *
   *  Only the rows the selection ENTERED or LEFT are repacked — the union of the old and the new
   *  span. xterm's own DOM renderer repaints all `rows` here, which on this canvas would mean
   *  repacking every row of every terminal on every drag tick. */
  handleSelectionChanged(
    start: SelPoint | undefined,
    end: SelPoint | undefined,
    columnSelectMode: boolean
  ): void {
    if (this.disposed) return
    const before = this.selectionRowRange()
    if (start && end) {
      const [top, bottom] = orderPoints(start, end)
      this.selTop = top
      this.selBottom = bottom
    } else {
      this.selTop = undefined
      this.selBottom = undefined
    }
    this.columnSelect = columnSelectMode
    const after = this.selectionRowRange()
    for (const [from, to] of mergeRanges(before, after)) this.packRows(from, to)
  }

  handleCursorMove(): void {
    if (this.disposed) return
    // FIRST, before the packs, and only for the terminal that HAS focus. xterm's own cursor holds
    // solid while you type (`CursorBlinkStateManager.restartBlinkAnimation`), and a STACKED terminal
    // beside this one is drawing exactly that on xterm's DOM renderer — a shared cursor that kept
    // flashing through a keystroke is the drift `CURSOR_BLINK_INTERVAL_MS` was matched to prevent.
    //
    // Its position in this method is what keeps the restart's repaint inside the clock's bracket:
    // the clock shows the cursor synchronously from here, so that repaint takes `pulse()`. The two
    // packs below are ordinary damage — but the engine notifies only on the clean→dirty EDGE, so
    // whichever write lands first is the one that routes, and a keystroke therefore costs a pulse
    // rather than a wake. That is fine and deliberate: either route reaches a FRAME, which is the
    // invariant, and the bracket exists to keep the blink's TIMED repaints off the wake path — not
    // to make sure typing takes it.
    if (this.focused) this.internals.blink?.restart(this.blinkSelf)
    const next = this.cursorViewportRow()
    const prev = this.lastCursorRow
    this.lastCursorRow = next
    this.packRows(next, next)
    if (prev !== next) this.packRows(prev, prev)
  }

  handleBlur(): void {
    if (this.disposed) return
    this.focused = false
    this.repaintFocusDependent()
    // AFTER the repaint: releasing makes the clock restore this cursor to its shown phase, and it
    // must restore the blurred SHAPE, which `repaintFocusDependent` has just established.
    this.publishBlinkTarget()
  }

  handleFocus(): void {
    if (this.disposed) return
    this.focused = true
    this.repaintFocusDependent()
    this.publishBlinkTarget()
  }

  /**
   * The canvas blink clock's phase for THIS terminal — show or hide its cursor for the half-period.
   *
   * SYNCHRONOUS, and that is the contract rather than an implementation detail. The clock brackets
   * this call so the damage it produces is routed to the frame loop's one-shot `pulse()` instead of
   * `wake()` (see `CursorBlinkTarget` in `canvas/SharedGlyphLayer.tsx`): a repack deferred to a
   * redraw request — the way an atlas reset and a decoration change defer theirs — would land
   * OUTSIDE that bracket, take the wake path, and re-arm the 30-frame idle streak twice a second.
   * That is Phase 1c's idle park silently undone on every canvas with a focused terminal, i.e. the
   * exact failure the clock exists to prevent. So the row is packed here, on the caller's stack;
   * this must never become an `emitRedraw`.
   *
   * BOTH halves go together, which is why only the addon can apply a phase: `packRows` re-pushes
   * the overlay (`syncCursor`) before it packs, and `cursorShown()` gates the cell half in the same
   * breath — so a block's cell inversion and every other shape's overlay disappear on one phase.
   */
  setCursorBlinkPhase(visible: boolean): void {
    if (this.disposed || this.blinkVisible === visible) return
    this.blinkVisible = visible
    this.packCursorRow()
  }

  /** Not part of xterm's renderer surface — the shell calls it from `_themeService.onChangeColors`.
   *  Every packed lane is a resolved color, so a theme change invalidates the whole grid. */
  handleThemeChange(): void {
    this.repackAll()
  }

  onRequestRedraw(cb: (e: { start: number; end: number }) => void): { dispose(): void } {
    this.redrawListeners.add(cb)
    return {
      dispose: (): void => {
        this.redrawListeners.delete(cb)
      }
    }
  }

  /** Called by xterm when the renderer is replaced (RenderService holds it in a MutableDisposable),
   *  and by the shell's own teardown. Everything after this is a silent no-op: a terminal being
   *  torn down mid-frame is a teardown race, not a bug, and it must never write into a grid whose
   *  owner has already dropped it.
   *
   *  The grid HANDLE is deliberately not disposed — the node that registered it owns its lifetime
   *  (it outlives a renderer swap back to DOM). */
  dispose(): void {
    // BEFORE `disposed`, deliberately: the clock restores the phase from inside its release path,
    // and an addon already flipped inert would swallow that `setPhase(true)` — leaving the last
    // packed row without the cursor the blink happened to be hiding. Identity-guarded in the shell,
    // so a terminal torn down after another has taken focus cannot stop the new one's blink.
    this.releaseBlinkTarget()
    this.disposed = true
    // The overlay cursor is a GRID-level value, so — unlike a packed row — nothing will ever
    // overwrite it. A renderer swapped back to xterm's DOM one would otherwise leave a bar or an
    // outline painted on the shared canvas under a terminal now drawing its own. A silent no-op when
    // the owner has already dropped the handle, which is the ordinary teardown order.
    this.handle.setCursor(null)
    this.redrawListeners.clear()
    this.atlasResetSub.dispose()
    for (const sub of this.decorationSubs) sub.dispose()
    this.decorationSubs.length = 0
  }

  // ---------------------------------------------------------------- internals

  /**
   * The shared atlas cleared its page (its colour key space filled), so EVERY lane this addon has
   * ever packed now names a slot holding some other cell's glyph. All rows have to be repacked.
   *
   * DEFERRED, NOT IMMEDIATE, and that is the whole design of this method. A reset fires
   * synchronously from inside a `glyphFor` call — i.e. from the middle of a `packRows` loop, ours
   * or another terminal's. Repacking here would re-enter that loop, and the atlas's own guard would
   * then hand the re-entrant requests the BLANK slot to stop it recursing, so the repack would
   * produce exactly the empty cells it exists to prevent. Instead we ask xterm for a full redraw
   * through the same `onRequestRedraw` mechanism `clear()` and a theme change use: RenderService
   * marks the rows dirty and packs them from its own debounced render pass, outside anybody's loop.
   *
   * WHY THE ENGINE'S UPLOAD ORDERING SURVIVES THIS. The engine uploads the atlas before it uploads
   * rows and both before it draws, and a reset preserves that: it marks the atlas dirty, so the
   * next frame re-uploads the cleared-and-refilled page BEFORE any row of it is drawn. Within that
   * frame, the row whose pack triggered the reset carries fresh slots (its remaining cells
   * allocated into the new page); OTHER rows may still name slots that meant something else in the
   * old page, and they are repainted one frame late — the frame this redraw request schedules. A
   * single frame of possibly-stale glyphs on rows nobody has touched, self-healing, is the accepted
   * cost of resets being rare; the alternative is a synchronous repack inside a pack loop, which is
   * a correctness problem rather than a cosmetic one.
   *
   * AND WHY A TERMINAL THAT IS OFF-SCREEN AT RESET TIME STILL HEALS — the mechanism the correctness
   * above quietly rests on. A redraw request for a grid nobody can see does not evaporate at either
   * end: xterm's RenderService answers `refreshRows` on a PAUSED terminal (its intersection observer
   * saw it leave the viewport) by setting `_needsFullRefresh` and flushing that full refresh the
   * moment the terminal intersects again, and the engine's damage is likewise visibility-scoped
   * rather than visibility-dropped — the repacked rows are uploaded on the frame that brings the
   * grid back. Note the timing, because it widens the "one frame" above: the observer lifts the
   * pause ASYNCHRONOUSLY and the refresh it schedules is debounced, so a grid panned back into view
   * right after a reset can show stale glyphs for a FEW frames, not exactly one.
   *
   * Bounded by nothing here on purpose: a page too small for the canvas would reset again on the
   * repack, request another redraw, and settle into a repaint per frame. That is the LRU escalation
   * Phase 2 names, and it needs to be VISIBLE (the atlas logs `resetCount`) rather than smoothed
   * over by a rate limit in the one place that knows the rows are wrong.
   */
  private handleAtlasReset(): void {
    if (this.disposed || this.rows <= 0) return
    this.emitRedraw(0, this.rows - 1)
  }

  /**
   * A decoration was registered or removed — a ⌘F search adding a hit, or the find bar closing and
   * dropping all of them. Decorations change cell COLOURS, so the rows have to be re-fed; the ATLAS
   * is untouched (its slots are keyed by colour, and the ones this asks for next are simply
   * different keys), so nothing needs clearing.
   *
   * DEFERRED, through the same `onRequestRedraw` path an atlas reset uses, and for the same reason:
   * this fires from wherever the decoration owner happens to be — the search addon's own loop, a
   * dispose, a marker being trimmed out of the buffer — and packing rows from inside someone else's
   * call is exactly the re-entrancy `handleAtlasReset` documents at length. Handing the repack to
   * RenderService also coalesces the burst a search produces (one event per match) into a single
   * debounced render pass, instead of repacking every row per hit.
   */
  private handleDecorationChange(): void {
    if (this.disposed || this.rows <= 0) return
    this.emitRedraw(0, this.rows - 1)
  }

  private repackAll(): void {
    if (this.disposed) return
    this.packRows(0, this.rows - 1)
    this.emitRedraw(0, this.rows - 1)
  }

  private packCursorRow(): void {
    const row = this.cursorViewportRow()
    this.packRows(row, row)
  }

  /** Everything a focus change repaints. The cursor row, because its shape changes (a focused block
   *  becomes a blurred outline), AND the selected rows, because an unfocused terminal's selection is
   *  painted in a quieter colour (limitation L3). Repacking only the cursor row — which is what this
   *  used to do — left the selection band bright until something unrelated happened to touch it. */
  private repaintFocusDependent(): void {
    this.packCursorRow()
    const sel = this.selectionRowRange()
    if (sel) this.packRows(sel[0], sel[1])
  }

  /** Tell the canvas's blink clock whether this terminal is the one to blink. Called on every focus
   *  edge and once at construction; `dispose` uses `releaseBlinkTarget` directly, because by then
   *  the answer is "nobody" whatever the focus flag says. */
  private publishBlinkTarget(): void {
    if (this.focused) this.internals.blink?.claim(this.blinkSelf)
    else this.releaseBlinkTarget()
  }

  private releaseBlinkTarget(): void {
    this.internals.blink?.release(this.blinkSelf)
  }

  /**
   * Is the cursor drawn at all right now?
   *
   * Two independent reasons it may not be — the app's own DECTCEM state (a TUI hiding it) and the
   * blink clock's phase — and every path that draws EITHER half asks this one question, which is
   * what keeps the cell half and the overlay half from ever disagreeing about a phase. Focus is
   * deliberately not in here: a blurred terminal still has a cursor, it just wears a different
   * shape (see `cursorShape`).
   */
  private cursorShown(): boolean {
    return this.blinkVisible && this.internals.cursorVisible()
  }

  /** The shape the cursor takes right now, from the shell's options and OUR focus flag. */
  private cursorShape(): CursorShape {
    const opts = this.internals.cursorStyle?.()
    return resolveCursorShape(this.focused, opts?.style, opts?.inactiveStyle)
  }

  /**
   * The overlay cursor this grid should draw, or null.
   *
   * Null for a BLOCK as well as for `none`: a block is a cell rewrite (only that path can invert the
   * glyph under it), and drawing it here too would paint an opaque quad over the inversion the feed
   * just produced. Null for a cursor that is not shown right now (`cursorShown` — DECTCEM inside a
   * TUI, or the blink's hidden phase) and for one scrolled out of the viewport, both for the same
   * reason: the overlay is a GRID-level value, so nothing else would ever erase a stale one —
   * unlike a packed row, which the next frame rewrites wholesale.
   */
  private cursorSpec(): GridCursor | null {
    const shape = this.cursorShape()
    if (shape === 'block' || shape === 'none') return null
    if (!this.cursorShown()) return null
    if (this.cols <= 0 || this.rows <= 0) return null
    const row = this.cursorViewportRow()
    if (row < 0 || row >= this.rows) return null
    // Clamped exactly as the cell path clamps it: with a deferred wrap pending the buffer's x sits
    // ON `cols`, and an overlay drawn there would hang off the right edge of the terminal.
    const col = Math.min(this.internals.cursorX(), this.cols - 1)
    const cell = this.internals.readCell(
      this.internals.baseY() + this.internals.cursorY(),
      col,
      this.workCell
    )
    return {
      col,
      row,
      shape,
      // A wide glyph's lead: the cursor covers the whole character, not its left half (L13). Read
      // from the CELL, since the cursor's column says nothing about how wide what it sits on is.
      widthCells: cell && cell.getWidth() === 2 ? 2 : 1,
      color: this.internals.theme().cursorBg
    }
  }

  /** Push the current overlay cursor at the grid. Cheap and idempotent — the engine change-gates it
   *  — which is what lets every pack path call it without reasoning about whether it moved. */
  private syncCursor(): void {
    this.handle.setCursor(this.cursorSpec())
  }

  /** The single funnel: every path that changes what a row should look like ends here.
   *
   *  Reads viewport/theme/cursor ONCE for the whole range — they cannot change mid-loop, and
   *  `theme()` in particular hands back the shell's cached snapshot, which there is no reason to
   *  re-read per row. */
  private packRows(from: number, to: number): void {
    if (this.disposed) return
    // FIRST, and independent of the range: the overlay cursor is a property of the terminal, not of
    // the rows this pass happens to touch, and every path that repacks anything is also a path
    // along which the cursor may have moved, changed shape or gone away.
    this.syncCursor()
    const start = Math.max(0, from)
    const end = Math.min(this.rows - 1, to)
    if (end < start || this.cols <= 0) return
    const theme = this.internals.theme()
    const viewportY = this.internals.viewportY()
    // -1 = no cursor row in this pass — the app hid it (DECTCEM inside a TUI) or the blink clock is
    // in its hidden phase. The two share this branch on purpose: `settleCursorCells` already knows
    // that a cursor row of -1 means "there is no block to keep in step with", so a phase costs no
    // repair repack and can never paint a block back onto the row it just cleared. NOT focus-gated:
    // a blurred terminal still has a cursor, it just wears a different shape, and which of the two
    // paths draws it is `cursorShape`'s answer below — not this row's.
    const cursorRow = this.cursorShown()
      ? this.internals.baseY() + this.internals.cursorY() - viewportY
      : -1
    // Resolved ONCE for the range: only a `block` is a cell rewrite, and the feed ignores
    // `cursorCol` for every other shape (the overlay pass draws those — see `cursorSpec`).
    const cursorShape = this.cursorShape()
    // CLAMPED, exactly as xterm's own renderers do (`Math.min(buffer.x, cols - 1)`): with a
    // deferred wrap pending, the buffer's x sits ON `cols`, one past the last column. Left
    // unclamped it matches no column and the cursor simply VANISHES at the end of a full line —
    // which is where a shell prompt spends much of its time.
    const cursorCol = Math.min(this.internals.cursorX(), this.cols - 1)
    // Read once for the whole range, like the theme: the shell builds the reader once and keeps it
    // live for the terminal's lifetime.
    const decorations = this.internals.decorations
    for (let row = start; row <= end; row++) {
      this.absRow = viewportY + row
      packViewportRow(this.rowBuf, this.readCellBound, this.workCell, {
        cols: this.cols,
        atlas: this.atlas,
        theme,
        selection: this.selectionOnRow(this.absRow),
        // VIEWPORT row, not the absolute one: xterm's linkifier already subtracted `ydisp` when it
        // fired, so the range is in the coordinates the user is currently looking at.
        linkUnderline: this.linkOnRow(row),
        cursorCol: row === cursorRow ? cursorCol : -1,
        cursorShape,
        // Only the SELECTION colour depends on this (an unfocused terminal's band is quieter — L3);
        // the blurred cursor is a shape, and shapes are the overlay's business.
        focused: this.focused,
        decorations,
        // Decoration markers are keyed by ABSOLUTE buffer row, so this is the row the lookup needs
        // — the viewport row would slide the highlights off their matches on every scroll.
        bufferRow: this.absRow
      })
      this.handle.updateRow(row, this.rowBuf)
    }
    this.settleCursorCells(cursorRow, cursorShape === 'block', start, end)
  }

  /**
   * Keep the CELL half of the cursor in step with the OVERLAY half across packs.
   *
   * Runs after the loop, so the ordinary case is a bookkeeping write: a pack that covered the cursor
   * row has just repainted it, and what it painted is now what the cells show. The other branch is
   * the repair — the cursor row was NOT in this range and its block-ness has changed since it was
   * last packed, which is the `cursorInactiveStyle` flip described on `cellCursorBlock`. Left alone
   * it shows as an outline drawn around a still-inverted cell, or as no cursor at all.
   *
   * TERMINATION, because this re-enters `packRows`: the repack it asks for covers the cursor row by
   * construction, so the nested call takes the first branch and cannot ask again. A cursor row
   * outside the grid (scrolled away, hidden by the app) takes neither branch — there is no stale
   * block to heal there, and asking for a row the pack would clamp away is what a loop would be
   * made of.
   */
  private settleCursorCells(cursorRow: number, block: boolean, start: number, end: number): void {
    if (cursorRow < 0 || cursorRow >= this.rows) return
    if (cursorRow >= start && cursorRow <= end) {
      this.cellCursorBlock = block
      return
    }
    if (this.cellCursorBlock === block) return
    this.packCursorRow()
  }

  /** Column span [start, endExclusive) of the selection on one ABSOLUTE buffer row, or null.
   *
   *  Mirrors xterm's own selection render model exactly (DomRenderer.handleSelectionChanged):
   *  in column-select mode every row in range gets the same [min, max) rectangle; linearly, the
   *  first row starts at the start column, the last ends at the end column (EXCLUSIVE), and the
   *  rows between are full width. */
  private selectionOnRow(absRow: number): readonly [number, number] | null {
    const top = this.selTop
    const bottom = this.selBottom
    if (!top || !bottom) return null
    if (absRow < top[1] || absRow > bottom[1]) return null
    let startCol: number
    let endCol: number
    if (this.columnSelect) {
      startCol = Math.min(top[0], bottom[0])
      endCol = Math.max(top[0], bottom[0])
    } else {
      startCol = absRow === top[1] ? top[0] : 0
      endCol = absRow === bottom[1] ? bottom[0] : this.cols
    }
    return endCol > startCol ? [startCol, endCol] : null
  }

  /**
   * The hovered link's column span on this VIEWPORT row, `[startCol, endColExclusive)`, or null.
   *
   * xterm's range is INCLUSIVE at both ends and can span rows; a middle row is covered edge to
   * edge. The `+ 1` on the end column is that inclusive→exclusive conversion, and forgetting it
   * leaves the link's last character un-underlined — a one-cell gap that reads as a rendering bug
   * rather than as an off-by-one.
   */
  private linkOnRow(row: number): readonly [number, number] | null {
    const link = this.internals.linkUnderline?.current()
    if (!link) return null
    if (row < link.y1 || row > link.y2) return null
    const startCol = row === link.y1 ? link.x1 : 0
    const endCol = row === link.y2 ? link.x2 + 1 : this.cols
    return endCol > startCol ? [Math.max(0, startCol), Math.min(this.cols, endCol)] : null
  }

  /** Which VIEWPORT rows the current selection covers — the repaint unit, clamped to the grid. */
  private selectionRowRange(): RowRange {
    const top = this.selTop
    const bottom = this.selBottom
    if (!top || !bottom) return null
    const viewportY = this.internals.viewportY()
    const from = Math.max(0, top[1] - viewportY)
    const to = Math.min(this.rows - 1, bottom[1] - viewportY)
    return to < from ? null : [from, to]
  }

  private cursorViewportRow(): number {
    return this.internals.baseY() + this.internals.cursorY() - this.internals.viewportY()
  }

  /** Exactly xterm's own dimension math (DomRenderer._updateDimensions), which is why the shell
   *  hands over DEVICE metrics rather than css ones: css.cell is derived from the ROUNDED css
   *  canvas, and xterm maps mouse coordinates through it.
   *
   *  Every leaf is assigned IN PLACE — see the `dimensions` field. xterm's own renderers write
   *  their dimensions object the same way, for the same reason. */
  private updateDims(): void {
    const m = this.internals.deviceMetrics()
    const dpr = this.internals.dpr() || 1
    const cols = Math.max(0, this.cols)
    const rows = Math.max(0, this.rows)
    const d = this.dimensions
    d.device.char.width = m.charW
    d.device.char.height = m.charH
    d.device.char.left = 0
    d.device.char.top = 0
    d.device.cell.width = m.cellW
    d.device.cell.height = m.cellH
    d.device.canvas.width = m.cellW * cols
    d.device.canvas.height = m.cellH * rows
    d.css.canvas.width = Math.round(d.device.canvas.width / dpr)
    d.css.canvas.height = Math.round(d.device.canvas.height / dpr)
    // A zero-column grid would make these NaN, which propagates into xterm's mouse math.
    d.css.cell.width = cols > 0 ? d.css.canvas.width / cols : 0
    d.css.cell.height = rows > 0 ? d.css.canvas.height / rows : 0
  }

  private emitRedraw(start: number, end: number): void {
    if (this.disposed) return
    for (const cb of this.redrawListeners) cb({ start, end })
  }
}

/** Union of two inclusive row ranges as a list of ranges to repack. Overlapping or touching
 *  ranges collapse into one; disjoint ones stay separate, so a selection jumping from the top of
 *  the viewport to the bottom does not repack everything in between. */
function mergeRanges(a: RowRange, b: RowRange): Array<readonly [number, number]> {
  if (!a) return b ? [b] : []
  if (!b) return [a]
  const [lo, hi] = a[0] <= b[0] ? [a, b] : [b, a]
  if (hi[0] <= lo[1] + 1) return [[lo[0], Math.max(lo[1], hi[1])]]
  return [lo, hi]
}