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.

14.6 KB
Raw Blame
/**
 * Stop a terminal DRAWING while the kanban board covers it, without stopping it PARSING.
 *
 * WHY. The canvas stays mounted under the board on purpose (`display: none` would 0x0-resize every
 * terminal into a tmux SIGWINCH — see the kanban section of CLAUDE.md), and nothing told xterm it
 * was covered: its only pause is its own GEOMETRIC IntersectionObserver (`RenderService`), and a
 * node under an opaque overlay still intersects the viewport. MEASURED (dev build, 12
 * streaming terminals, glass on, 60 s windows): board open over streaming terminals 36.5 % GPU /
 * 15.8 % renderer — no better than the canvas itself (30-32 %) — against 0.0 % / 2.4 % with the same
 * board over SILENT terminals, so essentially all of it was xterm painting output nobody could see
 * (140 RenderDebouncer refreshes per 5 s). Hiding the canvas with `visibility: hidden` measured
 * 35.5 %: CSS does not stop xterm's render service or WebGL's presents. The pause has to be xterm's.
 *
 * HOW: through xterm's OWN pause, never beside it. RenderService already knows how to be paused —
 * `refreshRows` on a paused service just sets `_needsFullRefresh`, renderer resizes queue on
 * `_pausedResizeTask`, and the transition back to intersecting flushes both and re-measures the
 * char size of a terminal that was opened hidden. All of that hangs off ONE method,
 * `_handleIntersectionChange(entry)`, which the observer reaches through `this.` (so an instance
 * property shadows it). We wrap it: the real entry is RECORDED, and what xterm is told is "not
 * intersecting" while covered, else the real entry. Covering and uncovering replay through the same
 * method, so the resume runs xterm's own bookkeeping rather than a copy of it that drifts.
 * Poking `_isPaused` directly would skip exactly that bookkeeping.
 *
 * The parser path is untouched: `term.write` still lands every byte in the buffer while paused, so
 * nothing is lost — the board-up period is one full repaint on the way out.
 *
 * WHAT THIS DOES NOT DO, ON PURPOSE. It never feeds the app's own visibility verdict
 * (`reportVisible` / the WebGL budget's `setVisible` / hibernation / the offscreen teardown):
 * folding the board into that verdict would let the board hibernate or tear down the sessions it
 * is showing cards for. The WebGL context stays held while the
 * board is up; only the draws stop.
 *
 * Private xterm API (`_core._renderService`), exactly as TerminalNode's renderer-swap net and
 * addon-fit already use it. Feature-detected: a build without the method gets no pause (today's
 * behaviour), never a throw.
 */

/** The slice of an IntersectionObserverEntry xterm's handler reads. */
export interface IntersectionVerdict {
  isIntersecting: boolean
  intersectionRatio: number
}

/** The private RenderService surface this module touches. */
export interface PausableRenderService {
  _handleIntersectionChange(entry: IntersectionVerdict): void
  /** Selection redraw request — see "THE PATHS BESIDE THE RENDER SERVICE" below. */
  handleSelectionChanged?(...args: unknown[]): void
}

/** Minimal xterm shape, so the unit test needs no DOM and no real Terminal. */
export interface PausableTerminal {
  _core?: {
    _renderService?: Partial<PausableRenderService>
    /** CoreBrowserTerminal: repositions the hidden input textarea on every cursor move. */
    _syncTextArea?: () => void
    /** The DOM Viewport: scroll-area height + scrollTop, synced on every scroll. */
    viewport?: { syncScrollArea?: (immediate?: boolean) => void }
  }
}

/*
 * THE PATHS BESIDE THE RENDER SERVICE. Pausing the render service stops xterm DRAWING, but three
 * per-output paths in xterm 5.5 run beside it and never ask whether it is paused. MEASURED (Server
 * Edition in headless Chrome, 20 terminals each printing a status line 10×/s and a full line every
 * second, board open, Liquid Glass on, every CSS animation held, 15 s windows): with the render
 * pause alone, GPU 9.3 % + renderer 17.8 %, main thread 14.4 % busy, ~950 forced layouts. With the
 * three paths below also held: GPU 0.4 % + renderer 3.1 %, main thread 1.5 %, zero layouts — what
 * is left is the parser, which must run. All three are per terminal per output, so this is the
 * board cost that grows with the number of busy sessions.
 *  - `CoreBrowserTerminal._syncTextArea` (every cursor move): writes the hidden textarea's
 *    position, i.e. a style/layout pass per frame for something nobody can see.
 *  - `Viewport.syncScrollArea` (every scroll): reads offsetHeight, writes the scroll area's height,
 *    reads and writes scrollTop — forced layouts (our viewport-scroll-sync wraps `_innerRefresh`
 *    with two more scrollTop reads).
 *  - `RenderService.handleSelectionChanged` (every scroll, via `SelectionService.refresh`): calls
 *    the renderer directly. The DOM renderer answers with a FULL `renderRows`, paused or not, so
 *    every terminal without a WebGL context repainted its whole screen behind the board on every
 *    line — almost all of the GPU figure above.
 * Each is held the same way the intersection handler is: an instance property shadows the
 * prototype method (callers reach all three through `this.`), a held call is recorded, and the
 * uncover replays it ONCE — the scroll area immediately, so the first frame after the board is
 * already scrolled to the right place; the selection with its LATEST range, because RenderService
 * keeps that range only through this call and the resume repaint reads it. A covered dispose (a
 * park) replays too, the scroll area deferred to the next frame because the element is about to be
 * detached. A core without a method simply has nothing held for it. Only the BOARD holds them: a
 * terminal that is merely off screen keeps xterm's stock behaviour.
 */
