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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { adoptUserNodes } from '@xyflow/system'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import {
GlyphGridRendererAddonCore,
type CursorBlinkPhaseTarget,
type CursorBlinkSeam
} from '../glyphgrid/addon'
// The addon's fakes, shared with `glyphgrid/addon.test.ts`. A plain module, not a `.test.ts`:
// importing a test file makes vitest collect its whole suite a second time under this one.
import { fakeTerm, recordingAtlas, recordingHandle } from '../glyphgrid/addon-fakes'
import { FLAG_CURSOR, readCell } from '../glyphgrid/cells'
import type { GridHandle } from '../glyphgrid/engine'
import { createFrameLoop, type FrameLoop, type FrameLoopHost } from '../glyphgrid/frame-driver'
import { useProjects } from '../state/projects'
import { useSettings } from '../state/settings'
import { useViewMode } from '../state/viewMode'
import {
boardCoversCanvas,
createBoardFrameGate,
createCellRebuildGuard,
createContextLossPolicy,
createCursorBlinkClock,
createPixelRatioWatcher,
cursorBlinkTarget,
setCursorBlinkTarget,
subscribeCursorBlinkRestart,
subscribeCursorBlinkTarget,
CURSOR_BLINK_INTERVAL_MS,
failSharedGlyph,
getSharedGlyphContext,
effectiveStackOrder,
flushOpaqueNodeIds,
gestureTerminalIds,
hasActiveGesture,
idsFromOrderSig,
installAtlasResetLog,
nodeIsOpaque,
nodeOrderSig,
nodeStackZ,
nodeZFor,
cellsDisagree,
opaqueNodeIds,
pixelRatioChanged,
primeOpaqueNodeIds,
releaseCursorBlinkTarget,
restartCursorBlink,
setNodeZOrder,
setOpaqueNodeIds,
setSharedGlyphCamera,
sharedGlyphActive,
sharedGlyphAvailable,
subscribeNodeZOrder,
subscribeOpaqueSet,
syncAtlasPixelRatio,
useSharedGlyph,
RESTORE_COOLDOWN_MS,
type AtlasResetSource,
type CursorBlinkClock,
type CursorBlinkTarget,
type PixelRatioWatchHost,
type StackedNode,
type StackOrderNode
} from './SharedGlyphLayer'
// Only the PURE parts are unit-testable here: there is no WebGL2, no OffscreenCanvas and no
// layout in the node test environment, so the component, the rAF driver and the GL singleton are
// device-verified (T6 checklist). What IS covered is everything the other tasks build on: the
// order signature Canvas derives, the store transitions T5/T6 read, and the z-order map + its
// notification seam.
beforeEach(() => {
// The store and the z map are module singletons; reset them explicitly so the tests are
// order-independent.
useSharedGlyph.setState({ enabled: false, generation: 0, failed: false })
setNodeZOrder([])
setOpaqueNodeIds([])
})
describe('nodeOrderSig', () => {
it('joins TERMINAL node ids in array order', () => {
const sig = nodeOrderSig([
{ id: 'a', type: 'terminal' },
{ id: 'b', type: 'terminal' }
])
expect(idsFromOrderSig(sig)).toEqual(['a', 'b'])
})
it('ignores every other node kind — only terminals own a grid', () => {
const sig = nodeOrderSig([
{ id: 's1', type: 'sticky' },
{ id: 't1', type: 'terminal' },
{ id: 'g1', type: 'group' },
{ id: 't2', type: 'terminal' },
{ id: 'sub', type: 'subagent' }
])
expect(idsFromOrderSig(sig)).toEqual(['t1', 't2'])
})
it('is order sensitive — a reorder must produce a different signature', () => {
const a = nodeOrderSig([
{ id: 'x', type: 'terminal' },
{ id: 'y', type: 'terminal' }
])
const b = nodeOrderSig([
{ id: 'y', type: 'terminal' },
{ id: 'x', type: 'terminal' }
])
expect(a).not.toBe(b)
})
it('elevates a SELECTED terminal above the unselected ones, wherever it sits in the array', () => {
// React Flow's elevateNodesOnSelect (default on, and now on in EVERY renderer mode) lifts the
// selected node's DOM to z 1000; the grids mirror it so canvas and DOM tell the same story.
// Round 4 removed the mirroring and turned the prop off instead — rejected in round 5, because
// that takes away "selecting/dragging brings a node to the front". The overlap it was trying to
// fix is handled by `opaqueNodeIds` (a stacked terminal leaves the canvas entirely) instead.
const sig = nodeOrderSig([
{ id: 'a', type: 'terminal' },
{ id: 'b', type: 'terminal', selected: true },
{ id: 'c', type: 'terminal' }
])
expect(idsFromOrderSig(sig)).toEqual(['a', 'c', 'b'])
})
it('keeps selected nodes in their own relative order (a multi-select is stable)', () => {
const sig = nodeOrderSig([
{ id: 'a', type: 'terminal', selected: true },
{ id: 'b', type: 'terminal' },
{ id: 'c', type: 'terminal', selected: true }
])
expect(idsFromOrderSig(sig)).toEqual(['b', 'a', 'c'])
})
it('an all-selected canvas keeps plain array order', () => {
const sig = nodeOrderSig([
{ id: 'a', type: 'terminal', selected: true },
{ id: 'b', type: 'terminal', selected: true }
])
expect(idsFromOrderSig(sig)).toEqual(['a', 'b'])
})
it('a selected NON-terminal does not reorder the terminals', () => {
// The elevation is applied over ALL nodes (that is what the DOM does) and terminals are
// filtered out of the result afterwards — so a selected sticky must be invisible here.
const sig = nodeOrderSig([
{ id: 't1', type: 'terminal' },
{ id: 's1', type: 'sticky', selected: true },
{ id: 't2', type: 'terminal' }
])
expect(idsFromOrderSig(sig)).toEqual(['t1', 't2'])
})
it('puts a GROUPED terminal above an ungrouped one that follows it in the array', () => {
// A child gets `parentZ + 1` = 1 while every ungrouped node is 0, so the grouped terminal is on
// top regardless of array position. (The FRAME itself is 0 — tied with the ungrouped node, not
// above it; that is the part the 'auto'-branch model got wrong.)
const sig = nodeOrderSig([
{ id: 'g', type: 'group' },
{ id: 'inside', type: 'terminal', parentId: 'g' },
{ id: 'outside', type: 'terminal' }
])
expect(idsFromOrderSig(sig)).toEqual(['outside', 'inside'])
})
it('a SELECTED frame carries its children above a selected ungrouped terminal', () => {
const sig = nodeOrderSig([
{ id: 'g', type: 'group', selected: true },
{ id: 'inside', type: 'terminal', parentId: 'g' },
{ id: 'outside', type: 'terminal', selected: true }
])
expect(idsFromOrderSig(sig)).toEqual(['outside', 'inside'])
})
it('an untyped node is not a terminal (React Flow defaults type to "default")', () => {
expect(nodeOrderSig([{ id: 'a' }])).toBe('')
})
it('round-trips the empty canvas as an EMPTY list, not a one-element list of ""', () => {
const sig = nodeOrderSig([])
expect(sig).toBe('')
expect(idsFromOrderSig(sig)).toEqual([])
})
})
describe('useSharedGlyph store', () => {
// The failure funnel warns by design; silence it here and assert the once-ness explicitly.
let warn: ReturnType<typeof vi.spyOn>
beforeEach(() => {
warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
})
afterEach(() => {
warn.mockRestore()
})
it('starts off, ungenerated and unfailed — the default-mode user must see nothing', () => {
expect(useSharedGlyph.getState()).toMatchObject({ enabled: false, generation: 0, failed: false })
expect(sharedGlyphActive()).toBe(false)
})
it('bumpGeneration increments (the re-register signal)', () => {
useSharedGlyph.getState().bumpGeneration()
useSharedGlyph.getState().bumpGeneration()
expect(useSharedGlyph.getState().generation).toBe(2)
})
it('markFailed flips failed AND bumps the generation, so one subscription wakes every node', () => {
useSharedGlyph.getState().markFailed()
expect(useSharedGlyph.getState().failed).toBe(true)
expect(useSharedGlyph.getState().generation).toBe(1)
})
it('markFailed is idempotent — a second failure must not re-notify or re-log', () => {
useSharedGlyph.getState().markFailed()
useSharedGlyph.getState().markFailed()
expect(useSharedGlyph.getState().generation).toBe(1)
expect(warn).toHaveBeenCalledTimes(1)
})
it('markFailed goes through the SAME funnel as failSharedGlyph (no half-failed state)', () => {
// The store action must not be a shortcut that flips the flag while the GPU context stays
// held: it delegates, so the two entries are interchangeable and the second one is a no-op.
failSharedGlyph('test')
useSharedGlyph.getState().markFailed()
expect(useSharedGlyph.getState()).toMatchObject({ failed: true, generation: 1 })
expect(warn).toHaveBeenCalledTimes(1)
})
it('disabling the mode bumps the generation — a disposed context must be announced', () => {
// setEnabled(false) drops the context; every registered grid is now holding an inert handle
// and would stay blank until it remounted without this signal.
useSharedGlyph.getState().setEnabled(true)
useSharedGlyph.getState().setEnabled(false)
expect(useSharedGlyph.getState().generation).toBe(2)
// Change-gated: a repeated disable disposes nothing, so it announces nothing.
useSharedGlyph.getState().setEnabled(false)
expect(useSharedGlyph.getState().generation).toBe(2)
})
it('ENABLING the mode bumps the generation too — already-mounted terminals must join', () => {
// The user flips the setting to Shared with a canvas full of live terminals. Each of them
// subscribes to `generation` and re-evaluates its participation on a bump; without one here
// they would keep painting through xterm's own renderer until they remounted (a project
// switch), and the setting would look like it did nothing. The bump is the ONE signal in this
// seam, so enabling rides it exactly like disposal does.
expect(useSharedGlyph.getState().generation).toBe(0)
useSharedGlyph.getState().setEnabled(true)
expect(useSharedGlyph.getState()).toMatchObject({ enabled: true, generation: 1 })
})
it('an enable bump carries the NEW enabled flag in the SAME notification', () => {
// A subscriber's first move is to ask `sharedGlyphActive()`. If `enabled` were written in a
// separate set() from the generation, one of the two notifications would carry a state that
// disagrees with the other and a node would decide on the stale half.
const seen: { enabled: boolean; generation: number }[] = []
const unsub = useSharedGlyph.subscribe((s) =>
seen.push({ enabled: s.enabled, generation: s.generation })
)
useSharedGlyph.getState().setEnabled(true)
unsub()
expect(seen).toEqual([{ enabled: true, generation: 1 }])
})
it('a repeated enable is change-gated — no bump, no re-registration storm', () => {
useSharedGlyph.getState().setEnabled(true)
useSharedGlyph.getState().setEnabled(true)
expect(useSharedGlyph.getState().generation).toBe(1)
})
it('sharedGlyphActive is enabled AND not failed', () => {
useSharedGlyph.getState().setEnabled(true)
expect(sharedGlyphActive()).toBe(true)
useSharedGlyph.getState().markFailed()
expect(sharedGlyphActive()).toBe(false)
})
it('setEnabled is change-gated and survives a disable/enable round trip', () => {
// Disabling also drops the GPU context; with none created (node env) that is a no-op, and it
// must not throw or disturb the flags.
useSharedGlyph.getState().setEnabled(true)
useSharedGlyph.getState().setEnabled(true)
expect(() => useSharedGlyph.getState().setEnabled(false)).not.toThrow()
expect(sharedGlyphActive()).toBe(false)
useSharedGlyph.getState().setEnabled(true)
expect(sharedGlyphActive()).toBe(true)
})
it('setEnabled(false) after a failure keeps the session failed (no silent retry)', () => {
useSharedGlyph.getState().setEnabled(true)
useSharedGlyph.getState().markFailed()
useSharedGlyph.getState().setEnabled(false)
useSharedGlyph.getState().setEnabled(true)
expect(useSharedGlyph.getState().failed).toBe(true)
expect(sharedGlyphActive()).toBe(false)
})
})
describe('setNodeZOrder', () => {
it('maps each id to its index — array order IS the paint order', () => {
setNodeZOrder(['a', 'b', 'c'])
expect(nodeZFor('a')).toBe(0)
expect(nodeZFor('b')).toBe(1)
expect(nodeZFor('c')).toBe(2)
})
it('an id it has never seen lands on TOP, not at 0', () => {
// A node created between two order pushes is appended last on the canvas, so "topmost" is the
// answer that matches what the user sees; 0 would flash it under every other terminal.
setNodeZOrder(['a', 'b'])
expect(nodeZFor('fresh')).toBe(2)
})
it('notifies subscribers when the order changes', () => {
const seen = vi.fn()
const unsub = subscribeNodeZOrder(seen)
setNodeZOrder(['a'])
setNodeZOrder(['a', 'b'])
expect(seen).toHaveBeenCalledTimes(2)
unsub()
})
it('does NOT notify when the same order is pushed again', () => {
setNodeZOrder(['a', 'b'])
const seen = vi.fn()
const unsub = subscribeNodeZOrder(seen)
setNodeZOrder(['a', 'b'])
expect(seen).not.toHaveBeenCalled()
unsub()
})
it('stops notifying after unsubscribe', () => {
const seen = vi.fn()
subscribeNodeZOrder(seen)()
setNodeZOrder(['z'])
expect(seen).not.toHaveBeenCalled()
})
it('an emptied canvas clears the map', () => {
setNodeZOrder(['a', 'b'])
setNodeZOrder([])
expect(nodeZFor('a')).toBe(0)
})
})
describe('nodeStackZ (React Flow z, reproduced)', () => {
// Every number below was READ OFF the real `adoptUserNodes` from @xyflow/system, called with what
// @xyflow/react's store passes it: `{ elevateNodesOnSelect: true, zIndexMode: 'basic' }`. 'basic'
// is the default in BOTH `getInitialState` and the <ReactFlow> component, and nothing in src/
// passes the prop. That detail decides the load-bearing case: the 'auto' branch adds a
// ROOT_PARENT_Z_INCREMENT band that would put a populated frame at 10 instead of 0, reversing
// frame-vs-ungrouped — and a previous cut of this file shipped exactly that mistake.
it('is 0 for a plain node and 1000 for a selected one', () => {
const z = nodeStackZ([{ id: 'a' }, { id: 'b', selected: true }])
expect(z.get('a')).toBe(0)
expect(z.get('b')).toBe(1000)
})
it('leaves a group FRAME at 0 — tied with every ungrouped node — and lifts its child to 1', () => {
// A frame does NOT outrank ungrouped nodes. Frames merely sort first in the array, so an
// ungrouped node overlapping one paints ON TOP of it (and must therefore go opaque).
const z = nodeStackZ([{ id: 'g' }, { id: 'inside', parentId: 'g' }, { id: 'outside' }])
expect(z.get('g')).toBe(0)
expect(z.get('inside')).toBe(1)
expect(z.get('outside')).toBe(0)
})
it('does not band root frames — two frames tie, and so do their children', () => {
const z = nodeStackZ([
{ id: 'g1' },
{ id: 'g2' },
{ id: 'c1', parentId: 'g1' },
{ id: 'c2', parentId: 'g2' }
])
expect(z.get('g1')).toBe(0)
expect(z.get('g2')).toBe(0)
expect(z.get('c1')).toBe(1)
expect(z.get('c2')).toBe(1)
})
it('a selected frame carries its children to 1001, above a selected ungrouped node', () => {
const z = nodeStackZ([
{ id: 'g', selected: true },
{ id: 'c', parentId: 'g' },
{ id: 'outside', selected: true }
])
expect(z.get('g')).toBe(1000)
expect(z.get('c')).toBe(1001)
expect(z.get('outside')).toBe(1000)
})
it('a selected CHILD of an unselected frame wins on its own z', () => {
// childZ 1000 > parentZ 0, so the child keeps 1000 rather than parentZ + 1.
const z = nodeStackZ([{ id: 'g' }, { id: 'c', parentId: 'g', selected: true }])
expect(z.get('c')).toBe(1000)
})
it('nested frames stack one per level', () => {
const z = nodeStackZ([
{ id: 'outer' },
{ id: 'inner', parentId: 'outer' },
{ id: 't', parentId: 'inner' }
])
expect(z.get('outer')).toBe(0)
expect(z.get('inner')).toBe(1)
expect(z.get('t')).toBe(2)
})
it('ignores a child whose parent is missing or comes later (React Flow warns and gives up)', () => {
const z = nodeStackZ([{ id: 'c', parentId: 'g' }, { id: 'g' }])
expect(z.get('c')).toBe(0)
})
it('survives a parentId cycle', () => {
expect(() => nodeStackZ([{ id: 'a', parentId: 'b' }, { id: 'b', parentId: 'a' }])).not.toThrow()
})
// The cases above are readable; THIS is the one that keeps them honest. `nodeStackZ` is
// transcribed from someone else's algorithm, and transcription is how the last two bugs got in —
// the first modelled selection only, the second modelled the `'auto'` branch of a library that
// defaults to `'basic'`. Reading the source more carefully is not a fix for that class of
// mistake; RUNNING it is. So every shape below goes through the real `adoptUserNodes`, called
// exactly as `@xyflow/react`'s store calls it, and the answers must be identical. It needs no
// DOM, which is why it can live in this suite at all.
//
// If this ever fails after a React Flow bump, the LIBRARY moved: re-derive `nodeStackZ` from the
// new behaviour rather than pinning the old numbers.
describe('agrees with the real adoptUserNodes', () => {
const rf = (nodes: readonly StackOrderNode[]): Record<string, number> => {
const lookup = new Map<string, { internals: { z: number } }>()
adoptUserNodes(
nodes.map((n) => ({
...n,
position: { x: 0, y: 0 },
data: {},
measured: { width: 10, height: 10 }
})) as never,
lookup as never,
new Map(),
// The store's own options (index.mjs `setNodes`): everything else is left at its default,
// which is where `zIndexMode: 'basic'` comes from.
{ elevateNodesOnSelect: true, checkEquality: true } as never
)
const out: Record<string, number> = {}
for (const [id, n] of lookup) out[id] = n.internals.z
return out
}
const ours = (nodes: readonly StackOrderNode[]): Record<string, number> =>
Object.fromEntries(nodeStackZ(nodes))
const shapes: Record<string, StackOrderNode[]> = {
'flat canvas': [{ id: 'a' }, { id: 'b' }],
'one selected': [{ id: 'a' }, { id: 'b', selected: true }],
'frame, child, ungrouped': [{ id: 'g' }, { id: 'inside', parentId: 'g' }, { id: 'outside' }],
'ungrouped before the frame': [
{ id: 'outside' },
{ id: 'g' },
{ id: 'inside', parentId: 'g' }
],
'two frames': [
{ id: 'g1' },
{ id: 'g2' },
{ id: 'c1', parentId: 'g1' },
{ id: 'c2', parentId: 'g2' }
],
'two frames, children interleaved': [
{ id: 'g1' },
{ id: 'g2' },
{ id: 'c2', parentId: 'g2' },
{ id: 'c1', parentId: 'g1' }
],
'selected frame': [
{ id: 'g', selected: true },
{ id: 'c', parentId: 'g' },
{ id: 'outside', selected: true }
],
'selected child': [{ id: 'g' }, { id: 'c', parentId: 'g', selected: true }],
'nested frames': [
{ id: 'outer' },
{ id: 'inner', parentId: 'outer' },
{ id: 't', parentId: 'inner' }
],
'nested frames, outer selected': [
{ id: 'outer', selected: true },
{ id: 'inner', parentId: 'outer' },
{ id: 't', parentId: 'inner' }
],
'several children of one frame': [
{ id: 'g' },
{ id: 'c1', parentId: 'g' },
{ id: 'c2', parentId: 'g' },
{ id: 'c3', parentId: 'g' }
]
}
for (const [name, nodes] of Object.entries(shapes)) {
it(name, () => {
expect(ours(nodes)).toEqual(rf(nodes))
})
}
})
})
describe('effectiveStackOrder', () => {
it('returns the input array itself when every z is 0 (no copy on the common canvas)', () => {
const nodes = [{ id: 'a' }, { id: 'b' }]
expect(effectiveStackOrder(nodes)).toBe(nodes)
})
it('breaks z ties by array order (a stable sort)', () => {
const order = effectiveStackOrder([
{ id: 'a' },
{ id: 'b' },
{ id: 'c', selected: true },
{ id: 'd' }
])
expect(order.map((n) => n.id)).toEqual(['a', 'b', 'd', 'c'])
})
})
describe('opaqueNodeIds', () => {
/** A 100×100 node at (x, y). Sizes come through `measured` (a live canvas) unless overridden. */
const at = (
id: string,
x: number,
y: number,
extra: Partial<StackedNode> = {}
): StackedNode => ({
id,
type: 'terminal',
position: { x, y },
measured: { width: 100, height: 100 },
...extra
})
it('leaves a terminal that overlaps nothing on the shared canvas', () => {
expect(opaqueNodeIds([at('a', 0, 0), at('b', 200, 0)])).toEqual([])
})
it('marks the UPPER terminal of an overlapping pair, and only it', () => {
// The lower one may stay on the canvas: the opaque node above hides it natively, which is the
// asymmetry the whole design rests on.
expect(opaqueNodeIds([at('low', 0, 0), at('high', 50, 50)])).toEqual(['high'])
})
it('a terminal stacked over a NON-terminal node counts too', () => {
// "Reveals another node" is about any kind — a sticky's text under a transparent body is the
// same defect as a terminal's.
const nodes = [at('note', 0, 0, { type: 'sticky' }), at('t', 20, 20)]
expect(opaqueNodeIds(nodes)).toEqual(['t'])
})
it('follows the SELECTION elevation, not raw array order', () => {
// Selecting the lower node lifts it above its neighbour in the DOM, so it is now the one whose
// body could reveal something — and the neighbour is free to go back on the canvas.
const nodes = [at('a', 0, 0, { selected: true }), at('b', 50, 50)]
expect(opaqueNodeIds(nodes)).toEqual(['a'])
expect(opaqueNodeIds([at('a', 0, 0), at('b', 50, 50)])).toEqual(['b'])
})
it('edge-to-edge nodes are not overlapping', () => {
// A snapped grid or a tidy row shares boundaries everywhere; treating that as an overlap would
// send half a neat canvas to the DOM renderer.
expect(opaqueNodeIds([at('a', 0, 0), at('b', 100, 0)])).toEqual([])
})
it('does NOT count a node\'s own group frame as something beneath it', () => {
// A grouped terminal is inside its frame's rect by construction. Counting it would put every
// grouped terminal on the DOM renderer permanently.
const group: StackedNode = {
id: 'g',
type: 'group',
position: { x: 0, y: 0 },
measured: { width: 400, height: 400 }
}
const child = at('t', 20, 20, { parentId: 'g' })
expect(opaqueNodeIds([group, child])).toEqual([])
})
it('counts an UNRELATED group frame beneath it', () => {
const group: StackedNode = {
id: 'g',
type: 'group',
position: { x: 0, y: 0 },
measured: { width: 400, height: 400 }
}
expect(opaqueNodeIds([group, at('t', 20, 20)])).toEqual(['t'])
})
it('resolves a grouped node\'s position through its parent chain', () => {
// The child's own `position` is frame-relative: read raw it would sit at (10,10) and miss the
// terminal it actually covers at (510,510).
const group: StackedNode = {
id: 'g',
type: 'group',
position: { x: 500, y: 500 },
measured: { width: 400, height: 400 }
}
// `out` is placed BEFORE the frame so it is beneath everything and cannot be marked itself —
// the assertion is about the child's resolved position and nothing else.
const outside = at('out', 510, 510)
const child = at('t', 10, 10, { parentId: 'g' })
expect(opaqueNodeIds([outside, group, child])).toEqual(['t'])
})
it('ignores collapsed and ⌘M terminals — they hold no grid either way', () => {
expect(opaqueNodeIds([at('a', 0, 0), at('b', 50, 50, { data: { collapsed: true } })])).toEqual(
[]
)
expect(opaqueNodeIds([at('a', 0, 0), at('b', 50, 50, { data: { mdMode: true } })])).toEqual([])
})
it('a collapsed terminal is still something to be stacked OVER', () => {
// It is an opaque header strip on screen; covering it is a real overlap.
const nodes = [at('c', 0, 0, { data: { collapsed: true } }), at('t', 50, 50)]
expect(opaqueNodeIds(nodes)).toEqual(['t'])
})
it('falls back to width/height when React Flow has not measured the node yet', () => {
const a: StackedNode = { id: 'a', type: 'terminal', position: { x: 0, y: 0 }, width: 100, height: 100 }
const b: StackedNode = { id: 'b', type: 'terminal', position: { x: 50, y: 50 }, width: 100, height: 100 }
expect(opaqueNodeIds([a, b])).toEqual(['b'])
})
it('a node of unknowable size contributes nothing, in either direction', () => {
const sizeless: StackedNode = { id: 'x', type: 'terminal', position: { x: 0, y: 0 } }
expect(opaqueNodeIds([sizeless, at('t', 10, 10)])).toEqual([])
expect(opaqueNodeIds([at('t', 10, 10), sizeless])).toEqual([])
})
it('survives a parentId cycle instead of spinning', () => {
const a = at('a', 0, 0, { parentId: 'b' })
const b = at('b', 0, 0, { parentId: 'a' })
expect(() => opaqueNodeIds([a, b])).not.toThrow()
})
it('reports every stacked terminal on a pile, not just the top one', () => {
expect(opaqueNodeIds([at('a', 0, 0), at('b', 20, 20), at('c', 40, 40)])).toEqual(['b', 'c'])
})
it('marks a terminal lying on a POPULATED group frame — the frame is not above it', () => {
// The case both wrong z models broke, from opposite sides. A frame is z 0, tied with every
// ungrouped node, and frames sort FIRST in the array — so `outside` paints on top of the frame
// and must be opaque, or the frame's dashed border and its label pill (DOM, above any canvas
// plate) show straight through the terminal's transparent body. The banded 'auto' model gave
// the frame z 10, concluded the terminal was underneath it, and left it transparent.
// `inside` is placed clear of `outside` so this asserts only the frame relationship.
const group: StackedNode = {
id: 'g',
type: 'group',
position: { x: 0, y: 0 },
measured: { width: 400, height: 400 }
}
const inside = at('inside', 300, 300, { parentId: 'g' })
const outside = at('outside', 10, 10)
expect(opaqueNodeIds([group, inside, outside])).toEqual(['outside'])
})
it('marks BOTH when a grouped and an ungrouped terminal overlap each other on a frame', () => {
// z: frame 0, outside 0 (later in the array ⇒ above the frame), inside 1 (above both). So
// `outside` is opaque for lying on the frame, and `inside` for lying on `outside`; the frame
// is skipped for `inside` because it is its ancestor.
const group: StackedNode = {
id: 'g',
type: 'group',
position: { x: 0, y: 0 },
measured: { width: 400, height: 400 }
}
const inside = at('inside', 20, 20, { parentId: 'g' })
const outside = at('outside', 60, 60)
expect(opaqueNodeIds([group, inside, outside])).toEqual(['outside', 'inside'])
})
})
describe('hasActiveGesture / gestureTerminalIds', () => {
const node = (id: string, extra: Partial<StackedNode> = {}): StackedNode => ({
id,
type: 'terminal',
position: { x: 0, y: 0 },
measured: { width: 100, height: 100 },
...extra
})
it('sees a drag and a RESIZE alike', () => {
expect(hasActiveGesture([node('a')])).toBe(false)
expect(hasActiveGesture([node('a', { dragging: true })])).toBe(true)
expect(hasActiveGesture([node('a', { resizing: true })])).toBe(true)
})
it('a gesture on a NON-terminal still freezes (it changes who overlaps whom)', () => {
expect(hasActiveGesture([node('s', { type: 'sticky', dragging: true })])).toBe(true)
expect(gestureTerminalIds([node('s', { type: 'sticky', dragging: true })])).toEqual([])
})
it('names the dragged terminal itself', () => {
expect(gestureTerminalIds([node('a', { dragging: true }), node('b')])).toEqual(['a'])
})
it('names the CHILDREN of a dragged group frame', () => {
// React Flow's getDragItems excludes children of a dragged parent, so they never carry
// `dragging` themselves — without the ancestor walk they stayed transparent all gesture.
const nodes: StackedNode[] = [
node('g', { type: 'group', dragging: true }),
node('c1', { parentId: 'g' }),
node('c2', { parentId: 'g' }),
node('far')
]
expect(gestureTerminalIds(nodes)).toEqual(['c1', 'c2'])
})
it('walks more than one level of frame', () => {
const nodes: StackedNode[] = [
node('outer', { type: 'group', resizing: true }),
node('inner', { type: 'group', parentId: 'outer' }),
node('t', { parentId: 'inner' })
]
expect(gestureTerminalIds(nodes)).toEqual(['t'])
})
it('survives a parentId cycle', () => {
const nodes: StackedNode[] = [node('a', { parentId: 'b' }), node('b', { parentId: 'a' })]
expect(() => gestureTerminalIds(nodes)).not.toThrow()
})
})
describe('setOpaqueNodeIds', () => {
it('answers membership', () => {
setOpaqueNodeIds(['a', 'b'])
expect(nodeIsOpaque('a')).toBe(true)
expect(nodeIsOpaque('c')).toBe(false)
})
it('notifies subscribers when the set changes', () => {
const seen = vi.fn()
const unsub = subscribeOpaqueSet(seen)
setOpaqueNodeIds(['a'])
setOpaqueNodeIds(['a', 'b'])
expect(seen).toHaveBeenCalledTimes(2)
unsub()
})
it('does NOT notify when the same MEMBERSHIP arrives in a different order', () => {
// This is a set, not a sequence: a node reorder that changes nothing about who overlaps whom
// must not wake every terminal on the canvas.
setOpaqueNodeIds(['a', 'b'])
const seen = vi.fn()
const unsub = subscribeOpaqueSet(seen)
setOpaqueNodeIds(['b', 'a'])
expect(seen).not.toHaveBeenCalled()
unsub()
})
it('does NOT notify when the same set is pushed again', () => {
setOpaqueNodeIds(['a', 'b'])
const seen = vi.fn()
const unsub = subscribeOpaqueSet(seen)
setOpaqueNodeIds(['a', 'b'])
expect(seen).not.toHaveBeenCalled()
unsub()
})
it('clears back to empty and notifies once', () => {
setOpaqueNodeIds(['a'])
const seen = vi.fn()
const unsub = subscribeOpaqueSet(seen)
setOpaqueNodeIds([])
expect(seen).toHaveBeenCalledTimes(1)
expect(nodeIsOpaque('a')).toBe(false)
unsub()
})
it('stops notifying after unsubscribe', () => {
const seen = vi.fn()
subscribeOpaqueSet(seen)()
setOpaqueNodeIds(['z'])
expect(seen).not.toHaveBeenCalled()
})
})
describe('primeOpaqueNodeIds / flushOpaqueNodeIds', () => {
it('primes the ANSWER immediately and the NOTIFICATION only on flush', () => {
// This is the ordering fix: Canvas primes during its own render (a listener's setState there is
// what React refuses), so a child reads the current answer while rendering, and the
// notification — needed only by nodes that did not re-render — follows from an effect.
const seen = vi.fn()
const unsub = subscribeOpaqueSet(seen)
primeOpaqueNodeIds(['a'])
expect(nodeIsOpaque('a')).toBe(true)
expect(seen).not.toHaveBeenCalled()
flushOpaqueNodeIds()
expect(seen).toHaveBeenCalledTimes(1)
unsub()
})
it('returns the signature, so the caller can key an effect on it', () => {
expect(primeOpaqueNodeIds(['b', 'a'])).toBe(primeOpaqueNodeIds(['a', 'b']))
})
it('a flush with nothing pending is free', () => {
primeOpaqueNodeIds(['a'])
flushOpaqueNodeIds()
const seen = vi.fn()
const unsub = subscribeOpaqueSet(seen)
flushOpaqueNodeIds()
flushOpaqueNodeIds()
expect(seen).not.toHaveBeenCalled()
unsub()
})
it('coalesces several primes into ONE notification', () => {
const seen = vi.fn()
const unsub = subscribeOpaqueSet(seen)
primeOpaqueNodeIds(['a'])
primeOpaqueNodeIds(['a', 'b'])
primeOpaqueNodeIds(['c'])
flushOpaqueNodeIds()
expect(seen).toHaveBeenCalledTimes(1)
expect(nodeIsOpaque('c')).toBe(true)
expect(nodeIsOpaque('a')).toBe(false)
unsub()
})
})
describe('graceful degrade without a GPU', () => {
/** A plausible xterm device cell (13px font at dpr 2): fractional width, integer height. */
const CELL = { cellW: 15.66, cellH: 31 }
let warn: ReturnType<typeof vi.spyOn>
beforeEach(() => {
warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
})
afterEach(() => {
warn.mockRestore()
})
it('getSharedGlyphContext returns null while the shared mode is off — no context is acquired', () => {
expect(getSharedGlyphContext(CELL)).toBeNull()
})
it('returns null (rather than throwing) when WebGL2/OffscreenCanvas are unavailable', () => {
useSharedGlyph.getState().setEnabled(true)
expect(getSharedGlyphContext(CELL)).toBeNull()
})
it('returns null once the session has failed', () => {
useSharedGlyph.getState().setEnabled(true)
useSharedGlyph.getState().markFailed()
expect(getSharedGlyphContext(CELL)).toBeNull()
})
// The atlas rasterizes into xterm's DEVICE cell, and only a live terminal knows it. A caller
// with no cell to offer (the layer component itself) must therefore adopt an existing context or
// get null — never build one from guessed metrics, which is the mismatch that made every glyph
// resample against the quad it is drawn onto.
it('does not CREATE a context for a caller that supplies no device cell', () => {
useSharedGlyph.getState().setEnabled(true)
const g = globalThis as unknown as Record<string, unknown>
const hadDocument = 'document' in g
const hadOffscreen = 'OffscreenCanvas' in g
const prevDocument = g.document
const prevOffscreen = g.OffscreenCanvas
try {
let constructed = 0
g.document = { createElement: () => ({ style: {}, className: '' }) }
g.OffscreenCanvas = class {
constructor() {
constructed++
}
getContext(): null {
return null
}
}
expect(getSharedGlyphContext()).toBeNull()
expect(constructed).toBe(0)
// …and an unusable cell is the same as no cell: it must not latch the one creation attempt.
expect(getSharedGlyphContext({ cellW: 0, cellH: NaN })).toBeNull()
expect(constructed).toBe(0)
// A usable one does reach construction.
expect(getSharedGlyphContext(CELL)).toBeNull() // no 2d context in this environment
expect(constructed).toBe(1)
} finally {
if (hadDocument) g.document = prevDocument
else delete g.document
if (hadOffscreen) g.OffscreenCanvas = prevOffscreen
else delete g.OffscreenCanvas
useSharedGlyph.getState().markFailed()
useSharedGlyph.setState({ enabled: false, failed: false })
}
})
it('setSharedGlyphCamera is inert without a context', () => {
expect(() => setSharedGlyphCamera({ x: 10, y: 20, zoom: 2 })).not.toThrow()
})
// The absence paths above are the easy half: every guard inside `createContext` RETURNS null.
// A constructor that THROWS instead (a wedged/lost GPU process, a hardened environment that
// raises on canvas construction) took a different route out of `ensureLiveContext` — up through
// whichever node happened to ask for the context first. It must degrade identically.
it('returns null (not a throw) when the OffscreenCanvas constructor THROWS rather than being absent', () => {
const g = globalThis as unknown as Record<string, unknown>
const hadDocument = 'document' in g
const hadOffscreen = 'OffscreenCanvas' in g
const prevDocument = g.document
const prevOffscreen = g.OffscreenCanvas
try {
// `creationAttempted` latches after the first attempt so a machine without a GPU is never
// asked twice; the teardown `markFailed()` runs is the only thing that clears it, and it is
// the supported way to get a fresh attempt out of this module singleton.
useSharedGlyph.getState().setEnabled(true)
useSharedGlyph.getState().markFailed()
useSharedGlyph.setState({ enabled: true, failed: false })
warn.mockClear()
// Past the `typeof document === 'undefined'` guard, so construction is actually attempted.
g.document = { createElement: () => ({ style: {}, className: '' }) }
g.OffscreenCanvas = class {
constructor() {
throw new Error('canvas construction refused')
}
}
expect(getSharedGlyphContext(CELL)).toBeNull()
expect(warn).toHaveBeenCalled()
expect(String(warn.mock.calls[0]?.[0])).toContain('[glyphgrid]')
// A construction throw is "not available here", NOT a session failure: flipping `failed`
// would bump the generation and re-notify every registrant from inside the very call one of
// them is making, and would additionally kill the mode for the rest of the app run.
expect(useSharedGlyph.getState().failed).toBe(false)
} finally {
if (hadDocument) g.document = prevDocument
else delete g.document
if (hadOffscreen) g.OffscreenCanvas = prevOffscreen
else delete g.OffscreenCanvas
// Leave the latch clear so a later test is not silently short-circuited by this one.
useSharedGlyph.getState().markFailed()
useSharedGlyph.setState({ enabled: false, failed: false })
}
})
})
/**
* The BOTH-RENDERERS invariant, tested at the one seam that is reachable headless.
*
* A terminal is either a budget-coordinated per-node WebGL client or a grid on the shared canvas —
* never both (the glyph addon's `setRenderer` and `WebglAddon.dispose()` each silently replace the
* other's renderer) and never neither. `TerminalNode` decides that from `sharedGlyphAvailable()`,
* so the predicate must answer "shared" for a canvas whose context has not been BUILT yet: the
* atlas now adopts a live terminal's device cell, which makes "no context yet" the normal state at
* a fresh mount and again after every font change.
*/
describe('sharedGlyphAvailable', () => {
const CELL = { cellW: 15.66, cellH: 31 }
beforeEach(() => {
// `creationAttempted` is a module singleton that survives a store reset, and only
// `disposeContext()` clears it — which an enable/disable pair runs, silently (unlike
// `markFailed`, which logs). Without this the block would depend on what ran before it.
useSharedGlyph.getState().setEnabled(true)
useSharedGlyph.getState().setEnabled(false)
})
afterEach(() => {
useSharedGlyph.setState({ enabled: false, generation: 0, failed: false })
})
it('is false while the mode is off, and false once the session has failed', () => {
expect(sharedGlyphAvailable()).toBe(false)
useSharedGlyph.getState().setEnabled(true)
useSharedGlyph.getState().markFailed()
expect(sharedGlyphAvailable()).toBe(false)
})
it('is TRUE with the mode on and no context built yet — the fresh-mount state', () => {
useSharedGlyph.getState().setEnabled(true)
// Nothing has asked for a context, so none exists. A probe that reported "not shared" here
// would hand every terminal on the canvas a WebGL budget client moments before each of them
// attaches a grid.
expect(sharedGlyphAvailable()).toBe(true)
})
it('turns false once this machine has PROVED it cannot build a context', () => {
useSharedGlyph.getState().setEnabled(true)
// No OffscreenCanvas in this environment: creation is attempted and produces nothing.
expect(getSharedGlyphContext(CELL)).toBeNull()
expect(sharedGlyphAvailable()).toBe(false)
})
it('is TRUE again after a disposal — a font change must not look like a failure', () => {
useSharedGlyph.getState().setEnabled(true)
expect(getSharedGlyphContext(CELL)).toBeNull() // latches the failed attempt
expect(sharedGlyphAvailable()).toBe(false)
// Mode off → disposeContext() (the same call a font change makes) → the latch is cleared.
useSharedGlyph.getState().setEnabled(false)
useSharedGlyph.getState().setEnabled(true)
expect(sharedGlyphAvailable()).toBe(true)
})
})
/**
* The dpr rebuild. The atlas cell and the baseline are latched at construction, so a window that
* moves between a retina and a 1x display keeps a page rasterized for the display it LEFT — soft on
* one, over-sharp on the other, for the life of the context. Nothing downstream rescues it: the
* grids register with the CSS cell, which is dpr-invariant, so no re-registration is triggered by
* the move. Only a rebuild re-rasterizes, and the rebuild is the FONT change's funnel with a
* different trigger.
*/
describe('pixelRatioChanged', () => {
it('is false for the ratio the atlas was built at', () => {
expect(pixelRatioChanged(2, 2)).toBe(false)
})
it('is true in both directions — retina to 1x and back', () => {
expect(pixelRatioChanged(2, 1)).toBe(true)
expect(pixelRatioChanged(1, 2)).toBe(true)
})
it('ignores float noise — a rebuild costs every grid on the canvas', () => {
expect(pixelRatioChanged(2, 2 + 1e-9)).toBe(false)
})
it('sees the fractional ratios a scaled display reports', () => {
expect(pixelRatioChanged(2, 1.5)).toBe(true)
expect(pixelRatioChanged(1.25, 1.5)).toBe(true)
})
it('treats an unreadable ratio as unchanged, never as a reason to rebuild', () => {
// 0 / NaN come out of a detached window or a broken shim. The atlas we have is the one the
// display we are on asked for; throwing it away on a bad reading is strictly worse than
// keeping it.
expect(pixelRatioChanged(2, 0)).toBe(false)
expect(pixelRatioChanged(2, NaN)).toBe(false)
expect(pixelRatioChanged(2, -1)).toBe(false)
expect(pixelRatioChanged(2, Infinity)).toBe(false)
})
})
describe('syncAtlasPixelRatio', () => {
/** The structural stand-in for a live context — the same trick `AtlasResetSource` uses, so the
* rebuild decision is exercisable without a GPU. In production `disposed` is flipped by
* `disposeContext()` itself, which is what makes the re-entry guard below real. */
const ctx = (dpr: number, disposed = false): { dpr: number; disposed: boolean } => ({
dpr,
disposed
})
it('does nothing while the display has not changed', () => {
expect(syncAtlasPixelRatio(2, ctx(2))).toBe(false)
expect(useSharedGlyph.getState().generation).toBe(0)
})
it('rebuilds on a change, bumping the generation EXACTLY once', () => {
// One bump, because that is the signal every mounted terminal re-registers on. Two would run
// the teardown/setup pair twice for one display change.
expect(syncAtlasPixelRatio(1, ctx(2))).toBe(true)
expect(useSharedGlyph.getState().generation).toBe(1)
})
it('bumps twice for two distinct changes (2 → 1 → 2), each against the FRESH context', () => {
// The second context is a different object because the first was disposed: a display change
// that goes there and back must rebuild both times, not latch after the first.
expect(syncAtlasPixelRatio(1, ctx(2))).toBe(true)
expect(syncAtlasPixelRatio(2, ctx(1))).toBe(true)
expect(useSharedGlyph.getState().generation).toBe(2)
})
it('is inert on a context that is already disposed — the re-entry guard', () => {
expect(syncAtlasPixelRatio(1, ctx(2, true))).toBe(false)
expect(useSharedGlyph.getState().generation).toBe(0)
})
it('a SECOND observer firing on the same display change does not bump again', () => {
// The guard above only means something because of two facts this asserts together, and which a
// pre-disposed literal cannot show. (1) `pushViewport` runs from the ResizeObserver, the window
// `resize` listener AND the resolution media query, and all three close over the SAME context
// object — so the second call sees what the first one did. (2) `disposeContext()` flips
// `disposed` on that live object,
// which is what the guard reads; here that write is stood in for explicitly, since this
// environment can build no real context to dispose.
const same = ctx(2)
expect(syncAtlasPixelRatio(1, same)).toBe(true)
same.disposed = true // ← what `disposeContext()` does to the live context, inside that call
expect(syncAtlasPixelRatio(1, same)).toBe(false)
// One display change, ONE re-registration of every grid on the canvas.
expect(useSharedGlyph.getState().generation).toBe(1)
})
it('does not rebuild on an unreadable ratio', () => {
expect(syncAtlasPixelRatio(0, ctx(2))).toBe(false)
expect(useSharedGlyph.getState().generation).toBe(0)
})
})
/**
* The dpr watcher — the TRIGGER the rebuild above depends on.
*
* `syncAtlasPixelRatio` is only ever reached from `pushViewport`, and the move it exists for (a
* window dragged between a retina and a 1x display at the SAME point size) leaves the host's CSS
* box identical, so the ResizeObserver stays silent and the whole fix rests on whatever else fires.
* xterm does not trust `resize` for this — `CoreBrowserService` watches
* `matchMedia('screen and (resolution: Xdppx)')` — and this suite is what makes the same watch
* testable here, since the component itself has no DOM in this environment.
*
* The part most likely to be got wrong is the RE-ARM: the query string embeds the ratio it was
* built at, so a query armed at 2dppx says nothing once the window is at 1dppx.
*/
describe('createPixelRatioWatcher', () => {
/** A media query list with the two methods we use, and a way to deliver a change. */
class FakeMql {
readonly listeners = new Set<() => void>()
constructor(readonly query: string) {}
addEventListener(_type: 'change', fn: () => void): void {
this.listeners.add(fn)
}
removeEventListener(_type: 'change', fn: () => void): void {
this.listeners.delete(fn)
}
fire(): void {
for (const fn of [...this.listeners]) fn()
}
}
/** A fake display whose ratio can be moved, recording every query the watcher arms. */
const fakeDisplay = (
startDpr: number
): { host: PixelRatioWatchHost; built: FakeMql[]; move(to: number): void } => {
let dpr = startDpr
const built: FakeMql[] = []
return {
host: {
dpr: () => dpr,
match: (query) => {
const mql = new FakeMql(query)
built.push(mql)
return mql
}
},
built,
// The browser order: `devicePixelRatio` is ALREADY the new value when the query that no
// longer matches delivers its change.
move(to: number): void {
dpr = to
}
}
}
it('arms on the ratio it is constructed at, in xterm’s own query form', () => {
const display = fakeDisplay(2)
createPixelRatioWatcher(display.host, () => {})
expect(display.built).toHaveLength(1)
expect(display.built[0]?.query).toBe('screen and (resolution: 2dppx)')
})
it('calls back EXACTLY once for one display change', () => {
const display = fakeDisplay(2)
const onChange = vi.fn()
createPixelRatioWatcher(display.host, onChange)
display.move(1)
display.built[0]?.fire()
expect(onChange).toHaveBeenCalledTimes(1)
})
it('RE-ARMS at the new ratio — a second change still fires', () => {
// The whole reason this is a watcher rather than one `addEventListener` call. The 2dppx query
// is answered once and then never again; without the re-arm the move BACK is silent, and the
// canvas keeps an atlas rasterized for the display it is no longer on.
const display = fakeDisplay(2)
const onChange = vi.fn()
createPixelRatioWatcher(display.host, onChange)
display.move(1)
display.built[0]?.fire()
expect(display.built).toHaveLength(2)
expect(display.built[1]?.query).toBe('screen and (resolution: 1dppx)')
// The spent query is released, so the move back cannot be answered twice.
expect(display.built[0]?.listeners.size).toBe(0)
display.move(2)
display.built[1]?.fire()
expect(onChange).toHaveBeenCalledTimes(2)
expect(display.built[2]?.query).toBe('screen and (resolution: 2dppx)')
})
it('bumps the generation exactly once per change, through the real rebuild funnel', () => {
// End to end for the thing the trigger exists to reach: the watcher's callback is
// `pushViewport`, whose first act is `syncAtlasPixelRatio`. One display change, ONE
// re-registration of every grid on the canvas — and the SECOND change gets its own.
const display = fakeDisplay(2)
let ctx = { dpr: 2, disposed: false }
createPixelRatioWatcher(display.host, () => {
if (syncAtlasPixelRatio(display.host.dpr(), ctx)) {
// What `disposeContext()` + the re-run effect do: the closure meets a FRESH context built
// at the ratio we are now on.
ctx.disposed = true
ctx = { dpr: display.host.dpr(), disposed: false }
}
})
display.move(1)
display.built[0]?.fire()
expect(useSharedGlyph.getState().generation).toBe(1)
display.move(2)
display.built[1]?.fire()
expect(useSharedGlyph.getState().generation).toBe(2)
})
it('stops: the listener is released and a later change reaches nobody', () => {
const display = fakeDisplay(2)
const onChange = vi.fn()
const watcher = createPixelRatioWatcher(display.host, onChange)
watcher.stop()
expect(display.built[0]?.listeners.size).toBe(0)
display.move(1)
display.built[0]?.fire()
expect(onChange).not.toHaveBeenCalled()
})
it('is inert where the environment has no matchMedia at all', () => {
// The node test environment and any hardened shell. Nothing to watch is a correct outcome —
// the `resize` listener is still there — and it must not cost a throw at mount.
const watcher = createPixelRatioWatcher({ dpr: () => 2, match: () => null }, () => {
throw new Error('unreachable')
})
expect(() => watcher.stop()).not.toThrow()
})
it('is inert on a query list that cannot be listened to', () => {
// An ancient shim exposing only the deprecated `addListener` pair. We do not carry a fallback
// for it (nothing else in the repo does), so it degrades to the `resize` trigger alone rather
// than throwing on every mount.
const watcher = createPixelRatioWatcher({ dpr: () => 2, match: () => ({}) }, () => {
throw new Error('unreachable')
})
expect(() => watcher.stop()).not.toThrow()
})
})
/**
* The board gate. The kanban board is a fully opaque overlay over the whole canvas, so every frame
* drawn under it is invisible work — and the idle park cannot help, because a canvas of STREAMING
* terminals under the board never goes quiet.
*
* The real `createFrameLoop` is driven here rather than a mock of it: what is being asserted is
* that a stopped loop really stops (a wake cannot resurrect it) and that a reopened canvas really
* draws, and both of those are the frame driver's contract, not this file's.
*/
describe('boardCoversCanvas', () => {
// The predicate the board frame gate and the blink clock read. It must say "covered" for BOTH
// full-page boards, because Canvas's `kanbanOpen` does: the Omni board was missing,
// so the shared canvas kept drawing under the all-projects board.
const setOmni = (enabled: boolean): void => {
useSettings.setState((s) => ({ settings: { ...s.settings, omniKanbanEnabled: enabled } }))
}
beforeEach(() => {
useViewMode.setState({ viewByProject: {}, defaultView: 'canvas', globalKanban: false })
useProjects.setState({ activeProjectId: 'p1' })
setOmni(false)
})
it('is false on the canvas', () => {
expect(boardCoversCanvas()).toBe(false)
})
it('is true for the active project’s own board', () => {
useViewMode.getState().setView('p1', 'kanban')
expect(boardCoversCanvas()).toBe(true)
})
it('is true for the Omni (all-projects) board', () => {
setOmni(true)
useViewMode.setState({ globalKanban: true })
expect(boardCoversCanvas()).toBe(true)
})
it('is true for the Omni board with no active project — Canvas’s Omni term needs none either', () => {
setOmni(true)
useViewMode.setState({ globalKanban: true })
useProjects.setState({ activeProjectId: '' })
expect(boardCoversCanvas()).toBe(true)
})
it('ignores a stale persisted Omni flag while the feature is off', () => {
useViewMode.setState({ globalKanban: true })
expect(boardCoversCanvas()).toBe(false)
})
it('is false with no active project even when the global default view is the board', () => {
useViewMode.setState({ defaultView: 'kanban' })
useProjects.setState({ activeProjectId: '' })
expect(boardCoversCanvas()).toBe(false)
})
})
describe('createBoardFrameGate', () => {
function harness(): {
host: FrameLoopHost
/** Run every pending rAF callback. */
flushFrames(): number
pendingFrames(): number
drew(): number
loopsMade(): number
makeLoop(): FrameLoop
/** Rows arriving from a terminal: the engine goes dirty whether or not anyone draws it. */
damage(): void
} {
const frames = new Map<number, () => void>()
const timers = new Map<number, () => void>()
let handle = 1
let dirty = false
let drew = 0
let loops = 0
const host: FrameLoopHost = {
frame: () => {
if (!dirty) return false
dirty = false
drew++
return true
},
alive: () => true,
onError: () => {},
requestFrame: (cb) => {
const h = handle++
frames.set(h, cb)
return h
},
cancelFrame: (h) => {
frames.delete(h)
},
setTimer: (cb) => {
const h = handle++
timers.set(h, cb)
return h
},
clearTimer: (h) => {
timers.delete(h)
}
}
return {
host,
flushFrames(): number {
const due = [...frames.entries()]
frames.clear()
for (const [, cb] of due) cb()
return due.length
},
pendingFrames: () => frames.size,
drew: () => drew,
loopsMade: () => loops,
makeLoop: () => {
loops++
return createFrameLoop(host)
},
damage: () => {
dirty = true
}
}
}
it('starts drawing when the board is closed', () => {
const h = harness()
createBoardFrameGate(() => false, h.makeLoop)
expect(h.pendingFrames()).toBe(1)
})
it('schedules NOTHING while the board is up, damage included', () => {
// The point of the whole gate: rows keep arriving under the board and none of them costs a
// frame.
const h = harness()
const gate = createBoardFrameGate(() => true, h.makeLoop)
expect(h.pendingFrames()).toBe(0)
h.damage()
gate.loop().wake()
expect(h.pendingFrames()).toBe(0)
expect(h.drew()).toBe(0)
})
it('stops drawing when the board OPENS, and drops the frame already scheduled', () => {
const h = harness()
let open = false
const gate = createBoardFrameGate(() => open, h.makeLoop)
expect(h.pendingFrames()).toBe(1)
open = true
gate.sync()
expect(h.pendingFrames()).toBe(0)
h.damage()
gate.loop().wake()
expect(h.pendingFrames()).toBe(0)
})
it('draws ONE frame immediately when the board closes — not on the next damage', () => {
// Everything that arrived under the board is still damage on the engine, so the first frame
// after the board closes paints the CURRENT screen. Waiting for the next write would leave a
// finished agent's terminal showing the rows it had when the board went up.
const h = harness()
let open = true
const gate = createBoardFrameGate(() => open, h.makeLoop)
h.damage()
expect(h.pendingFrames()).toBe(0)
open = false
gate.sync()
expect(h.pendingFrames()).toBe(1)
h.flushFrames()
expect(h.drew()).toBe(1)
})
it('hands out the CURRENT loop, so damage wakes the one that is running', () => {
// `createFrameLoop.stop()` is terminal by contract, so leaving the board builds a FRESH loop.
// A damage subscription that captured the original would be waking a corpse for the rest of
// the session — the frozen-canvas failure this gate must not introduce.
const h = harness()
let open = false
const gate = createBoardFrameGate(() => open, h.makeLoop)
const first = gate.loop()
open = true
gate.sync()
open = false
gate.sync()
expect(gate.loop()).not.toBe(first)
// The stopped loop adds nothing to what the fresh one has scheduled…
const scheduled = h.pendingFrames()
first.wake()
expect(h.pendingFrames()).toBe(scheduled)
// …while the one the gate hands out really is the one drawing.
h.damage()
h.flushFrames()
expect(h.drew()).toBe(1)
})
it('a sync with no change costs nothing — no new loop, no lost frame', () => {
const h = harness()
const gate = createBoardFrameGate(() => false, h.makeLoop)
gate.sync()
gate.sync()
expect(h.loopsMade()).toBe(1)
expect(h.pendingFrames()).toBe(1)
})
it('stop() ends it, and a later sync cannot resurrect it', () => {
// Teardown ordering is not guaranteed to beat a store notification that is already in flight.
const h = harness()
let open = true
const gate = createBoardFrameGate(() => open, h.makeLoop)
gate.stop()
open = false
gate.sync()
expect(h.pendingFrames()).toBe(0)
h.damage()
gate.loop().wake()
expect(h.pendingFrames()).toBe(0)
})
})
describe('createCursorBlinkClock', () => {
/**
* Everything the clock touches is injected, so the whole policy — the three gates, the phase, the
* teardown and the damage routing — is exercisable without a DOM, a timer or a GPU.
*
* The fake TARGET damages the engine when it repaints, exactly as the addon's cursor-row repack
* does (`updateRow`/`setCursor` → `markDirty` → the layer's damage subscription). That is the
* whole point of the harness: the trap this task exists to avoid is not visible unless the
* repaint's own damage is modelled.
*/
function blinkHarness(opts: { enabled?: boolean; covered?: boolean } = {}): {
clock: CursorBlinkClock
phases: boolean[]
loop: { wake: ReturnType<typeof vi.fn>; pulse: ReturnType<typeof vi.fn> }
intervalsStarted(): number
intervalsCleared(): number
running(): boolean
tick(): void
focus(name?: string): CursorBlinkTarget
blur(): void
setEnabled(on: boolean): void
setCovered(on: boolean): void
phasesOf(target: CursorBlinkTarget): boolean[]
} {
const phases: boolean[] = []
const perTarget = new Map<CursorBlinkTarget, boolean[]>()
const loop = { wake: vi.fn(), pulse: vi.fn() }
const state = {
enabled: opts.enabled ?? true,
covered: opts.covered ?? false,
target: null as CursorBlinkTarget | null
}
let started = 0
let cleared = 0
let fire: (() => void) | null = null
const clock = createCursorBlinkClock({
enabled: () => state.enabled,
covered: () => state.covered,
target: () => state.target,
loop: () => loop,
setInterval: (cb) => {
started++
fire = cb
return started
},
clearInterval: () => {
cleared++
fire = null
}
})
const focus = (): CursorBlinkTarget => {
const target: CursorBlinkTarget = {
setPhase(visible: boolean): void {
phases.push(visible)
const own = perTarget.get(target) ?? []
own.push(visible)
perTarget.set(target, own)
// The repack dirties the engine, synchronously, from inside `setPhase`.
clock.routeDamage()
}
}
state.target = target
clock.sync()
return target
}
return {
clock,
phases,
loop,
intervalsStarted: () => started,
intervalsCleared: () => cleared,
running: () => fire !== null,
tick: () => fire?.(),
focus,
blur: () => {
state.target = null
clock.sync()
},
setEnabled: (on) => {
state.enabled = on
clock.sync()
},
setCovered: (on) => {
state.covered = on
clock.sync()
},
phasesOf: (target) => perTarget.get(target) ?? []
}
}
it('has no clock at all while no terminal has focus', () => {
// The canvas everybody actually leaves open: terminals on screen, focus in the editor or in
// another app. A clock here would be a repaint twice a second for a cursor nobody is on.
const h = blinkHarness()
h.clock.sync()
expect(h.running()).toBe(false)
expect(h.intervalsStarted()).toBe(0)
})
it('has no clock while the blink setting is off', () => {
const h = blinkHarness({ enabled: false })
h.focus()
expect(h.running()).toBe(false)
})
it('has no clock while the kanban board covers the canvas', () => {
// The board gate has STOPPED the loop, so a phase flip would repack a row nobody draws, every
// 600 ms, for as long as the board is up.
const h = blinkHarness({ covered: true })
h.focus()
expect(h.running()).toBe(false)
})
it('starts one clock when a focused terminal and the setting agree', () => {
const h = blinkHarness()
h.focus()
expect(h.running()).toBe(true)
expect(h.intervalsStarted()).toBe(1)
})
it('alternates the phase, starting from SHOWN', () => {
const h = blinkHarness()
h.focus()
expect(h.phases).toEqual([]) // a freshly focused terminal gets a full period before it hides
h.tick()
h.tick()
h.tick()
expect(h.phases).toEqual([false, true, false])
})
it('repaints through pulse(), NEVER through wake — the park must survive the blink', () => {
// THE test of this task. `wake()` would draw the frame and then hold rAF alive for another
// IDLE_FRAMES_BEFORE_PARK frames, twice a second, forever.
const h = blinkHarness()
h.focus()
h.tick()
h.tick()
expect(h.loop.pulse).toHaveBeenCalledTimes(2)
expect(h.loop.wake).not.toHaveBeenCalled()
})
it('leaves ORDINARY damage on the wake path — only the blink is a one-shot', () => {
// Damage from a terminal writing rows is likely to be followed by more, which is exactly what
// `wake()` is for. Routing everything through `pulse()` would cost a scheduling hop per frame
// of a streaming terminal.
const h = blinkHarness()
h.focus()
h.clock.routeDamage()
expect(h.loop.wake).toHaveBeenCalledTimes(1)
expect(h.loop.pulse).not.toHaveBeenCalled()
})
it('a sync that changes nothing does not restart the interval', () => {
const h = blinkHarness()
h.focus()
h.clock.sync()
h.clock.sync()
expect(h.intervalsStarted()).toBe(1)
expect(h.intervalsCleared()).toBe(0)
})
it('turning the setting off stops the clock and hands the cursor back SHOWN', () => {
// A cursor left in its hidden phase is an invisible cursor for the rest of the session — the
// one way this feature can be worse than not having it.
const h = blinkHarness()
h.focus()
h.tick() // hidden
h.setEnabled(false)
expect(h.running()).toBe(false)
expect(h.phases).toEqual([false, true])
})
it('the board covering the canvas stops the clock the same way', () => {
const h = blinkHarness()
h.focus()
h.tick()
h.setCovered(true)
expect(h.running()).toBe(false)
expect(h.phases).toEqual([false, true])
})
it('losing focus stops the clock, restoring the terminal that had it', () => {
const h = blinkHarness()
const first = h.focus()
h.tick()
h.blur()
expect(h.running()).toBe(false)
expect(h.phasesOf(first)).toEqual([false, true])
})
it('a focus HANDOVER restores the old terminal and starts the new one shown', () => {
// The old target is restored BEFORE it is forgotten — afterwards there is no handle to fix it
// with, and its cursor would stay hidden until something unrelated repacked its row.
const h = blinkHarness()
const first = h.focus()
h.tick() // first is hidden
const second = h.focus()
expect(h.phasesOf(first)).toEqual([false, true])
expect(h.phasesOf(second)).toEqual([])
expect(h.running()).toBe(true)
h.tick()
expect(h.phasesOf(second)).toEqual([false])
})
it('stop() clears the interval, restores the cursor, and a later sync cannot restart it', () => {
// Teardown ordering is not guaranteed to beat a store notification already in flight — the
// same discipline `createBoardFrameGate.stop()` keeps.
const h = blinkHarness()
const first = h.focus()
h.tick()
h.clock.stop()
expect(h.running()).toBe(false)
expect(h.phasesOf(first)).toEqual([false, true])
h.clock.sync()
expect(h.running()).toBe(false)
})
it('matches xterm’s own blink period, so a DOM-rendered terminal beside a shared one agrees', () => {
expect(CURSOR_BLINK_INTERVAL_MS).toBe(600)
})
it('a cursor move during a hidden phase shows the cursor again — through pulse, not wake', () => {
// The restart is a BLINK repaint like any other, so it has to stay inside the bracket. A
// restart routed to `wake()` would be worse than the phase flips this design was built around:
// it happens on every keystroke, not twice a second.
const h = blinkHarness()
h.focus()
h.tick()
expect(h.phases).toEqual([false])
h.loop.pulse.mockClear()
h.loop.wake.mockClear()
h.clock.restart()
expect(h.phases).toEqual([false, true])
expect(h.loop.pulse).toHaveBeenCalledTimes(1)
expect(h.loop.wake).not.toHaveBeenCalled()
})
it('a restart re-arms the period, so the cursor stays solid while you type', () => {
// Showing it again without restarting the interval would leave the cursor solid only until the
// next tick of the OLD period — up to 600 ms, but as little as a millisecond.
const h = blinkHarness()
h.focus()
expect(h.intervalsStarted()).toBe(1)
h.clock.restart()
expect(h.intervalsCleared()).toBe(1)
expect(h.intervalsStarted()).toBe(2)
expect(h.running()).toBe(true)
})
it('a restart starts nothing while a gate is holding the clock stopped', () => {
// `sync` owns the gates. A restart that started an interval here would blink a cursor the
// setting (or the board) has already stopped.
const h = blinkHarness({ enabled: false })
h.focus()
h.clock.restart()
expect(h.running()).toBe(false)
expect(h.intervalsStarted()).toBe(0)
})
it('a restart with nothing focused, and one after stop(), are both inert', () => {
const h = blinkHarness()
h.clock.restart()
expect(h.running()).toBe(false)
h.focus()
h.clock.stop()
h.clock.restart()
expect(h.running()).toBe(false)
})
})
describe('the cursor blink target seam', () => {
afterEach(() => setCursorBlinkTarget(null))
it('notifies on a change and not on a repeat', () => {
const seen = vi.fn()
const off = subscribeCursorBlinkTarget(seen)
const target: CursorBlinkTarget = { setPhase: () => {} }
setCursorBlinkTarget(target)
setCursorBlinkTarget(target)
expect(seen).toHaveBeenCalledTimes(1)
expect(cursorBlinkTarget()).toBe(target)
setCursorBlinkTarget(null)
expect(seen).toHaveBeenCalledTimes(2)
expect(cursorBlinkTarget()).toBeNull()
off()
setCursorBlinkTarget(target)
expect(seen).toHaveBeenCalledTimes(2)
})
it('release only clears the blink for the target that still HOLDS it', () => {
// THE late-blur bug, and the reason the comparison lives in this function rather than in the
// attach shell (which has no unit tests by design): the browser does not promise that the old
// terminal's blur reaches us before the new one's focus, and an unconditional clear would stop
// the cursor of the terminal the user just clicked into.
const a: CursorBlinkTarget = { setPhase: () => {} }
const b: CursorBlinkTarget = { setPhase: () => {} }
setCursorBlinkTarget(a)
setCursorBlinkTarget(b)
releaseCursorBlinkTarget(a)
expect(cursorBlinkTarget()).toBe(b)
releaseCursorBlinkTarget(b)
expect(cursorBlinkTarget()).toBeNull()
})
it('restart notifies only for the target that holds the blink', () => {
// A background terminal streaming output moves its cursor constantly; any of them re-arming the
// focused terminal's period would hold the blink permanently solid.
const seen = vi.fn()
const off = subscribeCursorBlinkRestart(seen)
const a: CursorBlinkTarget = { setPhase: () => {} }
const b: CursorBlinkTarget = { setPhase: () => {} }
setCursorBlinkTarget(a)
restartCursorBlink(b)
expect(seen).not.toHaveBeenCalled()
restartCursorBlink(a)
expect(seen).toHaveBeenCalledTimes(1)
off()
restartCursorBlink(a)
expect(seen).toHaveBeenCalledTimes(1)
})
})
/**
* THE PARK, END TO END — the one constraint the whole blink design exists to satisfy.
*
* The addon's own tests prove it repacks on the caller's stack; the clock's tests above prove it
* routes bracketed damage to `pulse()`. Neither alone proves the FEATURE parks, because the trap
* lives exactly in the seam between them: an addon that repacked one tick later would satisfy both
* and still put an idle canvas back at the display's refresh rate, thirty frames every 600 ms.
*
* So this wires the REAL addon to the REAL clock through a handle that reports damage the way the
* engine does — edge-triggered on the clean→dirty transition, cleared by the frame the loop draws.
* It lives on THIS side of the boundary because the dependency direction is canvas → glyphgrid; the
* fakes come from `glyphgrid/addon-fakes.ts`, which is a plain module rather than a `.test.ts` so
* importing it does not collect the addon's suite a second time.
*/
describe('the blink phase through the real clock', () => {
function wired(): {
core: GlyphGridRendererAddonCore
loop: { wake: number; pulse: number }
intervalsStarted(): number
running(): boolean
tick(): void
frame(): void
/** Does the NEWEST pack of the cursor row carry the block cursor? */
cursorPainted(): boolean
} {
const handle = recordingHandle()
let clock: CursorBlinkClock | null = null
const loop = { wake: 0, pulse: 0 }
// The engine's `markDirty` notifies on the clean→dirty EDGE only, and the FRAME clears the flag
// — neither `wake()` nor `pulse()` draws inline, they schedule. Modelling that (rather than one
// notification per write) is what makes the counts below mean "frames scheduled", which is the
// number the park is about.
let dirty = false
const damage = (): void => {
if (dirty) return
dirty = true
clock?.routeDamage()
}
const damaging: GridHandle = {
...handle,
updateRow(row, cells) {
handle.updateRow(row, cells)
damage()
},
setCursor(cursor) {
handle.setCursor(cursor)
damage()
}
}
let current: CursorBlinkPhaseTarget | null = null
// The attach shell's seam, verbatim in behaviour: claim publishes, release and restart are
// identity-guarded, and a target change re-syncs the clock (the real one does it through the
// layer's subscription).
const seam: CursorBlinkSeam = {
claim(t) {
current = t
clock?.sync()
},
release(t) {
if (current !== t) return
current = null
clock?.sync()
},
restart(t) {
if (current !== t) return
clock?.restart()
}
}
let fire: (() => void) | null = null
let started = 0
clock = createCursorBlinkClock({
enabled: () => true,
covered: () => false,
target: () => current,
loop: () => ({
wake: () => {
loop.wake++
},
pulse: () => {
loop.pulse++
}
}),
setInterval: (cb) => {
started++
fire = cb
return started
},
clearInterval: () => {
fire = null
}
})
const term = fakeTerm({ rows: 4, cols: 4, cursorY: 1, cursorX: 2, focus: true, blink: seam })
const core = new GlyphGridRendererAddonCore(term, damaging, recordingAtlas())
return {
core,
loop,
intervalsStarted: () => started,
running: () => fire !== null,
tick: () => fire?.(),
frame: () => {
dirty = false
},
cursorPainted: () => {
const rec = [...handle.rows].reverse().find((r) => r.row === 1)
if (!rec) throw new Error('the cursor row was never packed')
return (readCell(rec.cells, 2).flags & FLAG_CURSOR) !== 0
}
}
}
it('a phase flip costs ONE pulse and never a wake — the idle park survives the blink', () => {
const h = wired()
// The addon claimed the blink at construction, so the clock is already ticking.
expect(h.running()).toBe(true)
for (let i = 0; i < 3; i++) {
h.tick()
// The frame the pulse scheduled draws and clears the engine's dirty flag, 600 ms before the
// next phase — which is what lets the next flip notify at all.
h.frame()
}
expect(h.loop.pulse).toBe(3)
expect(h.loop.wake).toBe(0)
})
it('ordinary damage from the SAME addon still takes wake()', () => {
// The other half of the routing: only the clock's own bracketed repaint is a pulse. A terminal
// writing rows is likely to be followed by more, and a pulse per write would put a scheduling
// hop in front of every character.
const h = wired()
h.core.renderRows(0, 3)
expect(h.loop.wake).toBe(1)
expect(h.loop.pulse).toBe(0)
})
it('a cursor move during a hidden phase shows the cursor, restarts the period, and pulses', () => {
// xterm holds its own cursor solid while you type; without this the shared renderer kept
// flashing, so a stacked (DOM-rendered) terminal beside a shared one behaved differently in the
// most attention-heavy moment there is — the drift the matched period exists to prevent.
const h = wired()
h.tick()
h.frame()
expect(h.cursorPainted()).toBe(false)
h.core.handleCursorMove()
expect(h.cursorPainted()).toBe(true)
expect(h.intervalsStarted()).toBe(2)
expect(h.loop.pulse).toBe(2)
expect(h.loop.wake).toBe(0)
})
})
describe('installAtlasResetLog', () => {
/** The atlas surface the log reads, with a manual trigger. */
function fakeAtlas(): {
source: AtlasResetSource
fire(): void
subs: number
} {
const cbs = new Set<() => void>()
let count = 0
return {
source: {
get resetCount() {
return count
},
onReset(cb) {
cbs.add(cb)
return {
dispose() {
cbs.delete(cb)
}
}
}
},
fire() {
// The real atlas increments its counter BEFORE it notifies (see GlyphAtlas.reset), which is
// what lets the log line carry the number of the reset it is reporting.
count++
for (const cb of [...cbs]) cb()
},
get subs() {
return cbs.size
}
}
}
let warn: ReturnType<typeof vi.spyOn>
beforeEach(() => {
warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
})
afterEach(() => {
warn.mockRestore()
})
it('logs the first reset immediately, with its number', () => {
const atlas = fakeAtlas()
installAtlasResetLog(atlas.source, () => 0)
atlas.fire()
expect(warn).toHaveBeenCalledTimes(1)
expect(String(warn.mock.calls[0][0])).toContain('[glyphgrid] atlas page reset #1')
})
// Resets are supposed to be RARE. A page too small for the canvas resets on every repack instead,
// and an unthrottled line there would be a console write per frame — which costs frames itself
// and buries the very signal the tester is being asked to report.
it('throttles a burst to one line, and says how many it swallowed', () => {
const atlas = fakeAtlas()
let now = 0
installAtlasResetLog(atlas.source, () => now)
atlas.fire()
now = 100
atlas.fire()
now = 200
atlas.fire()
expect(warn).toHaveBeenCalledTimes(1)
now = 5000
atlas.fire()
expect(warn).toHaveBeenCalledTimes(2)
const line = String(warn.mock.calls[1][0])
expect(line).toContain('#4')
expect(line).toContain('+2')
})
it('does not mention swallowed resets when none were', () => {
const atlas = fakeAtlas()
let now = 0
installAtlasResetLog(atlas.source, () => now)
atlas.fire()
now = 5000
atlas.fire()
expect(warn).toHaveBeenCalledTimes(2)
expect(String(warn.mock.calls[1][0])).not.toContain('+')
})
it('unsubscribes on dispose — the context that installed it is gone', () => {
const atlas = fakeAtlas()
const sub = installAtlasResetLog(atlas.source, () => 0)
expect(atlas.subs).toBe(1)
sub.dispose()
expect(atlas.subs).toBe(0)
atlas.fire()
expect(warn).not.toHaveBeenCalled()
})
})
describe('createContextLossPolicy', () => {
/**
* The whole policy is injected, so the once-only rule, the cooldown and both give-up branches
* are exercisable without a GPU, a canvas or a clock — the same split `createBoardFrameGate`
* and `createCursorBlinkClock` make.
*/
function harness(): {
deps: Parameters<typeof createContextLossPolicy>[0]
at(ms: number): void
suspends(): number
revives(): number
failures(): { reason: string; err?: unknown }[]
/** Make the next `revive()` throw — a driver that will not rebuild. */
breakRevive(): void
/** How many watchdog timers are armed right now. */
pendingTimers(): number
/** Fire every armed timer — "the restore never arrived". */
fireTimers(): void
} {
let clock = 0
let suspends = 0
let revives = 0
let broken = false
let handle = 1
const timers = new Map<number, () => void>()
const failures: { reason: string; err?: unknown }[] = []
return {
deps: {
now: () => clock,
suspend: () => {
suspends++
},
revive: () => {
if (broken) throw new Error('programs would not rebuild')
revives++
},
fail: (reason, err) => {
failures.push({ reason, err })
},
setTimer: (cb) => {
const h = handle++
timers.set(h, cb)
return h
},
clearTimer: (h) => {
timers.delete(h)
}
},
at: (ms) => {
clock = ms
},
suspends: () => suspends,
revives: () => revives,
failures: () => failures,
breakRevive: () => {
broken = true
},
pendingTimers: () => timers.size,
fireTimers: () => {
const due = [...timers.values()]
timers.clear()
for (const cb of due) cb()
}
}
}
let warn: ReturnType<typeof vi.spyOn>
beforeEach(() => {
warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
})
afterEach(() => {
warn.mockRestore()
})
it('a first loss suspends and ASKS for a restore', () => {
// `preventDefault()` is the request for a `webglcontextrestored` event; Phase 1b never made it
// because it had nothing to restore into.
const h = harness()
const policy = createContextLossPolicy(h.deps)
expect(policy.onLost()).toBe(true)
expect(h.suspends()).toBe(1)
expect(h.failures()).toEqual([])
})
it('the restore rebuilds and says so on the console', () => {
// A SILENT restore is indistinguishable from a freeze to whoever is debugging one, which is
// why both branches of this policy warn.
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onLost()
policy.onRestored()
expect(h.revives()).toBe(1)
expect(h.failures()).toEqual([])
expect(warn.mock.calls.map((c: unknown[]) => String(c[0])).join('\n')).toMatch(
/context restored/i
)
})
it('a SECOND loss inside the cooldown falls back permanently — no retry loop, ever', () => {
// The floor under the whole feature, and Phase 1b's behaviour kept as it: a GPU that keeps
// taking the context away must not be handed it back over and over, because that turns one
// failure into a flicker.
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onLost()
policy.onRestored()
h.at(RESTORE_COOLDOWN_MS - 1)
expect(policy.onLost()).toBe(false) // not even asking for a restore this time
expect(h.suspends()).toBe(1) // …and no second suspend
expect(h.failures()).toHaveLength(1)
expect(h.failures()[0].reason).toMatch(/lost again/i)
// Terminal: nothing that arrives afterwards may restore anything.
policy.onRestored()
expect(h.revives()).toBe(1)
expect(policy.onLost()).toBe(false)
expect(h.failures()).toHaveLength(1)
})
it('a loss AFTER the cooldown is restored again — one restore per context', () => {
// The rule is "once per CONTEXT", not "once per session": a machine that sleeps twice in an
// afternoon gets its renderer back both times.
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onLost()
policy.onRestored()
h.at(RESTORE_COOLDOWN_MS + 1)
expect(policy.onLost()).toBe(true)
policy.onRestored()
expect(h.revives()).toBe(2)
expect(h.failures()).toEqual([])
})
it('a restore that THROWS falls back permanently, carrying the error', () => {
// A half-rebuilt context draws nothing, and a canvas of transparent node bodies drawing
// nothing looks exactly like a freeze.
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onLost()
h.breakRevive()
policy.onRestored()
expect(h.failures()).toHaveLength(1)
expect(h.failures()[0].reason).toMatch(/restore threw/i)
expect(h.failures()[0].err).toBeInstanceOf(Error)
// And it is over: a later restore event cannot re-enter the rebuild.
policy.onRestored()
expect(h.revives()).toBe(0)
})
it('a restore we never asked for is ignored', () => {
// The browser can hand a context back on its own after we have given up. Rebuilding there
// would double-create every grid's GPU buffer and leak the first set.
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onRestored()
expect(h.revives()).toBe(0)
expect(h.failures()).toEqual([])
})
it('a restore that NEVER arrives falls back instead of stranding the canvas', () => {
// The worst outcome this policy can produce, and it is worse than the Phase-1b floor it
// promises to keep: suspended engine, stopped runtime, and `failed` still FALSE — so every
// node keeps a transparent body and keeps writing rows into a canvas that paints nothing, for
// the rest of the session, with no second line on the console. `preventDefault()` is only a
// REQUEST, and a synthetic `loseContext()` is never auto-restored at all.
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onLost()
expect(h.pendingTimers()).toBe(1)
h.fireTimers()
expect(h.failures()).toHaveLength(1)
expect(h.failures()[0].reason).toMatch(/never restored/i)
// Terminal, like every other give-up branch: a restore that turns up after we have given up
// must not rebuild anything.
policy.onRestored()
expect(h.revives()).toBe(0)
expect(h.failures()).toHaveLength(1)
})
it('the watchdog is disarmed by a restore that does arrive', () => {
// A timer left running would fail a session that recovered perfectly well.
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onLost()
policy.onRestored()
expect(h.pendingTimers()).toBe(0)
h.fireTimers()
expect(h.failures()).toEqual([])
})
it('the give-up branches arm no watchdog', () => {
// Nothing is waiting for a restore on either terminal path, and a timer that fired afterwards
// would log a second, contradictory reason for the same failure.
const withinCooldown = harness()
const a = createContextLossPolicy(withinCooldown.deps)
a.onLost()
a.onRestored()
withinCooldown.at(RESTORE_COOLDOWN_MS - 1)
a.onLost()
expect(withinCooldown.pendingTimers()).toBe(0)
const throwing = harness()
const b = createContextLossPolicy(throwing.deps)
b.onLost()
throwing.breakRevive()
b.onRestored()
expect(throwing.pendingTimers()).toBe(0)
})
it('the loss itself is announced, not only its outcome', () => {
// The one branch a regression could silence without any assertion going red — and the one a
// device tester reads first, since it is what says "the canvas is blank ON PURPOSE, wait".
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onLost()
expect(warn.mock.calls.map((c: unknown[]) => String(c[0])).join('\n')).toMatch(
/context lost/i
)
})
it('stop() disarms the watchdog, so it cannot fail a session that has moved on', () => {
// The layer unmounts for reasons that have nothing to do with a failure — the mode switched
// off hands the context back and disposes it. A watchdog firing after that would set the
// session's `failed` flag, and re-enabling the mode would then do nothing until a relaunch.
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onLost()
policy.stop()
expect(h.pendingTimers()).toBe(0)
h.fireTimers()
expect(h.failures()).toEqual([])
// …and it is terminal, like every other end state.
expect(policy.onLost()).toBe(false)
policy.onRestored()
expect(h.revives()).toBe(0)
})
it('a duplicate loss for the SAME outage is not a second failure', () => {
// Two `webglcontextlost` events before any restore is one outage, not a GPU that failed twice
// — suspending again would be harmless but failing the session would not.
const h = harness()
const policy = createContextLossPolicy(h.deps)
policy.onLost()
expect(policy.onLost()).toBe(true)
expect(h.suspends()).toBe(1)
expect(h.failures()).toEqual([])
policy.onRestored()
expect(h.revives()).toBe(1)
})
})
/**
* The 2026-08-10 crispness report, and the one measurement that ended it.
*
* `ensureLiveContext` fixes the atlas geometry from the FIRST terminal that registers, for the life
* of the context. In the field every node reported a device cell of 16.79998×36 while the atlas had
* latched to 16×36 — so every glyph was rasterized into a 16px box and drawn into a 16.8px cell, a
* 5% horizontal stretch. That is exactly the 4.9% wider advance measured off screenshots against
* xterm's own WebGL renderer, with the line spacing identical to the pixel because the heights
* agreed. A stretched glyph is wider, heavier AND softer, which is why the report read as "not
* crisp" and survived four other explanations.
*
* Nothing recovered from it: a font change rebuilt the context and a dpr change rebuilt it, but a
* cell that simply disagreed only logged a warning — and a project switch deliberately does not
* rebuild, so the wrong page outlived everything short of an app restart.
*/
describe('atlas cell drift', () => {
it('is a rebuild, not a warning', () => {
// The heights agreeing while the widths do not is the exact field shape, and the reason the
// symptom looked like blur rather than like geometry.
expect(cellsDisagree({ cellW: 16, cellH: 36 }, { cellW: 16.79998779296875, cellH: 36 })).toBe(
true
)
})
it('ignores float noise, so an ordinary canvas never rebuilds', () => {
// Two terminals measuring the same cell must not fight over it; the field dump had per-node
// residuals in the fourth decimal.
expect(cellsDisagree({ cellW: 16.8, cellH: 36 }, { cellW: 16.800001, cellH: 36 })).toBe(false)
expect(cellsDisagree({ cellW: 16.8, cellH: 36 }, { cellW: 16.8, cellH: 36 })).toBe(false)
})
it('catches a HEIGHT-only disagreement too', () => {
expect(cellsDisagree({ cellW: 16.8, cellH: 36 }, { cellW: 16.8, cellH: 38 })).toBe(true)
})
})
/**
* The drift rebuild's loop guard, and the half of it that was missing: it was reset ONLY by a font
* change, so the FIRST drift in a session spent the allowance for the rest of that session.
*
* The consequence is a terminal that stays resampled — soft, 5% wide — for as long as the app runs,
* even though the cause is long gone. The field shape: a webfont resolves after a dpr rebuild has
* latched a fallback face's cell, the drift is genuine, and it is answered with a console warning
* instead of the rebuild it deserves.
*/
describe('createCellRebuildGuard', () => {
it('allows one drift rebuild per epoch and refuses the second', () => {
const guard = createCellRebuildGuard()
expect(guard.allowRebuild()).toBe(true)
expect(guard.allowRebuild()).toBe(false)
expect(guard.allowRebuild()).toBe(false)
})
it('does NOT restore its own allowance — that is what stops a rebuild ping-pong', () => {
// The rebuild the guard permits goes through the same funnel a font change does, so if that
// funnel began a new epoch unconditionally the guard would re-arm itself and two terminals with
// genuinely different cells would hand the atlas back and forth forever, one rebuild per
// registration, with the canvas never painting.
const guard = createCellRebuildGuard()
guard.allowRebuild()
expect(guard.allowRebuild()).toBe(false)
})
it('re-arms on a new epoch, so a LATER genuine drift is still answered', () => {
const guard = createCellRebuildGuard()
expect(guard.allowRebuild()).toBe(true)
expect(guard.allowRebuild()).toBe(false)
// A font change, a dpr rebuild, the mode being switched back on: the old measurement is
// meaningless and the next terminal's cell is a fresh question.
guard.beginEpoch()
expect(guard.allowRebuild()).toBe(true)
})
it('logs the give-up once per epoch, not once per registration', () => {
const guard = createCellRebuildGuard()
guard.allowRebuild()
expect(guard.takeWarning()).toBe(true)
expect(guard.takeWarning()).toBe(false)
guard.beginEpoch()
expect(guard.takeWarning()).toBe(true)
})
it('starts an epoch armed, so the very first drift on a fresh context rebuilds', () => {
expect(createCellRebuildGuard().allowRebuild()).toBe(true)
})
})