interface HeldPath {
  /** Replay the held call once, if one is owed. `args` overrides the recorded ones. */
  flush(args?: unknown[]): void
  /** Put the original method back (own property or prototype, as it was). */
  restore(): void
}

function holdWhile(target: object | undefined, name: string, held: () => boolean): HeldPath | null {
  const obj = target as Record<string, unknown> | undefined
  if (!obj || typeof obj[name] !== 'function') return null
  const hadOwn = Object.prototype.hasOwnProperty.call(obj, name)
  const ownBefore = obj[name]
  const original = (ownBefore as (...a: unknown[]) => unknown).bind(obj)
  let owed: unknown[] | null = null
  obj[name] = (...args: unknown[]): unknown => {
    if (held()) {
      owed = args
      return undefined
    }
    return original(...args)
  }
  return {
    flush(args) {
      if (!owed) return
      const recorded = owed
      owed = null
      try {
        original(...(args ?? recorded))
      } catch {
        // A catch-up, never worth throwing for: a dispose can run after xterm tore its own
        // services down, and an exception here would escape a React effect cleanup.
      }
    },
    restore() {
      if (hadOwn) obj[name] = ownBefore
      else delete obj[name]
    }
  }
}

/**
 * The decision, alone: should xterm render right now? Paused when covered OR when it is
 * geometrically out of view (xterm's own rule, kept). Exported so the rule is tested by name.
 */
export function renderPaused(covered: boolean, intersecting: boolean): boolean {
  return covered || !intersecting
}

/** An entry's own answer, the way xterm reads it (`isIntersecting` absent → ratio 0 = hidden). */
function intersects(entry: Partial<IntersectionVerdict>): boolean {
  return entry.isIntersecting === undefined ? entry.intersectionRatio !== 0 : entry.isIntersecting
}

const verdict = (intersecting: boolean): IntersectionVerdict => ({
  isIntersecting: intersecting,
  intersectionRatio: intersecting ? 1 : 0
})

export interface BoardRenderPause {
  /** Re-read `covered()` and act on a change. Change-gated: a call that moved nothing is free. */
  sync(): void
  /** Restore xterm's own handler and leave it in its natural (geometric) state. Idempotent. */
  dispose(): void
}

export interface BoardRenderPauseOptions {
  /** Is this terminal covered right now? Read at every sync and at every observer delivery. */
  covered: () => boolean
  /** Covered → uncovered while geometrically on screen: the caller's guaranteed full repaint.
   *  xterm's own resume refresh is debounced and can be swallowed (see `fullRepaint` in
   *  TerminalNode), so the board's exit owes the one that cannot be. */
  onUncover?: () => void
}

/** Marker so a second install on the same render service (a park re-adopt that skipped a
 *  dispose) replaces the first instead of stacking a wrapper on a wrapper. */
const INSTALLED = Symbol('nt.boardRenderPause')

type Wrapped = PausableRenderService & { [INSTALLED]?: BoardRenderPause }

/**
 * Wrap `term`'s render service. Returns null (and changes nothing) when the private method is
 * missing — an xterm upgrade that renamed it degrades to today's behaviour.
 */
export function installBoardRenderPause(
  term: PausableTerminal,
  opts: BoardRenderPauseOptions
): BoardRenderPause | null {
  const rs = term._core?._renderService as Wrapped | undefined
  if (!rs || typeof rs._handleIntersectionChange !== 'function') return null
  // One layer, ever: an earlier controller still attached gives its original back first.
  rs[INSTALLED]?.dispose()
  const hadOwn = Object.prototype.hasOwnProperty.call(rs, '_handleIntersectionChange')
  const ownBefore = rs._handleIntersectionChange
  const original = ownBefore.bind(rs)
  // Seed the geometry from what xterm is ACTING ON right now, read after the earlier controller
  // (if any) handed its real verdict back. Not a blanket `true`: a terminal re-adopted after a park
  // was detached, so its observer already delivered not-intersecting (`_isPaused = true`); reattached
  // still off screen, the observer has nothing new to report, and a `true` seed made the next board
  // cover/uncover UNPAUSE it — streaming output painted off screen until a pan in and out (found in
  // review, reproduced against xterm 5.5's handler). A fresh xterm starts unpaused with no
  // delivery yet, so the same read gives intersecting there. A build without the field: `true`.
  const pausedNow = (rs as { _isPaused?: unknown })._isPaused
  let geometric = typeof pausedNow === 'boolean' ? !pausedNow : true
  let covered = opts.covered()
  let disposed = false

  const apply = (): void => original(verdict(!renderPaused(covered, geometric)))

  // The paths beside the render service (see the block above `holdWhile`): held exactly while
  // covered, never merely while off screen.
  const isHeld = (): boolean => !disposed && covered
  const selection = holdWhile(rs, 'handleSelectionChanged', isHeld)
  const scrollArea = holdWhile(term._core?.viewport, 'syncScrollArea', isHeld)
  const textarea = holdWhile(term._core, '_syncTextArea', isHeld)
  /** Replay what the covered period owed: `immediate` syncs the scroll area now (uncover), else on
   *  the next frame (a park's dispose into an element about to be detached). */
  const flushHeld = (immediate: boolean): void => {
    selection?.flush()
    scrollArea?.flush(immediate ? [true] : [])
    textarea?.flush()
  }

  const controller: BoardRenderPause = {
    sync(): void {
      if (disposed) return
      const now = opts.covered()
      if (now === covered) return
      covered = now
      apply()
      if (!covered) flushHeld(true)
      if (!covered && geometric) opts.onUncover?.()
    },
    dispose(): void {
      if (disposed) return
      disposed = true
      if (hadOwn) rs._handleIntersectionChange = ownBefore
      else delete (rs as Partial<Wrapped>)._handleIntersectionChange
      selection?.restore()
      scrollArea?.restore()
      textarea?.restore()
      if (rs[INSTALLED] === controller) delete rs[INSTALLED]
      // Hand xterm back the geometry it would have had all along. A no-op when nothing was
      // covered; when something was, it is xterm's own resume (flush + refresh).
      // Replayed on a PARK too, on purpose, even though the element is about to be detached: left
      // paused, a park whose detach and re-adopt land between two observer deliveries (the
      // observer reports changes only at a rendering step) would come back on screen with
      // `_isPaused` stuck true and nothing left to clear it. The cost is a single refresh into a
      // detached element, and the WebGL dispose that follows does its own full refresh anyway.
      if (covered) {
        original(verdict(geometric))
        flushHeld(false)
      }
    }
  }

  rs._handleIntersectionChange = (entry: IntersectionVerdict): void => {
    if (disposed) return original(entry)
    geometric = intersects(entry)
    // The board can have opened between syncs (a node mounted under it, an observer delivery
    // racing the view switch), so the observer path re-reads rather than trusting the cache.
    covered = opts.covered()
    if (!covered) {
      original(entry)
      flushHeld(true)
      return
    }
    original(verdict(false))
  }
  rs[INSTALLED] = controller
  // Mounted under a board that is already up (a card's "new session", a project switch onto a
  // board-view project): pause before the first frame rather than waiting for a change.
  if (covered) apply()
  return controller
}

/**
 * Where a terminal node keeps its live session's pause, so the wiring is one tested unit rather
 * than three lines spread over TerminalNode. The lifecycle run `attach`es (the render service only
 * exists once the terminal is open) and calls the release from its cleanup — per run, NOT through
 * `cleanups`, because a park keeps the xterm while this run's closures die with it, so the
 * adopting run must install its own. The board-flag and focus-mode effects only `sync`.
 *
 * The slot is the point: a node mounted while the board is already up is paused at install, and
 * the board closing reaches it only through `sync`, so a controller that never landed in the slot
 * leaves that node frozen on stale content until it is panned off screen and back.
 */
export interface BoardPauseSlot {
  /** Install on `term` for this run and hold the controller. Returns the run's release: dispose,
   *  and clear the slot unless a newer run has attached since. */
  attach(term: PausableTerminal, opts: BoardRenderPauseOptions): () => void
  /** Re-read `covered()` on whatever controller is attached now; nothing attached, nothing done. */
  sync(): void
}

export function createBoardPauseSlot(): BoardPauseSlot {
  let current: BoardRenderPause | null = null
  return {
    attach(term, opts) {
      const pause = installBoardRenderPause(term, opts)
      current = pause
      return () => {
        pause?.dispose()
        if (current === pause) current = null
      }
    },
    sync() {
      current?.sync()
    }
  }
}